improve-codebase-architecture
Improve Codebase Architecture
Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as markdown doc RFCs in ~/Development/docs/rfc.
A deep module (John Ousterhout, "A Philosophy of Software Design") 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.
Process
1. Explore the codebase
Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
- Where does understanding one concept require bouncing between many small files?
- Where are modules so shallow that the interface is nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
- Where do tightly-coupled modules create integration risk in the seams between them?
- Which parts of the codebase are untested, or hard to test?
The friction you encounter IS the signal.
More from evans-sam/skills
grill-me
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
15git-guardrails-claude-code
Set up Claude Code hooks to block dangerous git and gh CLI commands before they execute. Use when user wants to prevent destructive git operations, block dangerous GitHub CLI actions (repo delete, pr merge, secret management, API mutations), or add git/gh safety hooks to Claude Code.
14write-a-prd
Create a PRD through user interview, codebase exploration, and module design, then save as a local markdown document. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
13request-refactor-plan
Create a detailed refactor plan with tiny commits via user interview, then save it as a local markdown RFC document. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
13prd-to-issues
Turn a PRD into independent ticket artifacts — GitHub issues, Linear tickets, local files, or Notion pages — with HITL/AFK tags and dependency links. Each ticket is a tracer-bullet vertical slice. Use when user wants to produce standalone work items from a PRD. Not for a live feature-building workflow.
12design-an-interface
Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
12