improve-codebase-architecture
Explore a codebase to find opportunities for architectural improvement by deepening shallow modules (John Ousterhout, "A Philosophy of Software Design"). Use when the user says "improve architecture", "find refactoring opportunities", "make this more testable", "this codebase is
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/improve-codebase-architecture
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/improve-codebase-architecture
Explore a codebase like an AI would, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs.
Structured execution spec:
protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
A deep module has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside. (John Ousterhout, A Philosophy of Software Design)
The deepening test: would merging these modules produce a smaller combined interface than they have separately? If no, it's not a deepening opportunity — it's just reorganization.
Reference — Dependency Categories
Classify each candidate's dependencies; the category determines the entire testing strategy.
- In-process — pure computation, in-memory state, no I/O. Always deepenable; merge and test directly.
- Local-substitutable — dependencies with local test stand-ins (PGLite for Postgres, memfs for filesystem). Deepenable if the stand-in exists; test the merged module with the stand-in running in the suite.
- Remote but owned (Ports & Adapters) — your own services across a network boundary. Define a port at the boundary; the deep module owns the logic, transport is injected. Tests use an in-memory adapter; production uses the real one.
- True external (Mock) — third-party services you don't control (Stripe, Twilio). Mock at the boundary; the deepened module takes the external dependency as an injected port, tests provide a mock.
Reference — Testing Strategy
Replace, don't layer. Write new tests at the deepened module's interface boundary. Old unit tests on the now-merged shallow modules become redundant — delete them. Tests assert on observable outcomes through the public interface, not internal state, so they survive internal refactors.
Step 1 — Explore the codebase
Navigate organically. Note where you experience friction: where understanding one concept requires bouncing between many small files; where modules are so shallow the interface is nearly as complex as the implementation; where pure functions were extracted just for testability while the real bugs hide in how they're called; where tightly-coupled modules create integration risk at the seams; which parts are untested or hard to test. The friction you encounter IS the signal — don't follow rigid heuristics.
If you find no strong candidates, say so directly. A thin adapter over a stable external API is correct design, not a problem. Don't manufacture candidates — tell the user what you found and why the codebase resists the pattern.
Step 2 — Present candidates
⚠️ Deepening test: before listing a candidate, verify merging produces a smaller interface than the modules have separately. If not, it's reorganization — skip it.
For each genuine candidate show: Cluster (modules/concepts involved), Why they're coupled (shared types, call patterns, co-owned concept), Dependency category (one of four, one-sentence rationale), Test delta (specific test files that would be deleted, and the new boundary tests that replace them). Then ask: "Which of these would you like to explore?"
Step 3 — User picks a candidate
Step 4 — Frame the problem space
Write a user-facing explanation of the chosen candidate: the constraints any new interface must satisfy, the dependencies it must handle (with category), and a rough illustrative code sketch to make the constraints concrete (a grounding device, not a proposal). Show this, then immediately proceed to Step 5 — the user reads while designs are worked.
Step 5 — Design multiple interfaces
Produce 3–4 radically different interface designs, each under a different constraint:
- A — Minimal: 1–3 entry points max. Ruthlessly hide everything.
- B — Flexible: support many use cases and extension points; maximize what callers can customize.
- C — Caller-optimized: make the most common call site trivial; ergonomics over generality.
- D — Ports & Adapters (if applicable): design around injected adapters for cross-boundary dependencies.
Each design produces: (1) interface signature, (2) usage example, (3) what complexity it hides, (4) dependency strategy per category, (5) trade-offs.
⚠️ Don't mistake extraction for deepening. If a design has the same total interface surface as the original modules combined, it's a rename. The interface must get smaller.
Before dispatch, bind the worker and total invocation to finite deadlines and resource limits, with a named monitoring owner, observable progress, a cancellation handle and terminal success/failure/timeout outcomes. Use native controls; include read-only scope and no-child instructions in research briefs. On failure or timeout, cancel owned work and report retained partial results and unchecked coverage. If these controls are unavailable, do not dispatch. Use the existing bounded inline fallback when permitted, labeling it non-independent; empty or failed returns never count as completed coverage.
If sub-agents are available (Claude Code / Cowork): spawn 3–4 in parallel with the brief template below. Do not share prior designs between agents — isolation is the point. If not (Claude.ai): work each constraint sequentially, treating each design as complete before the next; this is useful but correlated same-context generation, not independent cold work.
## Design Brief
### Context
Codebase: [repo/language]
Candidate: [module cluster name]
### Files involved
[file path] — [one-line summary]
### Coupling description
[Why these modules are tightly coupled — shared types, call patterns, co-owned concepts]
### Dependency category
[In-process / Local-substitutable / Remote but owned / True external] — Rationale: [one sentence]
### What the deepened module should hide
[Internal state, wiring, error handling, retry logic, etc.]
### What it must expose
[The minimum surface callers actually need]
### Your design constraint
[One of: Minimal / Flexible / Caller-optimized / Ports & Adapters]
### Output format required
1. Interface signature 2. Usage example 3. What complexity it hides 4. Dependency strategy 5. Trade-offs
After all designs are presented, compare them in prose and give an opinionated recommendation — which is strongest and why, or a hybrid. The user wants a strong read, not a menu.
Step 6 — User picks an interface (or accepts the recommendation)
Step 7 — Create GitHub issue
Resolve and read back the exact destination repository with the complete issue draft before approval. Bind that approved repository explicitly in the publication command; ambiguous or changed identity stops publication. Draft the RFC using the template below. Render the complete draft as a markdown block in the conversation, then ask: "Should I create this issue now?" Wait for explicit confirmation before running gh issue create --repo <approved-owner/repository>. If gh is unavailable, print the final draft for manual paste.
## Problem
- Which modules are shallow and tightly coupled
- What integration risk exists at the seams
- Why this makes the codebase harder to navigate and maintain
## Proposed Interface
- Interface signature (types, methods, params)
- Usage example showing how callers use it
- What complexity it hides internally
## Dependency Strategy
[Category name] — [one sentence on how deps are handled]
- Production: [real adapter / merged module / mock boundary]
- Tests: [stand-in / in-memory adapter / mock implementation]
## Testing Strategy
- New boundary tests to write: [behaviors to verify at the interface — inputs and expected outcomes]
- Old tests to delete: [specific test file names and why they become redundant]
- Test environment needs: [stand-ins, adapters, or fixtures required]
## Implementation Recommendations
[Durable architectural principles, not file-path instructions.]
- What the module should own (responsibilities)
- What it should hide (implementation details)
- What it should expose (the interface contract)
- How callers should migrate to the new interface
Old tests to delete. Name specific old tests only when deletion is justified by a behavioral coverage mapping to retained/replacement boundary tests. An evidenced none is valid, including an untested candidate; do not manufacture a deletion list to satisfy the template.
⚠️ "Implementation Recommendations" must be file-path-agnostic. Write principles a future engineer can apply even after the codebase is reorganized.
Human output. This skill's handler-facing output obeys the human-output contract (
human-output/SKILL.md).
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
protocol.yon 10.6 KB · in bundle
-
SKILL.md 10.4 KB
--- name: improve-codebase-architecture description: Explore a codebase to find opportunities for architectural improvement by deepening shallow modules (John Ousterhout, "A Philosophy of Software Design"). Use when the user says "improve architecture", "find refactoring opportunities", "make this more testable", "this codebase is hard to navigate", "consolidate these modules", "find coupling problems", "write an RFC for this refactor", or "help me think about module design". Also trigger when the user asks why tests are brittle, why a module is hard to mock, or why changing one thing always breaks another. visibility: public self-improvable: true next-skills: - skill: prime-sweep phrase: "/prime-sweep" why: "When the codebase to refactor spans ≥3 sources or >10k tokens — delegate the surveying to keep your context clean" - skill: human-rewrite phrase: "/human-rewrite" why: "The refactor case or RFC is long-form argument aimed at whoever approves it — repair it for a reader without weakening the coupling evidence it rests on" triggers: - "/improve-codebase-architecture" - "improve architecture" - "find refactoring opportunities" - "make this more testable" - "this codebase is hard to navigate" - "consolidate these modules" - "find coupling problems" - "write an RFC for this refactor" - "help me think about module design" --- # /improve-codebase-architecture Explore a codebase like an AI would, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs. > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. **A deep module has a small interface hiding a large implementation.** Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside. (John Ousterhout, *A Philosophy of Software Design*) **The deepening test:** would merging these modules produce a smaller combined interface than they have separately? If no, it's not a deepening opportunity — it's just reorganization. ## Reference — Dependency Categories Classify each candidate's dependencies; the category determines the entire testing strategy. 1. **In-process** — pure computation, in-memory state, no I/O. Always deepenable; merge and test directly. 2. **Local-substitutable** — dependencies with local test stand-ins (PGLite for Postgres, memfs for filesystem). Deepenable if the stand-in exists; test the merged module with the stand-in running in the suite. 3. **Remote but owned (Ports & Adapters)** — your own services across a network boundary. Define a port at the boundary; the deep module owns the logic, transport is injected. Tests use an in-memory adapter; production uses the real one. 4. **True external (Mock)** — third-party services you don't control (Stripe, Twilio). Mock at the boundary; the deepened module takes the external dependency as an injected port, tests provide a mock. ## Reference — Testing Strategy **Replace, don't layer.** Write new tests at the deepened module's interface boundary. Old unit tests on the now-merged shallow modules become redundant — delete them. Tests assert on observable outcomes through the public interface, not internal state, so they survive internal refactors. ## Step 1 — Explore the codebase Navigate organically. Note where you experience friction: where understanding one concept requires bouncing between many small files; where modules are so shallow the interface is nearly as complex as the implementation; where pure functions were extracted just for testability while the real bugs hide in how they're called; where tightly-coupled modules create integration risk at the seams; which parts are untested or hard to test. **The friction you encounter IS the signal** — don't follow rigid heuristics. If you find no strong candidates, say so directly. A thin adapter over a stable external API is correct design, not a problem. Don't manufacture candidates — tell the user what you found and why the codebase resists the pattern. ## Step 2 — Present candidates > ⚠️ **Deepening test:** before listing a candidate, verify merging produces a smaller interface than the modules have separately. If not, it's reorganization — skip it. For each genuine candidate show: **Cluster** (modules/concepts involved), **Why they're coupled** (shared types, call patterns, co-owned concept), **Dependency category** (one of four, one-sentence rationale), **Test delta** (specific test files that would be deleted, and the new boundary tests that replace them). Then ask: "Which of these would you like to explore?" ## Step 3 — User picks a candidate ## Step 4 — Frame the problem space Write a user-facing explanation of the chosen candidate: the constraints any new interface must satisfy, the dependencies it must handle (with category), and a rough illustrative code sketch to make the constraints concrete (a grounding device, not a proposal). Show this, then immediately proceed to Step 5 — the user reads while designs are worked. ## Step 5 — Design multiple interfaces Produce 3–4 radically different interface designs, each under a different constraint: - **A — Minimal:** 1–3 entry points max. Ruthlessly hide everything. - **B — Flexible:** support many use cases and extension points; maximize what callers can customize. - **C — Caller-optimized:** make the most common call site trivial; ergonomics over generality. - **D — Ports & Adapters** (if applicable): design around injected adapters for cross-boundary dependencies. Each design produces: (1) interface signature, (2) usage example, (3) what complexity it hides, (4) dependency strategy per category, (5) trade-offs. > ⚠️ **Don't mistake extraction for deepening.** If a design has the same total interface surface as the original modules combined, it's a rename. The interface must get smaller. Before dispatch, bind the worker and total invocation to finite deadlines and resource limits, with a named monitoring owner, observable progress, a cancellation handle and terminal success/failure/timeout outcomes. Use native controls; include read-only scope and no-child instructions in research briefs. On failure or timeout, cancel owned work and report retained partial results and unchecked coverage. If these controls are unavailable, do not dispatch. Use the existing bounded inline fallback when permitted, labeling it non-independent; empty or failed returns never count as completed coverage. **If sub-agents are available** (Claude Code / Cowork): spawn 3–4 in parallel with the brief template below. Do not share prior designs between agents — isolation is the point. **If not** (Claude.ai): work each constraint sequentially, treating each design as complete before the next; this is useful but correlated same-context generation, not independent cold work. ``` ## Design Brief ### Context Codebase: [repo/language] Candidate: [module cluster name] ### Files involved [file path] — [one-line summary] ### Coupling description [Why these modules are tightly coupled — shared types, call patterns, co-owned concepts] ### Dependency category [In-process / Local-substitutable / Remote but owned / True external] — Rationale: [one sentence] ### What the deepened module should hide [Internal state, wiring, error handling, retry logic, etc.] ### What it must expose [The minimum surface callers actually need] ### Your design constraint [One of: Minimal / Flexible / Caller-optimized / Ports & Adapters] ### Output format required 1. Interface signature 2. Usage example 3. What complexity it hides 4. Dependency strategy 5. Trade-offs ``` After all designs are presented, compare them in prose and give an opinionated recommendation — which is strongest and why, or a hybrid. The user wants a strong read, not a menu. ## Step 6 — User picks an interface (or accepts the recommendation) ## Step 7 — Create GitHub issue Resolve and read back the exact destination repository with the complete issue draft before approval. Bind that approved repository explicitly in the publication command; ambiguous or changed identity stops publication. Draft the RFC using the template below. Render the complete draft as a markdown block in the conversation, then ask: **"Should I create this issue now?"** Wait for explicit confirmation before running `gh issue create --repo <approved-owner/repository>`. If `gh` is unavailable, print the final draft for manual paste. ```markdown ## Problem - Which modules are shallow and tightly coupled - What integration risk exists at the seams - Why this makes the codebase harder to navigate and maintain ## Proposed Interface - Interface signature (types, methods, params) - Usage example showing how callers use it - What complexity it hides internally ## Dependency Strategy [Category name] — [one sentence on how deps are handled] - Production: [real adapter / merged module / mock boundary] - Tests: [stand-in / in-memory adapter / mock implementation] ## Testing Strategy - New boundary tests to write: [behaviors to verify at the interface — inputs and expected outcomes] - Old tests to delete: [specific test file names and why they become redundant] - Test environment needs: [stand-ins, adapters, or fixtures required] ## Implementation Recommendations [Durable architectural principles, not file-path instructions.] - What the module should own (responsibilities) - What it should hide (implementation details) - What it should expose (the interface contract) - How callers should migrate to the new interface ``` > **Old tests to delete.** Name specific old tests only when deletion is justified by a behavioral coverage mapping to retained/replacement boundary tests. An evidenced none is valid, including an untested candidate; do not manufacture a deletion list to satisfy the template. > ⚠️ **"Implementation Recommendations"** must be file-path-agnostic. Write principles a future engineer can apply even after the codebase is reorganized. > **Human output.** This skill's handler-facing output obeys the human-output > contract (`human-output/SKILL.md`). > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.