Skip to content

chore(claude): refine Clean promotion signal — dependency rule vs project split #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emeraldleaf merged 2 commits into from
Jun 3, 2026
Merged

chore(claude): refine Clean promotion signal — dependency rule vs project split #50

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d724ec
chore(claude): refine the Clean promotion signal — dependency rule vs…
emeraldleaf May 29, 2026
e535f1b
chore(claude): point the promotion-signal rule at the VSA-vs-Clean guide
emeraldleaf May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,10 +95,38 @@ multi-project layout. None of the services are at that scale today and probably
the previous attempt at Clean Architecture in CatalogService was retired specifically
because we hit none of those signals.

**What "promote to Clean" actually means — the dependency rule vs. the project split.** Two
different things wear the name "Clean Architecture," and only one of them is what you'd
promote *to*:

- **The dependency rule** (Domain → nothing; infrastructure/IO at the edges) is *already in
force* in VSA and applies at every scale. It is **not earned, not complexity-gated, and
not what the promotion signal is about** — NextAurora keeps it today as single-project VSA
(see "Layer Dependencies"). Decoupling the domain from frameworks is always worth it.
- **The multi-project structure** (separate Domain/Application/Infrastructure/Api csprojs) is
the only part that carries ceremony, and the only thing the promotion signal gates. All it
buys over single-project VSA is **compile-time enforcement** of the dependency rule via
project references.

So the real axis is *how you enforce the dependency rule*, escalating only as the cost of a
violated boundary rises: **convention → architecture tests → project split.** The middle rung
is the one most teams skip: an **architecture test** (NetArchTest / ArchUnitNET, or a Roslyn
analyzer) asserting "Domain references no EF/Infrastructure namespaces" enforces the *same*
boundary the 4-project split does — deterministically, in CI, **without the project
ceremony**. The project split is therefore rarely needed *for enforcement alone*; reach for it
only when genuine domain complexity makes you want the *compiler* (not a test) to hold the
line, or when separate deploy/versioning units justify it. NextAurora enforces the dependency
rule today via *convention + the architecture-reviewer agent + CodeRabbit*; adding
architecture tests would be the next rung and would make it deterministic **without changing
the VSA shape**. Full portable decision guide (the two meanings of "Clean," the
convention→arch-tests→project-split spectrum, the Testcontainers testing shift, the
duplication tradeoff, when-to-use): [docs/vsa-vs-clean-architecture.md](docs/vsa-vs-clean-architecture.md).

| Signal | Shape |
|---|---|
| ≤4 aggregates per service, ≤10 features, single team | VSA (current default) |
| 5+ aggregates with cross-cutting domain rules that several features coordinate on, AND `Domain/` growing faster than `Features/` | Consider Clean Architecture promotion |
| "I want the dependency rule enforced, not just held by convention" | **Architecture tests** (NetArchTest / analyzer) — NOT a project split. Same boundary, no ceremony |
| 5+ aggregates with cross-cutting domain rules that several features coordinate on, AND `Domain/` growing faster than `Features/` | Consider the multi-project split — when you want the *compiler* to hold the boundary, or need separate deploy/versioning units |
Comment on lines +98 to +129

@coderabbitai coderabbitai Bot May 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Required follow-up for CLAUDE.md rule drift audit.

Run /check-rules locally to audit paraphrases against this diff.

As per coding guidelines, “When this changes, every paraphrase ending in ‘See CLAUDE.md’ elsewhere in the repo may need updating. Flag the CLAUDE.md change with a note: ‘Run /check-rules locally to audit paraphrases against this diff.’”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CLAUDE.md` around lines 98 - 127, Add the required follow-up note to
CLAUDE.md next to the changed section stating: "Run /check-rules locally to
audit paraphrases against this diff." Then run the repository's /check-rules
tool locally to locate all paraphrases that end with "See CLAUDE.md", update any
that now need revised wording, and commit those paraphrase updates; ensure the
note is present near the paragraph that distinguishes "dependency rule" vs
"multi-project structure" so reviewers can see the audit instruction.

| "I want to mock the DbContext in unit tests" | NOT a reason. Use integration tests with Testcontainers; see "Testing" rule |

**Don't apply both patterns uniformly across a single service.** Pick one shape per service
Expand Down
Loading