Improve Codebase Architecture

Walks your codebase looking for shallow modules (where the interface is almost as complex as the implementation) and suggests deepening refactors to improve testability and AI navigation. It reads your CONTEXT.md for domain language and checks ADRs to avoid relitigating past decisions. You get an HTML report with before/after diagrams, ranked by whether fixing each issue would actually concentrate complexity or just move it around. Pick one and it'll grill you on the design, updating your context docs and proposing new ADRs inline as the conversation firms up. Useful when you know something feels coupled or hard to test but can't quite see the seam.

skills.sh installs: 6.1K
GitHub stars: 5.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add vinvcn/mattpocock-skills-zh-cn --skill improve-codebase-architecture --agent claude-code

Installs into .claude/skills of the current project.

Files

改进代码库架构

暴露 architectural friction，并提出 deepening opportunities：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。

这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：

调用 Skill 工具并指定 codebase-design，获取 architecture vocabulary（module、interface、depth、seam、adapter、leverage、locality）及其 principles（deletion test、"the interface is the test surface"、"one adapter = hypothetical seam, two = real"）。每条建议都准确使用这些术语，不要漂移到 "component"、"service"、"API" 或 "boundary"。
GLOSSARY.md 中的 domain language 会为好的 seams 命名；docs/adr/ 中的 ADRs 记录这个命令不应重新争论的 decisions。

流程

1. 探索

先划定扫描范围：YAGNI。 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：

如果用户点名了方向（module、subsystem 或 pain point），就按该方向探索，跳过下面的推断。
否则，向前回看一段足够长的 commit history（git log --oneline），找出反复出现的 files 和 areas，让这些 hot spots 成为首要关注点。如果变更分散、没有明显 hot spot，再扩大范围。

先读取项目 domain glossary（GLOSSARY.md）以及你将触碰区域的 ADRs。

然后 spawn 一个使用全新 context window 的 sub-agent 来遍历 codebase。不要套死板 heuristics；自然探索，并记录你感到 friction 的地方：

SKILL.md on GitHub