Files
clean-architecture-backend-…/CLAUDE.md
T
DongHyeonka e6b6e18eae fix(strict-lane)!: 성능 lane이 상한을 재지 않고 통과하지 못하게 한다
문제: 성능 lane의 기계 의존 상한(httpclient 스트리밍 힙 증가, Mongo 시간
gate)이 performance.assertions.enabled 뒤에 있었고 기본값이 자리마다
달랐다(httpclient build false, Mongo build true, Mongo 테스트 코드 false).
workflow만 GRADLE_OPTS로 켰다. 그래서 desktop에서 손으로 돌린
./gradlew :performanceCheck가 httpclient 힙 상한을 재지 않고 통과했다
(2026-11-05 r10 게이트). JPA pool lane도 전에 같은 속성 뒤에서 아무 상한도
비교하지 않았다(PoolLaneClaimTest).

방법: 규칙을 build-logic strict-lane convention 한 곳에 둔다.
- PERFORMANCE lane 테스트 JVM에 performance.assertions.enabled=true를
  넣는다. 빌드(-P, GRADLE_OPTS)나 lane(systemProperty, jvmArgs, task
  설정)이 true 아닌 값을 주면 테스트 전에 실패하고, 지우거나 true로
  바꾸라고 알려 준다. true는 받아 준다(파생 서비스 workflow가 넘긴다).
- PERFORMANCE lane은 skip된 테스트가 있으면 실패한다.
- httpclient·Mongo 테스트는 조건 없이 단언하고 잰 값을 한 줄 남긴다.
  두 leaf의 속성 선언과 integration-main·release workflow의 GRADLE_OPTS
  줄을 지웠다. 사람과 workflow가 같은 명령을 쓴다. verifyStrictLaneStages가
  읽는 run: 줄은 그대로다.
버린 대안: 두 leaf 기본값만 true로(정의가 leaf마다 남아 다음 lane이 다시
복사한다), 속성 삭제만(옛 속성을 기본값 false로 읽는 파생 서비스 테스트가
조용히 건너뛴다), 측정 전용 태스크(쓸 곳이 없다: 숫자만 볼 때는 JMH, 실패한
단언과 매 실행 출력이 값을 남긴다).
같은 원인으로 함께 고친 문서: httpclient support-matrix·release-checklist의
없는 lane 이름 spring62CompatibilityTest와 빠진 main push 주기.

위험·한계: 손으로 돌린 performanceCheck가 이제 상한을 실제로 재므로 느린
기계에서는 실패할 수 있다. JVM 인자 공급자(jvmArgumentProviders)가 넣는
-D는 보지 않는다. Docker가 없을 때 skip되는 통합·시스템 lane은 지금
모두 실패한다(전부 skip이면 executed no test, 아니면 skip 안 되는 컨테이너
테스트가 실패) — 거짓 통과가 아니어서 고치지 않았다.

검증(desktop ~/b4-logs, flock 아래, 노트북과 같은 트리 — git diff sha256 일치):
- RED(고치기 전 트리 + 새 테스트): build-logic 새 테스트 4건이
  UnexpectedBuildSuccess로 실패 — aPerformanceLaneFailsOnAnExceededBound
  WhenTheBuildSetsNoAssertionsProperty, …FailsBeforeTestingWhenTheBuild
  TurnsItsAssertionsOff, …FailsWhenItsOwnDeclarationTurnsTheAssertionsOff,
  …FailsWhenOneOfItsTestsIsSkipped. jvmArgs 경로(…FailsWhenItsJvmArguments
  TurnTheAssertionsOff)도 같은 실패. 실제 lane: 속성 없이
  httpClientPerformanceTest rc=0인데 "skipped machine-dependent bound" 출력.
- GREEN: -p build-logic check javadoc rc=0. :performanceCheck rc=0(lane 5개
  테스트 26, skip 0; httpclient 힙 증가 5,243,880 B / 상한 16,777,216 B,
  Mongo p50·p95·p99 1ms, examined/returned 1.0, pool 대기 0).
  -p optional-platforms performanceCheck rc=0(grpc 1). 두 명령에
  -Pperformance.assertions.enabled=false → rc=1, 6개 lane 모두 테스트 전
  실패. =true → rc=0. verifyStrictLaneStages --dry-run 두 빌드 rc=0,
  architectureCheck rc=0, ci·mainCheck·integrationCheck·releaseCheck·
  performanceCheck --dry-run --configuration-cache rc=0,
  :mainCheck --continue --warning-mode=fail rc=0, -p optional-platforms ci
  rc=0, persistence-mongo:check rc=0, verify-httpclient-docs.py rc=0.
- 이 변경 밖 실패: :ci :verifyDependencyLocks --continue와
  httpclient:check가 CircuitBreakerStatusAccountingTest JDK 2건으로 rc=1.
  기준 커밋 3d73b6f1에서도 10/10 실패(이 트리도 10/10). ci의 다른
  task는 모두 통과했다.

Refs: docs/upgrade/2026-11-maturity-review.md B-43, docs/testing/TESTING_STRATEGY.md 6절
BREAKING CHANGE: PERFORMANCE lane은 performance.assertions.enabled가
true가 아니거나 skip된 테스트가 있으면 실패한다. 자기 성능 lane의 그 속성
선언(false)과 skip을 없앤다.
2026-11-06 20:33:47 +09:00

12 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. A PERFORMANCE lane asserts its bounds in every run and rejects skipped tests: the convention sets performance.assertions.enabled=true, and a build or lane that sets anything else fails before a test runs.
  • 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) is not covered; a command after which Gradle runs no task (--dry-run, -v, --help, --status, --stop, …, bundles such as -qm included), 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, an if condition, after set +e or an exit 0 trap, continue-on-error, …); (2) it may not run (inside if/for/case or a function, after a top-level or conditional exit 0, exec or set -n, under a non-status if:, in a workflow only a request starts or a workflow_call one no counted job calls, in a job that needs a conditional job, …); (3) the check does not read it although its failure would fail the step (|| exit 1, inside { }, ( ), $( ) or bash -c, after a cd it cannot follow, a shell: other than bash or sh, a runner that may be Windows with its pwsh default, …) — 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 its working-directory, then the cd <relative path> the same shell surely ran before it, 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 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, bounds always asserted — the same command by hand or in a workflow; 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'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.