Files
clean-architecture-backend-…/CLAUDE.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

11 KiB
Raw Blame History

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 (abbreviations matched as Gradle does), a command under continue-on-error or a non-status if:, and a workflow_dispatch-only workflow do not count; the build a command runs is its working-directory joined with -p — 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:

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:

./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.