Expose architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep modules. The goal is testability and AI-navigability.
This command is informed by the project's domain model and builds on a shared design vocabulary:
- Invoke the Skill tool and specify
codebase-design, to get the architecture vocabulary (module、interface、depth、seam、adapter、leverage、locality) and its principles (deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Every suggestion uses these terms precisely; do not drift to "component", "service", "API", or "boundary". GLOSSARY.mdThe domain language indocs/adr/record decisions this command should not re-litigate.
Process
1. Explore
First scope the scan: YAGNI. The payoff of deepening a module is making future changes easier, so focus more on areas of the codebase that are still changing recently. Before starting exploration, decide where to look:
- If the user named a direction (module, subsystem, or pain point), explore in that direction and skip the inference below.
- Otherwise, look back over a sufficiently long commit history (
git log --oneline), find recurring files and areas, and make these hot spots the primary focus. If changes are scattered with no obvious hot spot, then widen the scope.
First read the project domain glossary (GLOSSARY.md) and the ADRs for the areas you will touch.
Then spawn a sub-agent to traverse the codebase. Do not apply rigid heuristics; explore naturally and note where you feel friction:
- Does understanding a concept require jumping back and forth among many small modules?
- Which modules are shallow , i.e. their interface is almost as complex as their implementation?
- Are there pure functions extracted for testability, but the real bugs hide in how they are called (no locality)?
- Which tightly-coupled modules leak outside the seams?
- Which parts of the codebase are untested, or hard to test through the current interface?
Apply deletion testto anything you suspect is shallow: would deleting it concentrate complexity, or just move complexity elsewhere? "yes, concentrates" is the signal you want.
2. Present candidates with an HTML report
Write a self-contained HTML file to the OS temp directory, so nothing lands in the repo. Resolve the temp dir from $TMPDIR , fallback to /tmp(on Windows use %TEMP%), write to <tmpdir>/architecture-review-<timestamp>.html, so every run gets a new file. Open it for the user: on Linux use xdg-open <path>, on macOS use open <path>, on Windows use start <path>, and tell the user the absolute path.
The report uses Tailwind via CDN for layout/styling and Mermaid via CDN for diagrams that reliably convey structure. Mermaid and hand-written CSS/SVG visuals can be mixed: use Mermaid when the relationships are graph-shaped (call graphs, dependencies, sequences); use hand-written divs/SVG when you need editorial expression (mass diagrams, cross-sections, collapse animations). Every candidate must have before/after visualisation. Be visual.
Each candidate renders one card, including:
- Files - which files/modules are involved
- Problem - why the current architecture causes friction
- Solution - what will change, described in plain language
- Benefits - explain the benefits in terms of locality and leverage, and how tests will improve
- Before / After diagram - side-by-side, self-drawn, illustrating shallowness and deepening
- Recommendation strength -
Strong、Worth exploring、Speculativeone of, rendered as a badge
The end of the Report includesPreferred recommendation section: which candidate you would tackle first, and why.
Use GLOSSARY.md vocabulary to express the domain, use /codebase-design vocabulary to express architecture. If GLOSSARY.md defines "Order", say "Order intake module", not "FooBarHandler", and not "Order service".
ADR conflicts: if a candidate conflicts with an existing ADR, only raise it if the friction is real enough to warrant reopening the ADR. Mark it clearly in the card (e.g., warning callout:"contradicts ADR-0007 - but worth reopening because..."). Do not list every refactor that the ADR theoretically prohibits.
For the complete HTML scaffold, diagram patterns, and styling guidance, see HTML-REPORT.md。
Do not propose interfaces now. After writing the file, ask the user: "Which of these would you like to explore?"
3. Grilling loop
After the user selects a candidate, invoke the Skill tool and specify grilling, and walk through the decision tree with the user: constraints, dependencies, the shape of the deepened module, what goes behind the seam, and which tests can be preserved.
Side effects happen inline as the decisions take shape; invoke the Skill tool and specify domain-modeling, keeping the domain model up to date:
- Need to name the deepened module with a concept that does not exist in
GLOSSARY.md? Add the term toGLOSSARY.md. If the file does not exist, create it as needed. - Refined a fuzzy term during the conversation? Update immediately
GLOSSARY.md。 - Did the user reject a candidate for a load-bearing reason? Propose writing an ADR, phrased as:"Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only propose it when a future explorer actually needs that reason to avoid making the same suggestion again; skip temporary reasons ("not worth it right now") and obvious reasons.
- Want to explore alternative interfaces for the deepened module? Invoke the Skill tool and specify
codebase-design, and use the design-it-twice parallel sub-agent pattern within it.