문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
170 lines
10 KiB
Markdown
170 lines
10 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`; a merge-blocking contract over non-document repository files is a
|
||
pull-request lane whose inputs are exactly those files (app-bootstrap `repository-contract`).
|
||
`TEST`/`ARCHITECTURE` lanes are cacheable; `INTEGRATION`/`SYSTEM`/`PERFORMANCE` and main-stage
|
||
lanes rerun every time.
|
||
- `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`, `integrationCheck`, `performanceCheck`,
|
||
`releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull
|
||
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
|
||
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
|
||
command removes with `-x` and a command under `continue-on-error` or a non-status `if:` do not
|
||
count — or a folded workflow `run:` block splits an option off its command.
|
||
|
||
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), `performanceCheck` (the declared performance lanes; main and nightly). `ci` (pull
|
||
request) is leaf checks (API surfaces included, owner decision 20) + architectureCheck +
|
||
qualityCheck, and the workflow also runs `verifyStrictLaneStages --dry-run`; `mainCheck` (main branch) is configContractCheck +
|
||
qualificationCheck + the sample web contract + the sample full boot (`:sample-portfolio:systemTest`)
|
||
+ the public-path snapshot + the transport and messaging qualification lanes + the feature
|
||
generator round trip (`verifyFeatureScaffold`) + every leaf's `mainCheck` (document-contract lanes
|
||
and any lane the leaf adds). `releaseCheck` is the tag-only checks: release provenance and the
|
||
public-path snapshot.
|
||
|
||
Test-writing rules (behavior-sentence names that assert what they promise, `@DisplayName` in Korean
|
||
only when the name cannot say it (owner decision 5), 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.
|