문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
13 KiB
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:
domain-coregains framework, transport, database, or cloud dependencies.- A controller directly uses a repository, Spring Data interface, or persistence entity.
- An inbound DTO leaks into
application-coreordomain-core. - Business rules move into mappers, filters, configuration, settings, or controllers.
- Project dependencies violate
src/config/architecture/modules.jsonor the Gradle dependency gate. - Completion is claimed without the relevant verification or a named reason it could not run.
- 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 itsallowed_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 testinputs, and a test that compares a leaf with repository documents is amainStage()lane (tagdocument-contract) in that leaf'smainCheck; a merge-blocking contract over non-document repository files is a pull-request lane whose inputs are exactly those files (app-bootstraprepository-contract).TEST/ARCHITECTURElanes are cacheable;INTEGRATION/SYSTEM/PERFORMANCEand main-stage lanes rerun every time.verifyEnvKeysstays an app-bootstrap task (owner decision 4); its implementation is build-logic'sca.config-contract. Thesrc/build-tools/included build was emptied and removed.src/build.gradle: the root lifecycle (ci,mainCheck,integrationCheck,performanceCheck,releaseCheckand 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-explicitOnlystrict lane is in no stage a workflow executes — a lane the command removes with-x(abbreviations matched as Gradle does) is not covered; a command after which Gradle runs no task (--dry-run,-v,--help,--status,--stop, …, bundles such as-qmincluded), a short-option bundle Gradle rejects (-mx) and a command for another build do not count, nor does one that does not gate for one of three reasons: (1) its failure may not fail its step (an||other than|| exit <non-zero>, a pipe without pipefail, anifcondition, afterset +eor anexit 0trap,continue-on-error, …); (2) it may not run (insideif/for/caseor a function, after a top-level or conditionalexit 0,execorset -n, under a non-statusif:, in a workflow only a request starts or aworkflow_callone no counted job calls, in a job thatneedsa conditional job, …); (3) the check does not read it although its failure would fail the step (|| exit 1, inside{ },( ),$( )orbash -c, after acdit cannot follow, ashell:other than bash or sh, a runner that may be Windows with itspwshdefault, …) — the failure names each command's reason and says to put the stage command on a line of its own; the build a command runs is itsworking-directory, then thecd <relative path>the same shell surely ran before it, joined with-p— or a folded workflowrun:block splits an option off its command.
Commit policy is human-only: agents do not stage, commit, amend, or push implementation changes.
Review and improvement work
Reviewing this repository, fixing defects, refactoring, optimizing, or changing its folder, code or test
structure follows docs/improvement/; adding a feature follows docs/manual/. This is a synchronized
summary of AGENTS.md 「리뷰·개선 작업 기준」; if they drift, AGENTS.md wins.
- Review criteria — this repository's checklist for the 28 viewpoints, what counts as a defect, severity
and evidence levels, the review document format:
docs/improvement/02-review-criteria.md. The general guide is the frontend repository'sdocs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md; it is referenced by section, not copied. - Every finding, Minor included, is fixed or closed by a recorded decision. A fix is followed by a review
of that fix's diff, and the loop repeats until there are no findings
(
docs/improvement/09-working-method.md). - Owner decisions are not asked again. The index is
docs/improvement/08-decisions-records.md; the originals are the decision sections of the review documents. - Where heavy runs (Gradle, Docker, tests, gates) execute and how sessions split the work are the owner's
environment, kept in the 「소유자 환경」 sections of
07-verification-gates.mdand09-working-method.md. - Where the manual and the
AGENTS.mdrules (HARD-STOP, test-writing rules, capability criteria) disagree,AGENTS.mdis right.
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 over production code), testQualityCheck (the same over every test source
set, against config/spotbugs/exclude-test.xml), 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 (which includes testQualityCheck) + 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'smainCheck(document-contract lanes and any lane the leaf adds).releaseCheckis 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.