---
id: sm3-improve-codebase-architecture
name: "improve-codebase-architecture"
url: https://skills.yangsir.net/skill/sm3-improve-codebase-architecture
author: mattpocock
domain: ai-software-architecture-engineering
tags: ["codebase-refactoring", "architecture-improvement", "backend-optimization", "ai-code-analysis"]
install_count: 152000
rating: 4.80 (93 reviews)
github: https://github.com/mattpocock/skills
---

# improve-codebase-architecture

> 像AI一样探索代码库，分析并改进代码架构，提升代码质量、可维护性和可扩展性。

**Stats**: 152,000 installs · 4.8/5 (93 reviews)

## Before / After 对比

### 代码库架构改进

## Readme

# 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 GitHub issue RFCs.

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.

### 2. Present candidates

Present a numbered list of deepening opportunities. For each candidate, show:

- **Cluster**: Which modules/concepts are involved

- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept

- **Dependency category**: See [REFERENCE.md](https://github.com/mattpocock/skills/blob/HEAD/improve-codebase-architecture/REFERENCE.md) for the four categories

- **Test impact**: What existing tests would be replaced by boundary tests

Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"

### 3. User picks a candidate

### 4. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:

- The constraints any new interface would need to satisfy

- The dependencies it would need to rely on

- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints

Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.

### 5. Design multiple interfaces

Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.

Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:

- Agent 1: "Minimize the interface — aim for 1-3 entry points max"

- Agent 2: "Maximize flexibility — support many use cases and extension"

- Agent 3: "Optimize for the most common caller — make the default case trivial"

- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"

Each sub-agent outputs:

- Interface signature (types, methods, params)

- Usage example showing how callers use it

- What complexity it hides internally

- Dependency strategy (how deps are handled — see [REFERENCE.md](https://github.com/mattpocock/skills/blob/HEAD/improve-codebase-architecture/REFERENCE.md))

- Trade-offs

Present designs sequentially, then compare them in prose.

After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.

### 6. User picks an interface (or accepts recommendation)

### 7. Create GitHub issue

Create a refactor RFC as a GitHub issue using `gh issue create`. Use the template in [REFERENCE.md](https://github.com/mattpocock/skills/blob/HEAD/improve-codebase-architecture/REFERENCE.md). Do NOT ask the user to review before creating — just create it and share the URL.
Weekly Installs1.2KRepository[mattpocock/skills](https://github.com/mattpocock/skills)GitHub Stars2.4KFirst Seen5 days agoSecurity Audits[Gen Agent Trust HubPass](/mattpocock/skills/improve-codebase-architecture/security/agent-trust-hub)[SocketPass](/mattpocock/skills/improve-codebase-architecture/security/socket)[SnykPass](/mattpocock/skills/improve-codebase-architecture/security/snyk)Installed oncodex1.2Kopencode1.2Kcursor1.2Kgemini-cli1.2Kgithub-copilot1.2Kkimi-cli1.2K

---
*Source: https://skills.yangsir.net/skill/sm3-improve-codebase-architecture*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm3-improve-codebase-architecture/markdown*