clean-architecture-backend-template/CLAUDE.md

CLAUDE.md

Repository guidance for the Java 21 + Spring Boot 4.0.0 Clean Architecture template.

Prime Directive

Preserve architecture before optimizing for speed. The HARD-STOP SSOT is .agents/plugins/ca-superpowers/rules/clean-architecture.md; its eight current stop conditions are:

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 .harness/project/modules.yaml and Gradle verification.
6. Completion is claimed without the relevant verification or a named reason it could not run.
7. A corpus conclusion is made without evidence appropriate to the selected evidence profile.
8. Non-trivial work closes without the required LLM Wiki capture or a reported capture block.

If this summary and the SSOT differ, the SSOT wins.

Harness policy authorities

• Project manifest and stack: .harness/manifest.yaml
• Leaf modules, dependency edges, and focused commands: .harness/project/modules.yaml
• Risk classification: .harness/core/risk-policy.yaml
• Evidence selection: .harness/core/evidence-policy.yaml
• Orchestration and advisory depth: .harness/core/review-policy.yaml
• Durable/concise reporting: .harness/core/report-policy.yaml
• Physical parity check: .harness/validators/validate_policy_parity.py

Resolve a task packet once and reuse its stable task-packet hash and relevant rule hashes. Rerun resolution or reread a full rule only when the task overlay, packet hash, or rule hash changes.

Commit policy is human-only: agents do not stage, commit, amend, or push implementation changes.

Risk-based orchestration

• Low risk: implement inline or in a focused lane and run the focused check.
• Medium risk: use ca-implementer; select proportional review based on affected boundaries and evidence needs.
• High risk: use ca-implementer, then the full chain after a human commit: ca-architect-sentinel → ca-spec-reviewer → ca-quality-reviewer → gradle-runner.

Risk comes from change surface and task flags, not file count.

Module families

.harness/project/modules.yaml owns the complete 19-leaf list. Root guidance summarizes families; the nearest src/**/CLAUDE.md owns local rules.

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
sample-portfolio	Fixture/reference consumer	registered runtime leaves; never a production dependency
app-bootstrap	Spring Boot entrypoint and composition root	registered runtime leaves

Never infer an individual leaf's Gradle path, allowed dependency, or test command from this table. Read it from .harness/project/modules.yaml or from the resolved task packet.

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/, run the exact focused command emitted in the task packet. Architecture-wide commands:

./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest' --console=plain
./gradlew verifyPublicPathSnapshot --console=plain
./gradlew verifyEnvKeys --console=plain

Use public-path and env-key checks only when their surfaces changed. Full test or check requires the controller's workflow authorization.

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.

LLM Wiki capture

For non-trivial implementation or workflow changes, follow .agents/plugins/ca-superpowers/rules/llm-wiki-capture.md. If the controller explicitly excludes wiki writes for a dispatched task, report the handoff instead of writing outside scope.