improve-codebase-architecture

Improve the codebase architecture

Reveal architectural friction points and proposedeepening opportunities— refactorings that turn shallow modules into deep modules. The goal is testability and AI navigability.

This commandreferencesthe project's domain model, and builds on a shared design vocabulary:

• Call the Skill tool and pass "codebase-design" to get the architectural 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"). Use these terms strictly in every recommendation—do not drift to "component", "service", "API", or "boundary".
• GLOSSARY.md provides naming for good seams;docs/adr/ records decisions that this command should not re-litigate.

Process

1. Explore

Determine the scope before scanning—YAGNI. The payoff of deepening a module lies in making future changes to that module easier, so give extra weight to code areas that have changed recently. Before looking, decidewhere to look：

• If the user specified a direction—a module, a subsystem, a pain point—adopt it and skip the inference step below.
• Otherwise, review a longer stretch of commit history (git log --oneline) to find the codebase's hotspots—the files and areas that recur—and let those paths draw your attention first. If changes are scattered with no clear hotspots, widen the scope.

First read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you are about to touch.

Then spawn a subagent to traverse the codebase. Do not follow rigid heuristics—explore organically, and note where you hit friction:

• Where does understanding a concept require jumping back and forth between multiple small modules?
• Which modules areshallow—where the interface is almost as complex as the implementation?
• Where have pure functions been extracted purely for testability, but the real bugs are hidden in how they are called (lack of locality）？
• Which tightly coupled modules cross their seams?
• Which parts of the codebase are untested, or hard to test through the current interface?

Applydeletion testto anything you suspect is shallow: does deleting it concentrate complexity, or merely move it? "Concentrates it" is the signal you want.

2. Present the candidates as an HTML report

Write a self-contained HTML file to the OS temp directory, so no file is left in the repository. Resolve the temp directory from $TMPDIR , falling back to /tmp(on Windows %TEMP%), and write <tmpdir>/architecture-review-<timestamp>.html, so each run gets a new file. Open it for the user—using xdg-open <path>on Linux, open <path>on macOS, start <path>on Windows—and tell the user the absolute path.

The report uses Tailwind (via CDN) for layout and styling, and Mermaid (via CDN) Draw diagrams, using them where graphics/flow/sequence can reliably convey structure. Mix Mermaid with hand-crafted CSS/SVG visuals—use Mermaid when the relationship is a graphic shape (call graphs, dependencies, sequences), and hand-built divs/SVG when you want a more editorial effect (mass diagrams, cross-sections, collapsed animations). Every candidate must have abefore-and-after visualization. Make it visually impactful.

Render one card per candidate, containing:

• Files—which files/modules are involved
• Problem—why the current architecture creates friction
• Approach—describe in plain language what will change
• Benefits—explain in terms of locality and leverage, and how testing will improve
• Before-and-after diagram—show them side by side, custom-drawn, illustrating the shallowness and deepening effects
• Recommendation strength——Strong(strongly recommended),Worth exploring(worth exploring),Speculative(speculative), rendered as a badge

The report ends with aBest recommendationsection: which candidate you would tackle first and why.

Use domain vocabulary from GLOSSARY.md, and for architecture use the /codebase-design vocabulary. If GLOSSARY.md defines "Order", say "Order intake module"—not "FooBarHandler", and not "Order service".

ADR conflicts: if a candidate contradicts an existing ADR, bring it up only when the friction is truly severe enough to warrant revisiting the ADR. Clearly flag it in the card (for example, a warning prompt:"Contradicts ADR-0007—but worth reopening because..."). Do not list every theoretical refactoring that an ADR forbids.

See HTML-REPORT.md for the complete HTML scaffolding, diagram patterns, and styling guidance.

After writing the file, do not propose an interface yet. Ask the user: "Which approach would you like to explore?"

3. Grilling loop

Once the user selects a candidate, call the Skill tool and pass in "grilling" to walk the decision tree with them—constraints, dependencies, the shape of the deepened module, what is behind the seam, which tests will survive.

Side effects occur immediately when a decision is made—call the Skill tool and pass in "domain-modeling" to keep the domain model up to date:

• Name a deepened module with a concept that does not exist in GLOSSARY.md ? Add that term to GLOSSARY.md. If the file does not exist, create it later.
• Clarified an ambiguous term during the conversation? Immediately update GLOSSARY.md。
• Did the user reject a candidate for an important reason? Propose creating an ADR, worded as:"Would you like me to record this as an ADR, so that future architecture reviews do not raise this suggestion again?" Only propose it if the reason is truly useful in practice for helping future explorers avoid raising the same suggestion again—skip temporary reasons ("not worth doing now") and self-evident reasons.
• Want to explore an alternative interface for the deepened module? Call the Skill tool and pass in "codebase-design" and use its design-it-twice parallel sub-agent mode.