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-12
- Stars
- ★ 2
- 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 资源文件 1
- 参考文档HTML-REPORT.md1.8 KB
03 SKILL.md 正文
<!-- vendored: mattpocock/skills@fcf0071 skills/engineering/improve-codebase-architecture (MIT). -->
Improve architecture
Find refactors that turn shallow modules into deep ones. Load nt-vendor:codebase-design
and use its terms exactly.
1. Explore
Decide where to look before looking. If the user named a module, subsystem, or pain
point, start there. Otherwise read back through git log --oneline for the areas that
change most often, because deepening pays off where change keeps happening.
Read CONTEXT.md and any ADRs for that area. Then spawn one agent to walk the code and
note where it is hard to follow:
- one concept spread across many small modules;
- shallow modules;
- functions extracted for testing while the bugs sit in how they are called;
- coupled modules that leak across their seams;
- code that is untested, or hard to test through its interface.
Apply the deletion test to anything that looks shallow.
2. Report
Write a self-contained architecture-review-<timestamp>.html to the OS temp directory,
so nothing is added to the repo. Open it with the platform's open command and tell the
user the absolute path. Follow HTML-REPORT.md.
Each candidate gets the files involved, the problem, the solution, the gain in locality,
leverage, and tests, a before-and-after visual, and a strength of Strong,
Worth exploring, or Speculative. Name domain concepts with the words in
CONTEXT.md. Mention a conflict with an ADR only when the problem is serious enough to
reopen that ADR. End with one top recommendation.
Do not propose interfaces yet. Ask the user which candidate to explore.
3. Work through the choice
Question the user about the chosen candidate: its constraints, its dependencies, where the seam goes, and which tests survive. As decisions settle:
- add a new or sharpened domain term to
CONTEXT.mdright away; - offer an ADR when the user rejects a candidate for a lasting reason that a later review would need in order not to suggest it again;
- for alternative interfaces, use the design-it-twice pattern in codebase-design.
04 同仓库更多 Skills
human-voice
Humanize prose by choosing a surgical voice edit or a structural rewrite. Use for AI-sounding drafts, anti-slop passes, editorial reviews, and requests to preserve an author's voice.
install-anti-slop
Install and configure the anti-slop Oxlint plugin in a local TypeScript or JavaScript repository. Use whenever a user asks to add anti-slop lint rules, copy the anti-slop plugin, configure opinionated Oxlint rules, or migrate an existing local anti-slop setup.
eli5
Explain a topic like I'm a 5 year old. Use when the user types /eli5 <topic> or asks for a dead-simple picture explainer of how something works.
codebase-design
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
audit-codebase
Read-only whole-codebase audit for simplifications in data structures, state representation, control flow, algorithms, and ownership. Inventories every subsystem as a coverage contract, reviews each one in a bounded subagent, verifies each finding against the repo, then audits its own coverage. Never edits, runs tests, commits, or pushes. Use for "audit this codebase", "find simplifications", or a pre-refactor survey.
crawl
Crawl a site with Screaming Frog and turn the output into findings a repo can act on. Use for SEO crawls and site audits, redirect or structured-data checks, rich-result eligibility questions, or any request that starts from crawl output.