Back to Details

improve-codebase-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Improve Codebase Architecture

改进代码库架构

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
挖掘架构层面的痛点，并提出深化优化机会——即将浅模块重构为深模块的方案。目标是提升可测试性与AI可导航性。

Glossary

术语表

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.
  • Module — anything with an interface and an implementation (function, class, package, slice).
  • Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
  • Implementation — the code inside.
  • Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
  • Seam — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
  • Adapter — a concrete thing satisfying an interface at a seam.
  • Leverage — what callers get from depth.
  • Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
Key principles (see LANGUAGE.md for the full list):
  • Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
  • The interface is the test surface.
  • One adapter = hypothetical seam. Two adapters = real seam.
This skill is informed by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
所有建议中请严格使用以下术语。统一术语是核心要求——不要随意替换为“组件”“服务”“API”或“边界”。完整定义请查看LANGUAGE.md。
  • Module — 任何具有Interface和实现的单元（函数、类、包、代码片段）。
  • Interface — 调用者使用该模块必须了解的所有信息：类型、不变量、错误模式、调用顺序、配置。不仅仅是类型签名。
  • Implementation — 模块内部的代码。
  • Depth — 接口的杠杆作用：少量接口背后承载大量行为。Deep（深）=高杠杆作用；Shallow（浅）=接口复杂度几乎与实现相当。
  • Seam — Interface所在的位置；无需修改原有代码即可变更行为的节点。（请使用该术语，而非“边界”）
  • Adapter — 在Seam处满足Interface要求的具体实现。
  • Leverage — 调用者从模块深度中获得的收益。
  • Locality — 维护者从模块深度中获得的收益：变更、Bug、知识都集中在同一位置。
核心原则（完整列表请查看LANGUAGE.md）：
  • 删除测试法：假设删除该模块。如果复杂度随之消失，说明它只是一个中转模块；如果复杂度分散到N个调用者中重新出现，说明它具备存在价值。
  • Interface即测试面。
  • 一个Adapter=潜在Seam；两个Adapter=真实Seam。
该技能会参考项目的领域模型。领域语言为优质Seam命名；ADR记录了该技能不应重新讨论的决策。

Process

流程

1. Explore

1. 探索

Read the project's domain glossary and any ADRs in the area you're touching first.
Then use the Agent tool with 
subagent_type=Explore
to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
  • Where does understanding one concept require bouncing between many small modules?
  • Where are modules shallow — interface 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 (no locality)?
  • Where do tightly-coupled modules leak across their seams?
  • Which parts of the codebase are untested, or hard to test through their current interface?
Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
首先阅读项目的领域术语表以及你所涉及领域的所有ADR。
然后使用Agent工具，设置
subagent_type=Explore
来遍历代码库。不要遵循僵化的规则——以自然方式探索，并记录你遇到的痛点：
  • 理解某个概念需要在多个小模块之间跳转的位置？
  • 哪些模块属于Shallow（浅）——接口复杂度几乎与实现相当？
  • 哪些纯函数仅为了可测试性而被提取，但真正的Bug隐藏在调用逻辑中（缺乏Locality）？
  • 哪些紧耦合模块的边界存在泄漏？
  • 代码库中哪些部分未被测试，或难以通过当前Interface进行测试？
对所有疑似浅模块应用删除测试法：删除它会让复杂度集中，还是仅仅转移？如果是“集中”，则符合优化信号。

2. Present candidates

2. 提出候选方案

Present a numbered list of deepening opportunities. For each candidate:
  • Files — which files/modules are involved
  • Problem — why the current architecture is causing friction
  • Solution — plain English description of what would change
  • Benefits — explained in terms of locality and leverage, and also in how tests would improve
Use CONTEXT.md vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If 
CONTEXT.md
defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. "contradicts ADR-0007 — but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.
Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
列出编号形式的深化优化机会。每个候选方案需包含：
  • 文件 — 涉及的文件/模块
  • 问题 — 当前架构为何导致痛点
  • 解决方案 — 用通俗易懂的语言描述变更内容
  • 收益 — 从Locality和Leverage的角度解释，同时说明测试层面的改进
**使用CONTEXT.md中的领域词汇，以及LANGUAGE.md中的架构词汇。**如果CONTEXT.md定义了“Order”，请使用“Order录入Module”——不要用“FooBarHandler”，也不要用“Order服务”。
ADR冲突：如果候选方案与现有ADR矛盾，仅当痛点足够严重、值得重新讨论ADR时才提出。请明确标记（例如："与ADR-0007矛盾——但值得重新讨论，原因是…"）。不要列出所有ADR禁止的理论性重构方案。
暂不要提出Interface设计。请询问用户：“你希望深入探索哪一个方案？”

3. Grilling loop

3. 深度研讨循环

Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Side effects happen inline as decisions crystallize:
  • Naming a deepened module after a concept not in 
    CONTEXT.md
    ?     Add the term to 
    CONTEXT.md
    — same discipline as 
    /grill-with-docs
    (see CONTEXT-FORMAT.md). Create the file lazily if it doesn't exist.
  • Sharpening a fuzzy term during the conversation? Update 
    CONTEXT.md
    right there.
  • User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See ADR-FORMAT.md.
  • Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md.
Vendored from mattpocock/skills @ 
b843cb5
— MIT License. See skills/UPSTREAM-CREDITS.md for refresh instructions.
一旦用户选定某个候选方案，进入深度研讨对话。与用户一起梳理设计脉络——约束条件、依赖关系、深化后模块的形态、Seam背后的内容、保留的测试等。
随着决策逐渐明确，同步执行以下操作：
  • 为深化后的模块命名了CONTEXT.md中未提及的概念？ 将该术语添加到CONTEXT.md中——遵循与
    /grill-with-docs
    相同的规范（请查看CONTEXT-FORMAT.md）。如果文件不存在，按需创建。
  • 对话中明确了模糊术语的定义？ 立即更新CONTEXT.md。
  • 用户因关键原因拒绝候选方案？ 提议创建ADR，表述为：“需要我将该决策记录为ADR，以便未来架构评审时不再重复提出类似方案吗？” 仅当该原因确实能帮助后续探索者避免重复建议时才提出——跳过临时原因（如“目前不值得投入”）和不言自明的原因。请查看ADR-FORMAT.md。
  • 希望探索深化后模块的替代Interface？ 请查看INTERFACE-DESIGN.md。
源自mattpocock/skills @ 
b843cb5
— MIT许可证。刷新说明请查看skills/UPSTREAM-CREDITS.md。