Files
clean-architecture-backend-…/CLAUDE.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

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

9.1 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.
  • src/build-tools/: only checks not yet moved (verifyEnvKeys, JPA evidence/readiness/release registry). Do not add new checks there.
  • 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 exists; legacy outbox/realtime cutover still has explicitly documented seams in src/messaging/CLAUDE.md.

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). ci (pull request) is leaf checks + architectureCheck + qualityCheck; mainCheck (main branch) is configContractCheck + qualificationCheck + the sample web contract + the public-path snapshot + API surfaces + the transport and messaging qualification lanes

  • the JPA readiness registry; releaseCheck is ci + provenance, archive hygiene 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.