Clean Architecture review

What this skill is

A catalyst for a conversation, not a mechanised audit. The architectural model is fixed — Clean Architecture, the four rings in reference-clean-architecture.svg. Everything else about each run differs and must be negotiated with the dev in context: the project's language, its size, whether the whole repo is in scope or one subfolder, which tools to use, whether the output is a one-shot report or a permanent guardrail, whether failing rules stay red or get skipped.

If you find yourself running a fixed procedure, stop and ask.

The reference

reference-clean-architecture.svg shows Clean Architecture's two load-bearing ideas: four concentric rings (Entities / Use Cases / Interface Adapters / Frameworks & Drivers), and the dependency rule — source-code dependencies point inward only. The flow-of-control sub-diagram shows how control crosses the inner boundary via input/output ports so the inner rings stay ignorant of the outer ones.

Refer to the image explicitly in the conversation. If the dev has their own rendering of Clean Architecture, prefer theirs.

The shape of the conversation

Anchor on the model. Confirm with the dev that Clean Architecture is the right frame for this project. A short clarifying exchange is better than assuming.

Ask what, where, how deep. You know nothing about the project a priori — language, size, scope, intent. Ask before scanning.

Map code to rings cheaply. Read top-level folders / namespaces / modules and propose a mapping to the four rings. One or two levels deep. Cite paths. Goal: shared vocabulary, not exhaustiveness.

Find candidate violations directionally. Fast scans of imports / using-directives / identifiers against the dependency rule. Be honest: text-level scans are ~85% accurate — they miss fully-qualified references and can false-match on string literals or identifier collisions.

Stop and negotiate strategy before doing anything expensive. This is the step that makes the session worth running. Present the tradeoffs explicitly — do not pick for the dev:

• One-shot vs. permanent guardrail. A written report describes the codebase today and decays on the next commit. An executable architecture test compounds value but costs more to set up. Say this out loud.
• Cheap vs. precise tooling. Propose a range, and surface options the dev may not know about — this is where the skill earns its keep. At the cheap end: grep/bash over imports and using-directives, fast and throwaway. At the precise end: a language-idiomatic static analyzer or architecture-test library that operates at AST/IL level. Look up what currently exists for the language at hand (for example, Roslyn-based frameworks on .NET, ArchUnit for Java/Kotlin, ts-arch or dependency-cruiser for TS, import-linter for Python — verify these are current, add others you find). Name at least one precise option the dev may not know about, and briefly say what it buys them over grep.
• Failing rules on day one. Existing codebases will light up red. Ask whether those failures should stay red (refactor backlog) or be skipped with a ticket reference. Do not default.

Often the right sequence is a cheap one-shot first to see the shape, then a precise permanent check once the dev knows what they want. Offer that path when it fits — and in that case, run both and compare results honestly before committing to the heavier tool.

Execute only what was agreed. Don't bundle features the dev didn't ask for — no CI workflows, severity levels, baseline snapshots, architecture.md docs, or drift-detection tests. If a permanent guardrail is introduced, mention in passing that a coverage test (every top-level module appears in some ring) is the single defence against silent drift — but only act on it if the dev picks it up.

What to avoid

• Running a semantic analyzer before the dev has picked one.
• Assuming language, scope, or size. Ask.
• Treating the beats above as a checklist. They're the shape of a conversation, not a procedure.
• Turning the "map code to rings" step into a full written report by reflex — that's the one-shot path, and the dev may want something else.
• Shipping a fix before the dev has expressed an intent to fix anything.