Back to Details

improve-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Improve Architecture

架构优化

Explore a codebase organically, surface architectural friction, and propose refactors via GitHub issue RFCs. Uses "Design It Twice" — multiple parallel interface designs compared in prose.
有机探索整个代码库，梳理出架构摩擦点，并通过GitHub issue RFC的形式提出重构方案。采用"Design It Twice"策略——并行生成多套接口设计方案并进行书面对比。

Process

流程

1. Friction-driven exploration

1. 摩擦驱动探索

Use subagents to explore the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
  • Understanding one concept requires bouncing between many small files
  • Modules so shallow the interface is nearly as complex as the implementation
  • Pure functions extracted just for testability, but real bugs hide in how they're called
  • Tightly-coupled modules creating integration risk in the seams between them
  • Untested or hard-to-test areas
  • Code that fights you when you try to change it
The friction you experience IS the signal. Be honest about what confused you or slowed you down — that's the most valuable information.
使用子Agent探索代码库，不要遵循僵化的启发式规则，要有机探索并记录你遇到摩擦的位置：
  • 理解一个概念需要在多个小文件之间反复跳转
  • 模块过于浅层，其接口复杂度几乎和实现逻辑相当
  • 纯函数仅为了可测试性被抽离，但实际bug隐藏在函数的调用逻辑中
  • 紧耦合模块在衔接处带来集成风险
  • 未测试或难以测试的区域
  • 修改代码时阻力极大
你感受到的摩擦就是信号，如实记录让你困惑或拖慢你进度的点——这是最有价值的信息。

2. Present candidates

2. 展示候选优化点

Show a numbered list of opportunities. For each:
  • Cluster: which modules/concepts are involved
  • Why coupled: shared types, call patterns, co-ownership of a concept
  • Dependency category: see references/dependency-categories.md
  • Test impact: existing coverage, what boundary tests would replace
Don't propose solutions yet. Ask the user which candidate to explore.
给出编号的优化机会列表，每个条目包含：
  • Cluster: 涉及的模块/概念
  • Why coupled: 共享类型、调用模式、共同归属同一个概念
  • Dependency category: 参见 references/dependency-categories.md
  • Test impact: 现有覆盖率、可被替换的边界测试
暂时不要提出解决方案，询问用户希望探索哪个候选点。

3. Frame the problem space

3. 界定问题空间

For the chosen candidate, write up:
  • Constraints any new interface must satisfy
  • Dependencies it relies on
  • A rough illustrative sketch to ground the constraints (not a proposal, just framing)
Show this to the user, then immediately proceed to step 4. The user reads while sub-agents work.
针对选中的候选点，整理出以下内容：
  • 任意新接口必须满足的约束
  • 它所依赖的资源
  • 用于具象化约束的粗略说明草图（不是方案，仅用于界定问题）
将内容展示给用户后，立即进入第4步，用户阅读内容的同时子Agent可以并行工作。

4. Design It Twice

4. Design It Twice

Spawn 3+ sub-agents in parallel, each with a different design constraint and a separate technical brief (file paths, coupling details, dependency category, what's being hidden).
  • Agent 1: Minimise the interface — 1-3 entry points max
  • Agent 2: Maximise flexibility — support many use cases and extension
  • Agent 3: Optimise for the most common caller — default case trivial
  • Agent 4 (if applicable): Ports & adapters 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 (see references/dependency-categories.md)
  5. Trade-offs
Present designs sequentially, then compare in prose. Give an opinionated recommendation — which design is strongest and why. If elements combine well, propose a hybrid.
并行生成3个以上的子Agent，每个都有不同的设计约束和独立的技术概要（文件路径、耦合细节、依赖类别、需要隐藏的内容）。
  • Agent 1: 最小化接口——最多1-3个入口点
  • Agent 2: 最大化灵活性——支持多种使用场景和扩展需求
  • Agent 3: 针对最常见调用方优化——默认场景使用成本极低
  • Agent 4（如适用）: 为跨边界依赖提供端口与适配器
每个子Agent输出以下内容：
  1. 接口签名（类型、方法、参数）
  2. 调用方使用示例
  3. 内部隐藏的复杂度内容
  4. 依赖策略（参见 references/dependency-categories.md）
  5. 取舍权衡
按顺序展示所有设计方案，然后进行书面对比，给出有倾向性的推荐——说明哪个设计最优以及原因。如果不同方案的元素可以很好地结合，可以提出混合方案。

5. Create GitHub issue RFC

5. 创建GitHub issue RFC

After the user picks a design (or accepts the recommendation), create a GitHub issue using 
gh issue create
. Don't ask to review first — create and share the URL.
Use the RFC template:
markdown
undefined
用户选定设计方案（或接受推荐方案）后，使用
gh issue create
命令创建GitHub issue，无需先请求审核，直接创建并分享URL。
使用如下RFC模板：
markdown
undefined

Problem

Problem

Describe the architectural friction:
  • Which modules are shallow and tightly coupled
  • What integration risk exists in the seams
  • Why this makes the codebase harder to navigate and maintain
Describe the architectural friction:
  • Which modules are shallow and tightly coupled
  • What integration risk exists in the seams
  • Why this makes the codebase harder to navigate and maintain

Proposed Interface

Proposed Interface

The chosen interface design:
  • Interface signature (types, methods, params)
  • Usage example showing how callers use it
  • What complexity it hides internally
The chosen interface design:
  • Interface signature (types, methods, params)
  • Usage example showing how callers use it
  • What complexity it hides internally

Dependency Strategy

Dependency Strategy

Which category applies and how dependencies are handled:
  • In-process: merged directly
  • Local-substitutable: tested with [specific stand-in]
  • Ports & adapters: port definition, production adapter, test adapter
  • Mock: mock boundary for external services
Which category applies and how dependencies are handled:
  • In-process: merged directly
  • Local-substitutable: tested with [specific stand-in]
  • Ports & adapters: port definition, production adapter, test adapter
  • Mock: mock boundary for external services

Testing Strategy

Testing Strategy

  • New boundary tests to write: behaviours to verify at the interface
  • Old tests to delete: shallow module tests made redundant
  • Test environment needs: local stand-ins or adapters required
Replace, don't layer — old unit tests on shallow modules become waste once boundary tests exist. Delete them.
  • New boundary tests to write: behaviours to verify at the interface
  • Old tests to delete: shallow module tests made redundant
  • Test environment needs: local stand-ins or adapters required
Replace, don't layer — old unit tests on shallow modules become waste once boundary tests exist. Delete them.

Implementation Recommendations

Implementation Recommendations

Durable guidance NOT coupled to current file paths:
  • 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
undefined
Durable guidance NOT coupled to current file paths:
  • 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
undefined