Claude Code Guide

Claude Code Guide

ABSOLUTE REQUIREMENT FOR ALL AI AGENTS: Before generating any code, you MUST read hexagonal-architecture.md, ddd.md, clean-code.md, kotlin-code-style.md or java-code-style.md, observability.md, security.md, and spring-boot.md. Failure to follow the hexagonal architecture patterns produces architecturally invalid code. EVERY class MUST be placed in the correct layer. EVERY dependency MUST point inward (domain ← application ← infrastructure ← bootstrap).

FIRST STEP FOR NEW PROJECTS: verify all resource files exist per resources.md. If missing, generate them FIRST.

Project-agnostic: code samples use placeholder package com.example.platform and service name platform-service. Replace with your project’s actual values when applying patterns.

This file is the index. Concrete step-by-step content lives in the four themed files below.

Themed Files

Required Reading Order

Before making any changes, read these guides in order:

1. hexagonal-architecture.md — Hexagonal architecture, ports, adapters, outbox, chain of responsibility.
2. ddd.md — Domain-Driven Design concepts.
3. clean-code.md — Clean code principles, transaction patterns.
4. kotlin-code-style.md — fun interface, extension functions, data class. (Kotlin projects)
5. java-code-style.md — interfaces, static methods, record. (Java projects)
6. observability.md — metrics, logging, distributed tracing.
7. security.md — AuthN/Z, secrets, validation, audit.
8. api-design.md — REST conventions, versioning, error envelope (for endpoints).
9. spring-boot.md — Spring Boot integration patterns.
10. resources.md — required resource files for each module.
11. This guide — feature workflow + bug-fix patterns (themed files above).

Architecture Quick Reference

1
platform-service/
2
├── domain/                          # Pure domain models, zero dependencies
3
│   ├── Organization.kt
4
│   ├── User.kt
5
│   └── support/OutboxMessage.kt
6
│
7
├── application/                     # Use cases and ports, depends on domain only
8
│   ├── port/
9
│   │   ├── inbound/                # Entry point contracts
10
│   │   │   └── CreateOrganizationPort.kt
11
│   │   └── outbound/               # Dependency contracts
12
│   │       └── repository/
13
│   │           ├── OrganizationRepositoryPort.kt
14
│   │           └── support/TransactionPort.kt
15
│   │       # NO publisher/ folder — OutboxRepositoryPort + MessagePublisherPort
16
│   │       # + OutboxEventFactory ship in codehuntersio-sdk-event-messaging.
17
│   └── usecase/
18
│       └── CreateOrganizationUseCase.kt
19
│
20
├── infrastructure/
21
│   ├── entry-points/               # Inbound adapters
22
│   │   ├── rest-controller/        # HTTP endpoints
23
│   │   ├── kafka-consumer/         # Message consumers
24
│   │   └── scheduler-task/         # Background jobs
25
│   └── driven-adapters/            # Outbound adapters
26
│       ├── jdbc-repository/        # Database
27
│       ├── kafka-producer/         # Messaging
28
│       ├── redis-cache/            # Caching
29
│       └── metrics-publisher/      # Observability
30
│
31
└── bootstrap/                      # Spring Boot wiring
32
    ├── MainApplication.kt
33
    └── config/
34
        ├── UseCaseConfig.kt
35
        ├── JdbcConfig.kt
36
        └── KafkaConfig.kt

Workflow Index

Adding a new feature (end-to-end):

1. ccg-domain-and-ports.md §Step 1 — domain model (if needed).
2. ccg-domain-and-ports.md §Step 2 — inbound + outbound ports + command.
3. ccg-domain-and-ports.md §Step 3 — use case implementation.
4. ccg-adapters-and-wiring.md §Step 4 — REST / JDBC / Kafka / metrics adapters.
5. ccg-adapters-and-wiring.md §Step 5 — bootstrap Spring config.

Fixing a bug:

• ccg-bugfix-and-testing.md — failing test first, then minimal fix.

Writing tests:

• ccg-bugfix-and-testing.md §Testing Patterns — use case (mocked ports) + Testcontainers integration.
• testing.md — full strategy: TDD, Karate, ArchUnit, coverage.

Common smaller tasks (new entity, new repo method, cache, metrics, background job):

• ccg-reference.md §Common Tasks.

Avoiding anti-patterns:

• ccg-reference.md §Common Mistakes.

Pre-merge checks:

• ccg-reference.md §Checklist.

Dependency Direction Quick Reference

1
┌───────────────┐
2
│   domain      │  ← pure logic, no framework, no I/O
3
└───────▲───────┘
4
        │ depends on
5
┌───────┴───────┐
6
│  application  │  ← use cases + ports, depends on domain only
7
└───────▲───────┘
8
        │ depends on
9
┌───────┴───────┐
10
│ infrastructure│  ← adapters, frameworks, I/O, implements ports
11
└───────▲───────┘
12
        │ depends on
13
┌───────┴───────┐
14
│   bootstrap   │  ← Spring Boot wiring, all module deps
15
└───────────────┘

Never reverse. Domain MUST NOT import Spring, JPA, Kafka, Jackson, anything framework. Application MUST NOT import infrastructure. Infrastructure MAY import application + domain. Bootstrap MAY import everything.

ArchUnit enforces this at build time per testing.md §3.3.

Companion Commands & Agents

Getting Started Quickly

To understand the codebase: read hexagonal-architecture.md, then ccg-reference.md §Dependency Direction.

To add a feature: follow ccg-domain-and-ports.md → ccg-adapters-and-wiring.md → tests per ccg-bugfix-and-testing.md.

To fix a bug: ccg-bugfix-and-testing.md — RED test first, then minimal fix, then full test pass.

Remember: when in doubt, read the layer rules and follow existing patterns. Consistency over cleverness.