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.
所有建议中必须严格使用以下术语。统一语言是核心要求——不要随意使用“组件（component）”“服务（service）”“API”或“边界（boundary）”。完整定义请参考LANGUAGE.md。
  • Module — 任何具备接口（Interface）与实现（Implementation）的实体（函数、类、包、代码切片）。
  • Interface — 调用方使用该模块所需了解的全部信息：类型、不变量、错误模式、调用顺序、配置。不仅仅是类型签名。
  • Implementation — 模块内部的代码。
  • Depth — 接口的杠杆效应：用简洁的接口实现丰富的行为。Deep（深度模块） = 高杠杆效应。Shallow（浅模块） = 接口复杂度几乎与实现相当。
  • Seam — 接口所在的位置；无需原地修改代码即可变更行为的地方。（使用该术语，而非“边界（boundary）”。）
  • Adapter — 在Seam处满足接口要求的具体实现。
  • Leverage — 调用方从模块深度中获得的价值。
  • Locality — 维护者从模块深度中获得的价值：变更、bug、知识都集中在一处。
核心原则（完整列表请参考LANGUAGE.md）：
  • 删除测试：想象删除该模块。如果复杂度随之消失，说明它只是一个透传模块。如果复杂度分散到N个调用方中重新出现，说明它具备存在价值。
  • 接口即测试面。
  • 一个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
来遍历代码库。不要遵循僵化的规则——以自然的方式探索，并记录你遇到摩擦的地方：
  • 理解某个概念需要在多个小模块间反复跳转的位置？
  • 哪些模块是浅模块——接口复杂度几乎与实现相当？
  • 哪些纯函数只是为了可测试性而提取，但真正的bug隐藏在调用逻辑中（缺乏Locality）？
  • 哪些紧耦合模块的实现细节跨Seam泄露？
  • 代码库中哪些部分未测试，或难以通过当前接口进行测试？
对所有疑似浅模块应用删除测试：删除它会集中复杂度，还是只是转移复杂度？“集中复杂度”是你需要的信号。

2. Present candidates as an HTML report

2. 将候选方案以HTML报告形式呈现

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from 
$TMPDIR
, falling back to 
/tmp
(or 
%TEMP%
on Windows), and write to 
<tmpdir>/architecture-review-<timestamp>.html
so each run gets a fresh file. Open it for the user — 
xdg-open <path>
on Linux, 
open <path>
on macOS, 
start <path>
on Windows — and tell them the absolute path.
The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.
For each candidate, the same template as before, but rendered as a card:
  • 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 how tests would improve
  • Before / After diagram — side-by-side, custom-drawn, illustrating the shallowness and the deepening
  • Recommendation strength — one of 
    Strong
    , 
    Worth exploring
    , 
    Speculative
    , rendered as a badge
End the report with a Top recommendation section: which candidate you'd tackle first and why.
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 in the card (e.g. a warning callout: "contradicts ADR-0007 — but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.
See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
将独立的HTML文件写入系统临时目录，避免文件存入代码仓库。从
$TMPDIR
解析临时目录，若不存在则回退到
/tmp
（Windows系统为
%TEMP%
），并写入
<tmpdir>/architecture-review-<timestamp>.html
，确保每次运行都生成新文件。为用户打开该文件——Linux系统使用
xdg-open <path>
，macOS使用
open <path>
，Windows使用
start <path>
——并告知其绝对路径。
报告通过Tailwind CDN实现布局与样式，通过Mermaid CDN生成图表（当图形/流程/序列图能清晰传达结构时使用）。将Mermaid与手工编写的CSS/SVG可视化结合——当关系为图形化（调用图、依赖图、序列图）时使用Mermaid，当需要更具编辑性的展示（规模图、剖面图、折叠动画）时使用手工构建的div/SVG。每个候选方案都需要前后对比可视化。尽量采用可视化方式呈现。
每个候选方案使用统一模板，以卡片形式展示：
  • 涉及文件 — 相关的文件/模块
  • 问题 — 当前架构产生摩擦的原因
  • 解决方案 — 用通俗易懂的语言描述变更内容
  • 收益 — 从Locality和Leverage角度解释，以及测试将如何改进
  • 前后对比图 — 并排展示自定义绘制的图表，说明浅模块的问题与深化后的效果
  • 推荐强度 — 分为
    Strong（强烈推荐）
    、
    Worth exploring（值得探索）
    、
    Speculative（推测性）
    ，以徽章形式呈现
报告末尾添加首要推荐部分：说明你建议优先处理哪个候选方案及原因。
领域词汇使用CONTEXT.md中的定义，架构词汇使用LANGUAGE.md中的定义。如果CONTEXT.md定义了“Order”，请使用“Order录入Module”——而非“FooBarHandler”或“Order服务”。
ADR冲突：如果候选方案与现有ADR矛盾，仅当摩擦足够严重、值得重新讨论ADR时才提出。在卡片中明确标记（例如警告提示：“与ADR-0007矛盾——但因以下原因值得重新讨论……”）。无需列出ADR禁止的所有理论性重构。
完整的HTML框架、图表模式及样式指南请参考HTML-REPORT.md。
暂不要提出具体接口。文件生成后，询问用户：“你希望深入探索哪一个方案？”

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.
一旦用户选定某个候选方案，进入深度研讨对话。与用户一起梳理设计树——约束条件、依赖关系、深化后模块的形态、Seam背后的内容、保留的测试用例。
随着决策逐步明确，同步执行以下操作：
  • 为深化后的模块命名了CONTEXT.md中未提及的概念？ 将该术语添加到CONTEXT.md中——遵循与
    /grill-with-docs
    相同的规范（参考CONTEXT-FORMAT.md）。若文件不存在则按需创建。
  • 对话中明确了模糊术语的定义？ 立即更新CONTEXT.md。
  • 用户因关键原因拒绝候选方案？ 主动提议生成ADR，表述为：“需要我将该决策记录为ADR吗？这样未来的架构评审就不会再提出相同建议。” 仅当该原因能帮助后续探索者避免重复建议时才提出——跳过临时原因（“目前不值得做”）和不言自明的原因。参考ADR-FORMAT.md。
  • 希望探索深化后模块的替代接口？ 请参考INTERFACE-DESIGN.md。