Back to Details

improve-codebase-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Improve Codebase Architecture

Improve Codebase Architecture

暴露 architecture friction，并提出 deepening opportunities，也就是把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。
Expose architecture friction and propose deepening opportunities—refactors that turn shallow modules into deep modules. The goals are testability and AI-navigability.

Glossary

Glossary

在每个建议中精确使用这些术语。语言一致性就是重点，不要漂移到 “component”、“service”、“API” 或 “boundary”。完整定义见 LANGUAGE.md。
  • Module — 任何有 interface 和 implementation 的东西（function、class、package、slice）。
  • Interface — caller 为正确使用 module 必须知道的一切：types、invariants、error modes、ordering、config。不只是 type signature。
  • Implementation — 内部代码。
  • Depth — interface 上的 leverage：小 interface 后面有大量 behaviour。Deep = 高 leverage。Shallow = interface 几乎和 implementation 一样复杂。
  • Seam — interface 所在的位置；可以不原地编辑就改变 behaviour 的地方。（用这个词，不用 “boundary”。）
  • Adapter — 在 seam 处满足 interface 的具体东西。
  • Leverage — callers 从 depth 获得的东西。
  • Locality — maintainers 从 depth 获得的东西：change、bugs、knowledge 集中在一个地方。
关键原则（完整列表见 LANGUAGE.md）：
  • Deletion test：想象删除这个 module。如果复杂性消失，它只是 pass-through。如果复杂性在 N 个 callers 中重新出现，它就在发挥价值。
  • The interface is the test surface.
  • One adapter = hypothetical seam. Two adapters = real seam.
这个 skill 会参考项目的 domain model。Domain language 为好的 seams 命名；ADRs 记录 skill 不应重新争论的决策。
Use these terms precisely in every recommendation. Language consistency is key—do not drift into using "component", "service", "API", or "boundary". See LANGUAGE.md for full definitions.
  • Module — Anything with an interface and implementation (function, class, package, slice).
  • Interface — Everything a caller must know to use the module correctly: types, invariants, error modes, ordering, config. Not just a type signature.
  • Implementation — Internal code.
  • Depth — Leverage on the interface: a small interface with a large amount of behaviour behind it. Deep = high leverage. Shallow = interface is nearly as complex as the implementation.
  • Seam — The location of an interface; a place where behaviour can be changed without editing in-place. (Use this term instead of "boundary".)
  • Adapter — A concrete thing that satisfies an interface at a seam.
  • Leverage — What callers gain from depth.
  • Locality — What maintainers gain from depth: changes, bugs, and knowledge are concentrated in one place.
Key Principles (full list in LANGUAGE.md):
  • Deletion test: Imagine deleting this module. If complexity disappears, it's just a pass-through. If complexity re-emerges in N callers, it's providing value.
  • The interface is the test surface.
  • One adapter = hypothetical seam. Two adapters = real seam.
This skill references the project's domain model. Domain language names good seams; ADRs record decisions that the skill should not re-debate.

Process

Process

1. Explore

1. Explore

先读取项目的 domain glossary 和你将触碰区域的任何 ADR。
然后使用 Agent tool 和 
subagent_type=Explore
遍历 codebase。不要死套启发式规则；自然探索并记录你感到 friction 的地方：
  • 理解一个概念是否需要在许多小 modules 之间来回跳？
  • 哪些 modules 是 shallow，interface 几乎和 implementation 一样复杂？
  • 哪些 pure functions 只是为了 testability 被抽出，但真正 bug 藏在调用方式里（没有 locality）？
  • 哪些 tightly-coupled modules 会跨 seams 泄漏？
  • codebase 哪些部分未测试，或很难通过当前 interface 测试？
对任何疑似 shallow 的东西应用 deletion test：删除它会集中复杂性，还是只是移动复杂性？“会集中”就是你要找的信号。
First, read the project's domain glossary and any ADRs for the areas you will touch.
Then use the Agent tool with 
subagent_type=Explore
to traverse the codebase. Don't rigidly follow heuristics; explore naturally and note where you feel friction:
  • Does understanding a concept require jumping back and forth between many small modules?
  • Which modules are shallow, with an interface nearly as complex as the implementation?
  • Which pure functions were extracted solely for testability, but the real bugs lie in how they're called (lacking locality)?
  • Which tightly-coupled modules leak across seams?
  • Which parts of the codebase are untested, or hard to test via the current interface?
Apply the deletion test to anything suspected of being shallow: Would deleting it concentrate complexity, or just move it? "Concentrates" is the signal you're looking for.

2. Present candidates

2. Present candidates

展示一个编号列表，列出 deepening opportunities。每个 candidate 包含：
  • Files — 涉及哪些 files/modules
  • Problem — 当前 architecture 为什么造成 friction
  • Solution — 用普通语言说明会改变什么
  • Benefits — 用 locality 和 leverage 解释，也说明 tests 会如何改善
domain 词汇使用 CONTEXT.md，architecture 词汇使用 LANGUAGE.md。 如果 
CONTEXT.md
定义了 “Order”，就说 “Order intake module”，不要说 “FooBarHandler”，也不要说 “Order service”。
ADR conflicts：如果 candidate 与现有 ADR 冲突，只有当 friction 真实到值得重开 ADR 时才提出。明确标记（例如 "contradicts ADR-0007 — but worth reopening because…"）。不要列出 ADR 理论上禁止的每个 refactor。
不要还没问用户就提出 interfaces。问用户：“你想探索哪一个？”
Present a numbered list of deepening opportunities. Each candidate includes:
  • Files — Which files/modules are involved
  • Problem — Why the current architecture causes friction
  • Solution — Describe what will change in plain language
  • Benefits — Explain using locality and leverage, and how tests will improve
Use domain vocabulary from CONTEXT.md and architecture vocabulary from LANGUAGE.md. If 
CONTEXT.md
defines "Order", say "Order intake module" instead of "FooBarHandler" or "Order service".
ADR Conflicts: If a candidate conflicts with an existing ADR, only propose it if the friction is significant enough to warrant reopening the ADR. Mark it clearly (e.g., "contradicts ADR-0007 — but worth reopening because…"). Do not list every refactor that is theoretically prohibited by an ADR.
Do not propose interfaces without asking the user first. Ask the user: "Which one would you like to explore?"

3. Grilling loop

3. Grilling loop

用户选中 candidate 后，进入 grilling conversation。和他们走完整个 design tree：constraints、dependencies、deepened module 的形状、seam 后面是什么、哪些 tests 能经受变化。
决策成形时内联产生 side effects：
  • 用 
    CONTEXT.md
    中没有的概念命名 deepened module？     把 term 加到 
    CONTEXT.md
    ，纪律同 
    /grill-with-docs
    （见 CONTEXT-FORMAT.md）。文件不存在就懒创建。
  • 对话中收紧了模糊 term？ 立刻更新 
    CONTEXT.md
    。
  • 用户用有分量的理由拒绝 candidate？ 提议 ADR，表述为："要我把这记录成 ADR，避免未来 architecture reviews 再次建议它吗？" 只有当未来 explorer 真的需要这个理由来避免重复建议时才提议；短期理由（“现在不值得”）和显而易见的理由跳过。见 ADR-FORMAT.md。
  • 想探索 deepened module 的替代 interfaces？ 见 INTERFACE-DESIGN.md。
Once the user selects a candidate, enter a grilling conversation. Walk through the entire design tree with them: constraints, dependencies, the shape of the deepened module, what's behind the seam, and which tests will survive changes.
Generate inline side effects as decisions take shape:
  • Naming a deepened module with a concept not in 
    CONTEXT.md
    ?     Add the term to 
    CONTEXT.md
    , following the same discipline as 
    /grill-with-docs
    (see CONTEXT-FORMAT.md). Lazily create the file if it doesn't exist.
  • Tightened an ambiguous term during the conversation? Update 
    CONTEXT.md
    immediately.
  • User rejected a candidate with a substantial reason? Propose an ADR, phrased as: "Would you like me to record this as an ADR to prevent future architecture reviews from suggesting it again?" Only propose this if future explorers will actually need this reason to avoid repeating the suggestion; skip short-term reasons ("not worth it now") and obvious reasons. See ADR-FORMAT.md.
  • Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md.