Back to Details

improve-codebase-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
像AI一样探索代码库，发现架构摩擦点，找到提升可测试性的机会，并以GitHub issue RFC的形式提出模块加深重构方案。
深度模块（出自John Ousterhout的《软件设计的哲学》）指的是拥有小型接口但隐藏大量实现的模块。深度模块更易于测试、更易于AI导航，并且让你可以在边界而非内部进行测试。

Process

流程

1. Explore the codebase

1. 探索代码库

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.
使用Agent工具，设置subagent_type=Explore来自然地浏览代码库。不要遵循僵化的规则——要有机地探索，并记录你遇到的摩擦点：
  • 理解某个概念需要在多个小文件之间来回切换的地方？
  • 模块过于浅显，接口复杂度几乎与实现相当的地方？
  • 仅为了可测试性而提取纯函数，但真正的bug隐藏在函数调用逻辑中的地方？
  • 紧耦合模块在接缝处带来集成风险的地方？
  • 代码库中哪些部分未经过测试，或是难以测试？
你遇到的摩擦点就是关键信号。

2. Present candidates

2. 提出候选改进点

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 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?"
列出带编号的模块加深机会清单。对于每个候选点，需要展示：
  • 集群：涉及哪些模块/概念
  • 耦合原因：共享类型、调用模式、概念的共同归属
  • 依赖类别：参考REFERENCE.md中的四类
  • 测试影响：哪些现有测试会被边界测试取代
暂时不要提出接口方案。向用户询问：“你想深入探索其中哪一个？”

3. User picks a candidate

3. 用户选择候选点

4. Frame the problem space

4. 界定问题范围

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。用户在阅读和思考问题的同时，子代理可以并行工作。

5. Design multiple interfaces

5. 设计多个接口

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:
  1. Interface signature (types, methods, params)
  2. Usage example showing how callers use it
  3. What complexity it hides internally
  4. Dependency strategy (how deps are handled — see REFERENCE.md)
  5. 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.
使用Agent工具并行生成3个及以上的子代理。每个子代理必须为加深后的模块设计完全不同的接口。
为每个子代理提供独立的技术简报（文件路径、耦合细节、依赖类别、需要隐藏的内容）。此简报与步骤4中的面向用户说明无关。为每个代理设置不同的设计约束：
  • 代理1：“最小化接口——目标最多1-3个入口点”
  • 代理2：“最大化灵活性——支持多种用例和扩展”
  • 代理3：“针对最常见的调用方优化——让默认场景尽可能简单”
  • 代理4（如有需要）：“围绕端口与适配器模式设计，处理跨边界依赖”
每个子代理需要输出：
  1. 接口签名（类型、方法、参数）
  2. 展示调用方如何使用它的示例
  3. 它在内部隐藏的复杂度
  4. 依赖策略（如何处理依赖——参考REFERENCE.md）
  5. 权衡取舍
按顺序展示各个设计方案，然后用文字进行对比。
对比完成后，给出你自己的推荐：你认为哪个设计最优秀，以及原因。如果不同设计的元素可以很好地结合，也可以提出混合方案。要明确表达观点——用户需要的是明确的建议，而不只是选项清单。

6. User picks an interface (or accepts recommendation)

6. 用户选择接口（或接受推荐方案）

7. Create GitHub issue

7. 创建GitHub issue

Create a refactor RFC as a GitHub issue using 
gh issue create
. Use the template in REFERENCE.md. Do NOT ask the user to review before creating — just create it and share the URL.
使用
gh issue create
创建重构RFC作为GitHub issue。使用REFERENCE.md中的模板。创建前无需征求用户审核——直接创建并分享链接。