- 결정 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>
159 lines
9.4 KiB
Markdown
159 lines
9.4 KiB
Markdown
# 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.
|