Files
clean-architecture-backend-…/CLAUDE.md
T
donghyeon-kaandClaude Opus 5.5 423a29c46f review-followup Wave 3 라운드 2(P18): outbox canonical 통일, composition 모듈, legacy Kafka seam 삭제
- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
  durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
  sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
  composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 12:30:01 +09:00

159 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
Repository guidance for the Java 21 + Spring Boot 4.0.8 Clean Architecture template.
## Prime Directive
Preserve architecture before optimizing for speed. The following seven HARD-STOP conditions are a
synchronized summary of the canonical local policy in `AGENTS.md`:
1. `domain-core` gains framework, transport, database, or cloud dependencies.
2. A controller directly uses a repository, Spring Data interface, or persistence entity.
3. An inbound DTO leaks into `application-core` or `domain-core`.
4. Business rules move into mappers, filters, configuration, settings, or controllers.
5. Project dependencies violate `src/config/architecture/modules.json` or the Gradle dependency
gate.
6. Completion is claimed without the relevant verification or a named reason it could not run.
7. A repository/corpus conclusion is made without evidence proportional to its scope and risk.
If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must be resynchronized.
## Gradle policy authorities
- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source
paths, Gradle paths and allowed production project dependency edges. There is no runtime
membership list: what a composition root may take is its `allowed_dependencies`, and the direction
gate refuses any other edge. The registry owns the leaf list and its size; no document restates
the count, because a number written in prose drifts the moment a leaf is added.
- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test
that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`)
in that leaf's `mainCheck`.
- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's
`ca.config-contract`. The `src/build-tools/` included build was emptied and removed.
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `releaseCheck` and the named
repository-wide gates).
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
## Proportional workflow
- Low risk: work in the owning leaf, follow its nearest guidance, and run the focused check.
- Medium risk: use the relevant Superpowers design, planning, TDD, debugging, and review workflows
in proportion to the affected boundaries.
- High risk: make architecture and behavior decisions explicit, use staged architecture/spec/quality
review, and run architecture-wide verification authorized by the task.
Risk comes from change surface and runtime, security, data, or public-contract impact, not file
count.
## Module families
`src/config/architecture/modules.json` owns the complete leaf list. Root guidance summarizes
families; the nearest `src/**/CLAUDE.md` owns local rules. No task enforces this any more:
`verifyDocumentedLeafCount` was deleted along with the other documentation-drift parsers. A stated
count that disagrees with the registry is a defect, not a build failure — so do not state one.
| Family | Responsibility | Stable dependency direction |
| --- | --- | --- |
| `domain-core` | Pure domain model, invariants, events, ports | Java stdlib and registered value-only contracts |
| `application-core` | Commands, use cases, application policies, transaction ports | `domain-core`, `shared-contract` |
| `adapter:inbound:*` | HTTP, gRPC, GraphQL, WebSocket transport boundaries | application/domain/shared contracts |
| `adapter:outbound:persistence-*` | JPA/PostgreSQL and MongoDB persistence adapters | application/domain/shared contracts as registered |
| `adapter:outbound:*` | support, messaging, cache, notification, storage, file, HTTP client, identifier capabilities | application/domain/shared and registered support edge |
| `shared-contract` | Skeleton-wide operational contracts | Java stdlib only |
| `messaging:*` | Vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this application | `messaging:*` only — it depends on no `domain-core`, `application-core`, or `shared-contract` type |
| `sample-portfolio` | Fixture/reference consumer | registered runtime leaves; never a production dependency |
| `app-bootstrap` | Spring Boot entrypoint and composition root | registered runtime leaves |
The `messaging:*` family is the one entry that is not a Clean Architecture layer, and it is listed so
that the exception is stated rather than inferred from a directory. It is a vendored library — its
own `*-api` leaves are its ports, its broker leaves are its adapters, its starter is its composition
root — and the messaging module review (`docs/reviews/2026-08-14-messaging-module-code-review.md`
MSG-023 §6.2) chose that layout deliberately over folding it into `adapter:outbound:*`. This
application reaches it through the application-owned anti-corruption bridge in
`adapter:outbound:messaging` (MSG-015). The canonical bridge is the only path: the legacy outbox
append port and the legacy Kafka publishing seam were deleted (owner decision 7).
Never infer an individual leaf's Gradle path, allowed dependency, or test command from this table.
Read its `gradle_path` and `allowed_dependencies` from `src/config/architecture/modules.json`; runtime
composition is established by actual Gradle dependencies/auto-configuration, not a registry
`runtime_memberships` field that does not exist.
## Layer workflow
For a full use case, work in this order:
```text
domain-core
-> application-core
-> adapter:outbound:* (or persistence/identifier)
-> adapter:inbound:*
-> app-bootstrap wiring
```
Layer-only work stays inside that registered leaf plus its tests. If a required fix crosses a layer
or writable scope, stop and request context rather than expanding silently.
## Testing
- `domain-core`: pure JUnit unit tests.
- `application-core`: use-case tests with hand-rolled fakes; no web or persistence context.
- inbound adapters: focused transport slice/contract tests.
- persistence adapters: mapping/port contract tests; use a real datastore only when vendor semantics
require it.
- other outbound adapters: port contract tests with fake external systems; no real network.
- identifier: pure deterministic unit tests.
- bootstrap/settings: binding, validation, wiring, and architecture tests.
From `src/`, read the owning leaf's `gradle_path` from
`config/architecture/modules.json` and run `./gradlew <gradle-path>:test --console=plain`.
Architecture-wide commands:
```bash
./gradlew architectureCheck --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
./gradlew verifyPublicPathSnapshot --console=plain
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
```
A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone.
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
(SpotBugs, FindSecBugs), `configContractCheck` (the environment contract), `integrationCheck` (the
declared strict integration lanes; a lane that needs an input the build was not given is left out
and named). `ci` (pull request) is leaf checks (API surfaces included, owner decision 20) +
architectureCheck + qualityCheck; `mainCheck` (main branch) is configContractCheck +
qualificationCheck + the sample web contract + the public-path snapshot + the transport and
messaging qualification lanes + every leaf's `mainCheck` (document-contract lanes, MinIO lanes);
`releaseCheck` is the tag-only checks: release provenance and the public-path snapshot.
Test-writing rules (behavior-sentence names that assert what they promise, given/when/then comments,
one `// when`, one fake per port in the port owner's testFixtures, fake and adapter sharing one
abstract contract test) are canonical in `AGENTS.md`.
Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
requires the controller's workflow authorization.
## Capability modules
Optional features (JPA, Redis, Kafka, notification, Mongo, object storage, HTTP client, GraphQL,
WebSocket, gRPC, file server) are modules that turn on when present and disappear when removed. A
service selects them with one `runtimeOnly` line each in `app-bootstrap/build.gradle`; the template's
default composition is the web inbound adapter, observability, the cores, and support/identifier. The
seven completion criteria for a capability module are canonical in `AGENTS.md`.
## Advisory and reporting
Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many
exist; use fewer when the option set is smaller. Judgment findings include falsifiable assumptions
and counterarguments. Deterministic compile, dependency, secret, or failed-test findings use
Rule → Evidence → Fix without manufactured debate.
Citation verification is profile-based: none for `review-lite`, blocking citations for
`review-standard`, and all material citations for `audit-deep`/`regulated`. Durable reports are
triggered by high risk, at least 3 blocking findings, an architecture decision, explicit user request,
or the regulated profile. Otherwise a concise result is allowed.