improve-codebase-architecture
Skill2 starsChanged 3 days agoMITView on GitHub
Codebase-wide architecture improvement via the deep-modules pattern (Ousterhout / Feathers) — find tightly-coupled modules worth consolidating and deepening. Use when looking for refactor opportunities or to make the codebase more testable + AI-navigable; run periodically (every few days), not diff-centric.
We split this skill into the rules it gives an agent
10 rules. 0 are common, 5 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 184 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
Read and follow framework/work-principle.md before taking up work.
- Distinctive: line 88
After larger feature additions when "it feels messy".
- Distinctive: line 89
Before onboarding a new maintainer / agent — friction map as an entry tool.
- Distinctive: line 91
When tests test implementation instead of behaviour — symptom that modules are shallow.
- Very specific: line 105
Before exploring (Phase 1) and before writing any candidate, proposal or finding in deep-module vocabulary: read and follow …
- Very specific: line 112
When starting the codebase walk: read and follow skills/improve_codebase_architecture/process.md (Phase 1 organic exploration with the …
- Distinctive: line 174
No implementation of the refactors — only decision material.
- Very specific: line 176
No diff review — code_review_board is a different domain.
- Very specific: line 178
No cross-spec review — architecture_coherence_review is a different domain.
- Distinctive: line 203
Abort: no friction found → the codebase is already deep + clean.
“Common” is measured: kept by at least 6 in 10 of the 184 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Read and follow framework/work-principle.md before taking up work.
Resolve this reference against the framework root; retain the consumer CWD.
Skill: improve-codebase-architecture
Purpose
Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep modules. The goal is testability + AI-navigability.
Complementary to existing review skills:
code_review_board(L1/L2) is diff-centric — review of recent changes.architecture_coherence_reviewis cross-spec — interface contracts between specs.improve_codebase_architectureis codebase-wide + periodic — an every-few-days friction walk, not diff-centric.
Distinct: not "what's wrong with this PR?", but "where does friction accumulate across the whole codebase, and where would deepening concentrate complexity?".
Source
Matt Pocock's skills at b843cb5 (MIT License, © 2026 Matt Pocock); Forge's register of adopted methods.
Standalone
Distinct from:
code_review_board(L1/L2) — diff-centric, post-MCA return. This skill is codebase-wide + periodic; no diff required.architecture_coherence_review— cross-spec interface contracts (≥2 specs). This skill is codebase-wide within a single repo, not cross-spec.code-architecturepersona (absorbed into code-review) — diff-review architecture axis. This skill finds refactor candidates, not review-of-existing-code.frame— problem-analysis discipline. This skill is the codebase-walk discipline (anchored on concrete files + modules).
What only this skill delivers:
- Strict glossary (module / interface / implementation / depth / seam / adapter / leverage / locality) — disciplinary vocabulary, not "component / service / API / boundary".
- Deletion test as an identification tool for shallow modules.
- One-adapter-hypothetical / two-adapters-real rule as anti-YAGNI for abstractions.
- 3-phase loop (explore organic → present numbered candidates → grilling loop with the user).
- Inline side effects: update CONTEXT.md / offer an ADR on rejection.
When to call
- The user wants to improve architecture, find refactor opportunities, or make the codebase AI-navigable + testable.
- Periodic (Pocock recommendation: every-few-days continuous refactor).
- After larger feature additions when "it feels messy".
- Before onboarding a new maintainer / agent — friction map as an entry tool.
- When tests test implementation instead of behaviour — symptom that modules are shallow.
Do not call for
- PR diff review →
code_review_boardL1 / L2. - Cross-spec interface check →
architecture_coherence_review. - Single-module refactor with a clear plan → direct MCA delegation.
- Performance optimization (hot path) →
code-reviewperformance axis.
Glossary (strict)
Before exploring (Phase 1) and before writing any candidate, proposal or finding in deep-module vocabulary: read and
follow skills/improve_codebase_architecture/glossary.md (terms module, interface, implementation, depth, seam,
adapter, leverage, locality; principles including the deletion test and the one-adapter / two-adapters rule;
relationships; rejected framings).
Process
When starting the codebase walk: read and follow skills/improve_codebase_architecture/process.md (Phase 1 organic
exploration with the deletion test; Phase 2 numbered candidates with files, problem, solution, benefits and ADR
conflicts, then the user's pick; Phase 3 grilling loop with inline CONTEXT.md updates and the ADR offer on
rejection).
Red flags
- A proposal that uses "service" / "component" / "boundary" vocabulary instead of the strict glossary (drift).
- A candidate without a files list (too abstract to decide on).
- Solution description without locality + leverage argumentation.
- A proposal that increases test coverage without changing the module (that's symptom treatment, not deep-module).
- Proposing a new seam with only one adapter ("diamond" risk — hypothetical seam).
- A proposal that violates its own CONTEXT.md vocabulary (domain drift).
- A refactor plan without checking whether tests still test the right thing.
Common rationalizations
| Rationalization | Reality |
| "It's just a small refactor" | Several small refactors without glossary discipline accumulate as vocabulary drift. |
| "Component / service / API is standard language" | Standard isn't precise enough for deep-modules discipline. The strict glossary prevents drift. |
| "We extract that into a util module" | Util is a pattern break. A deep module has behaviour + locality. Util is pass-through. |
| "Several small modules are more testable" | Test against implementation, not behaviour. A deep module with a small interface is easier to test (the interface is the test surface). |
| "We add the adapter prophylactically" | One adapter = hypothetical seam. Two adapters = real seam. Adapter only when something actually varies across it. |
| "Pure function = automatically good" | A pure function without locality (bug hides in HOW it's called) is shallow + leaky. |
| "We use DDD's bounded context" | "Boundary" is overloaded. Say seam + interface in this skill's vocabulary. |
Contract
INPUT
- Required: codebase access (repo locally or via Read tool).
- Required: clear trigger (user request for an architecture improvement, or a periodic every-few-days run).
- Optional: CONTEXT.md with a domain glossary (the skill uses it when present, lazy-creates when absent).
- Optional: docs/decisions/ or docs/adr/ with ADRs.
- Context: this skill (with the strict glossary),
skills/_protocols/skill-guardrails.md,skills/documentation_and_adrs/SKILL.md.
OUTPUT
DELIVERS:
- Phase 1 friction map (organic, qualitative — where does the reviewer experience friction?).
- Phase 2 numbered candidate list (files / problem / solution / benefits) with strict-glossary vocabulary.
- Phase 3 grilling conversation per picked candidate with a design-tree walk.
- Inline side effects: CONTEXT.md updates / ADRs on rejection / cross-ref to api_and_interface_design when interface design is needed.
DOES NOT DELIVER:
- No implementation of the refactors — only decision material.
- No diff review —
code_review_boardis a different domain. - No cross-spec review —
architecture_coherence_reviewis a different domain.
ENABLES:
- A codebase-wide refactor roadmap.
- Vocabulary discipline (anti-drift).
- Clear decisions about seams / adapters / module shapes.
- Testability improvement via the deep-module pattern.
DONE
- Friction map documented (phase 1 output).
- ≥3 numbered candidates presented in the complete format.
- The user has picked which candidates to explore (phase 2 gate).
- Grilling loop for picked candidates done with the design-tree walk (phase 3).
- CONTEXT.md updates / ADRs / cross-refs done inline.
- Strict glossary used consistently (no "service" / "component" / "boundary" drift).
FAIL
- Retry: vocabulary drift detected → rewrite candidates with the strict glossary.
- Escalate: ≥2 candidates contradict an existing ADR → user decision whether to revisit the ADRs.
- Abort: no friction found → the codebase is already deep + clean. The skill is not needed now; defer to the next run.
See also
skills/_protocols/skill-guardrails.md— anti-patterns.skills/api_and_interface_design/authoring.md— phase 3 grilling loop invokes contract-first when interface design is needed.skills/documentation_and_adrs/SKILL.md— ADR format on rejection.skills/code_review_board/SKILL.md— diff counterpart.skills/architecture_coherence_review/SKILL.md— cross-spec counterpart.skills/deprecation_and_migration/SKILL.md— when a refactor retires an old system.
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- mattpocock/skills★ 309ksame name
- danny-avila/LibreChat★ 47ksame name
- LibreChat-AI/LibreChat★ 47ksame name
- QuivrHQ/quivr★ 40ksame name
- windmill-labs/windmill★ 18ksame name
- GreyDGL/PentestGPT★ 16ksame name
- humanlayer/humanlayer★ 13ksame name
- sanity-io/sanity★ 6.4ksame name
- ArcReel/ArcReel★ 6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.5ksame name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use decision-mapping, writing-beats and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FabienDehopreSkilldecision-mapping
Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
Also in 8 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 60 projects that use this
simo97Skillmigrate-to-shoehorn
Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
Also in 64 projects that use this
- simo97Skill
request-refactor-plan
Use this skill when user wants to create a refactor plan.
Also in 40 projects that use this
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 33 projects that use this
AnasX7Skillscaffold-exercises
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
Also in 63 projects that use this
- +2 more from simo97
In this repository85 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversary-test-planSkill
- api-and-interface-designSkill
- architecture-coherence-reviewSkill
- bedrock-drillSkill
- cavemanSkill
- code-review-boardSkill
- consistency-checkSkill
- councilSkill
- cross-spec-consistency-checkSkill
- deprecation-and-migrationSkill
- documentation-and-adrsSkill
- frameSkill
- frontend-design-ttySkill
- frontend-ui-engineeringSkill
- get-api-docsSkill
- impl-plan-reviewSkill
- improve-codebase-architectureSkill
- knowledge-captureSkill
- knowledge-processorSkill
- pre-build-spec-auditSkill
- retroactive-spec-updateSkill
- root-cause-fixSkill
- scopingSkill
- sectional-deep-reviewSkill
- security-and-hardeningSkill
- session-diagnosisSkill
- shipping-and-launchSkill
- show-open-tasksSkill
- source-spec-reduceSkill
- spec-authoringSkill
- spec-boardSkill
- task-creationSkill
- task-status-updateSkill
- testingSkill
- transparency-headerSkill
- ux-authoringSkill
- workflow-routerSkill
- youtube-subtitlesSkill
- adversary-test-planSkill
- api-and-interface-designSkill
- architecture-coherence-reviewSkill
- bedrock-drillSkill
- cavemanSkill
- close-retroSkill
- code-review-boardSkill
- consistency-checkSkill
- convergence-loopSkill
- councilSkill
- cross-spec-consistency-checkSkill
- deprecation-and-migrationSkill
- documentation-and-adrsSkill
- frameSkill
- frontend-design-ttySkill
- frontend-ui-engineeringSkill
- get-api-docsSkill
- impl-plan-reviewSkill
- knowledge-captureSkill
- knowledge-processorSkill
- The first 60 shown.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.