init: 클린 아키텍처 백엔드
This commit is contained in:
DongHyeonka
@@ -0,0 +1,119 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
./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.
|
||||
Reference in New Issue
Block a user