improve-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- improve-codebase-architecture
- description
- Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- disable-model-invocation
- true
02 资源文件 2
- 参考文档HTML-REPORT.md10.9 KB
- 参考文档report.html15.3 KB
03 SKILL.md 正文
Improve Codebase Architecture
Surface architectural friction, propose deepening opportunities: refactors turning shallow modules into deep ones. Aim: testability and AI-navigability.
Command informed by project domain model, built on shared design vocabulary:
- Call Skill tool with
groundwork:codebase-designfor architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and principles (deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion. No drift into "component," "service," "API," "boundary." - Domain language in
GLOSSARY.mdnames good seams. ADRs indocs/adr/record decisions this command must not re-litigate.
Process
1. Explore
Scope before scan: YAGNI. Deepening module pays off by easing future changes, so weight recently changed parts extra. Decide where to look before looking:
- User named direction (module, subsystem, pain point)? Take it, skip inference below.
- Else walk back good stretch of commit history (
git log --oneline) to find hot spots: files/areas that keep coming up. Let those paths pull attention first. Changes scattered, no clear hot spot? Widen net.
Read domain glossary (GLOSSARY.md) and any ADRs in touched area first.
Then spawn sub-agent to walk codebase. No rigid heuristics; explore organically, note where friction felt:
- Where does understanding one concept require bouncing between many small modules?
- Where are modules shallow, interface nearly as complex as implementation?
- Where were pure functions extracted just for testability, but real bugs hide in how they're called (no locality)?
- Where do tightly-coupled modules leak across seams?
- Which parts untested, or hard to test through current interface?
Apply deletion test to suspected shallow things: would deleting concentrate complexity, or just move it? "Yes, concentrates" = wanted signal.
2. Present candidates as an HTML report
Write self-contained HTML file to OS temp dir so nothing lands in repo. Resolve temp dir from $TMPDIR, fallback /tmp (or %TEMP% on Windows), write to <tmpdir>/architecture-review-<timestamp>.html so each run gets fresh file. Open for user (xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows), tell them absolute path.
Report starts as copy of report.html: fixed stylesheet setting look, plus Mermaid pinned from CDN for diagrams where graph, flow or sequence shows structure. Write only body. Mix Mermaid with scaffold's hand-built visuals: Mermaid when relationships graph-shaped (call graphs, dependencies, sequences); core samples, cross-sections or collapse boxes when point is depth. Each candidate gets before/after visualisation. Be visual.
Per candidate, render card with:
- Files: files/modules involved
- Problem: why current architecture causes friction
- Solution: plain English description of change
- Benefits: in terms of locality and leverage, plus how tests improve
- Before / After diagram: side-by-side, custom-drawn, showing shallowness and deepening
- Recommendation strength: one of
Strong,Worth exploring,Speculative, rendered as badge
Open report with Top recommendation in title block: which candidate to tackle first and why.
Use GLOSSARY.md vocabulary for the domain, and the groundwork:codebase-design vocabulary for the architecture. If GLOSSARY.md defines "Order," say "the Order intake module," not "the FooBarHandler," not "the Order service."
ADR conflicts: candidate contradicts existing ADR? Surface only when friction real enough to warrant revisiting ADR. Mark clearly in card (e.g. warning callout: "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor ADR forbids.
See HTML-REPORT.md for filling template, markup vocabulary, diagram patterns.
Do NOT propose interfaces yet. After file written, ask user: "Which of these would you like to explore?"
3. Grilling loop
User picks candidate → call Skill tool with groundwork:grilling to walk decision tree together: constraints, dependencies, shape of deepened module, what sits behind seam, what tests survive.
Side effects happen inline as decisions crystallize. Call Skill tool with groundwork:domain-modeling to keep domain model current:
- Naming a deepened module after a concept not in
GLOSSARY.md? Add term toGLOSSARY.md. Create file lazily if missing. - Sharpening a fuzzy term during the conversation? Update
GLOSSARY.mdright there. - User rejects the candidate with a load-bearing reason? Offer ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Offer only when future explorer would actually need reason to avoid re-suggesting. Skip ephemeral reasons ("not worth it right now") and self-evident ones.
- Want to explore alternative interfaces for the deepened module? Call Skill tool with
groundwork:codebase-design, use its design-it-twice parallel sub-agent pattern.
04 同仓库更多 Skills
unslop
Use when writing or editing prose a person will read, or when text sounds AI-generated.
show-me
Use when asked to show, diagram, or walk through how code fits together or what a change does, or before explaining a multi-file flow in prose.
pr
Use when writing or updating a pull request description, or before running `gh pr create`.
commit
Use when writing a commit message, or before running `git commit`.
write-specs
Spec a feature's observable behavior. Use when asked for requirements, when a request says what the system should do but not how, or to capture what a built system already guarantees. Not for how to build it (write-plan).
write-skills
Write, fix, or audit a skill's frontmatter, trigger description, and body. Use when a skill is asked for, never fires, or fires at the wrong moment. Not for a hook (write-hooks) or the plugin manifest and catalog.