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.

This command is informed by the project's domain model and built on a shared design vocabulary:

Run the
```
$codebase-design
```
skill for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
The domain language in
```
CONTEXT.md
```
gives names to good seams; ADRs in
```
docs/adr/
```
record decisions this command should not re-litigate.

识别架构摩擦点并提出深化优化机会——即将浅层module转换为深层module的重构操作。目标是提升可测试性与AI可导航性。

本指令基于项目的领域模型，并遵循一套通用的设计术语体系：

运行
```
$codebase-design
```
技能以了解架构术语（module、interface、depth、seam、adapter、leverage、locality）及其原则（删除测试、“interface即测试面”、“一个adapter=假设性seam，两个=真实seam”）。所有建议中必须严格使用这些术语——不要随意替换为“component”、“service”、“API”或“boundary”。
```
CONTEXT.md
```
中的领域语言为优质seam命名；
```
docs/adr/
```
中的ADR记录了本指令不应重新讨论的决策。

Process

流程

1. Explore

1. 探索阶段

Scope before you scan — YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look:

If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
Otherwise, walk back a good stretch of the commit history (
```
git log --oneline
```
) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the project's domain glossary (

CONTEXT.md

) and any ADRs in the area you're touching first.

For a large codebase, spawn a bounded exploration sub-agent to walk the selected scope while you inspect the domain docs and recent history. For a small scope, explore directly. 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.

扫描前先确定范围——YAGNI（You Ain't Gonna Need It，你不会需要它）。深化module的价值在于让未来的变更更轻松，因此要重点关注代码库中近期有变更的部分。在开始扫描前先确定探索方向：

如果用户指定了方向——某个module、子系统或痛点，则直接以此为目标，跳过以下推断步骤。
否则，回溯一段足够长的提交历史（
```
git log --oneline
```
），找出代码库的热点区域——频繁变更的文件和模块，优先关注这些路径。如果变更分散且无明显热点，则扩大探索范围。

首先阅读项目的领域术语表（

CONTEXT.md

）以及你所探索区域的相关ADR。

对于大型代码库，启动一个受限探索子Agent来遍历选定范围，同时你负责查看领域文档和近期历史。对于小型范围，则直接进行探索。不要遵循僵化的规则——以有机方式探索，并记录你遇到摩擦的地方：

理解某个概念需要在多个小型module间反复跳转的位置？
哪些module是浅层的——interface复杂度几乎与实现复杂度相当？
哪些地方仅为了可测试性而提取了纯函数，但实际bug隐藏在函数调用逻辑中（缺乏locality）？
哪些紧耦合的module越过了它们的seam？
代码库中哪些部分未测试，或难以通过当前interface进行测试？

对任何你怀疑是浅层的内容应用删除测试：删除它会集中复杂度，还是只是转移复杂度？如果是“集中复杂度”，则是你要找的信号。

2. Present candidates as a visual report

2. 将候选方案整理为可视化报告

Present a compact Markdown report directly in the conversation. Use a Mermaid diagram only when relationships, flow, or sequence are materially clearer than prose or a table. If the user asks to preserve the report, save the same Markdown where the repository keeps architectural notes.

For each candidate, include:

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 — a small Mermaid diagram or concise mapping 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 the
$codebase-design
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 REPORT.md for the report structure and diagram guidance.

Do NOT propose interfaces yet. After presenting the report, ask the user: "Which of these would you like to explore?"

直接在对话中呈现一份简洁的Markdown报告。仅当关系、流程或序列用 prose 或表格无法清晰表达时，才使用Mermaid图。如果用户要求保存报告，则将相同的Markdown文件保存到代码库存储架构笔记的位置。

每个候选方案需包含：

文件——涉及哪些文件/module
问题——当前架构为何会导致摩擦
解决方案——用通俗易懂的语言描述变更内容
收益——从locality和leverage的角度解释，以及测试将如何改进
前后对比——小型Mermaid图或简洁的映射图，展示浅层问题与深化优化后的状态
推荐强度——
```
Strong
```
（强烈推荐）、
```
Worth exploring
```
（值得探索）、
```
Speculative
```
（推测性）之一，以徽章形式呈现

报告末尾需添加首要推荐部分：说明你会优先处理哪个候选方案及原因。

领域术语使用
CONTEXT.md
中的表述，架构术语使用
$codebase-design
中的术语。如果

CONTEXT.md

定义了“Order”，则称其为“Order录入module”——而非“FooBarHandler”，也非“Order service”。

ADR冲突：如果候选方案与现有ADR冲突，仅当摩擦足够严重，值得重新讨论ADR时才提出。在卡片中明确标记（例如：警告提示框：“与ADR-0007冲突——但值得重新讨论，原因是……”）。不要列出ADR禁止的所有理论上的重构。

报告结构和图表指导请参见REPORT.md。

暂不要提出interface方案。报告呈现后，询问用户：“你想深入探讨哪一个方案？”

3. Grilling loop

3. 深入探讨循环

Once the user picks a candidate, run the

$grilling

skill to walk the decision 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 — run the

$domain-modeling

skill to keep the domain model current as you go:

Naming a deepened module after a concept not in
CONTEXT.md
? Add the term to
```
CONTEXT.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.
Want to explore alternative interfaces for the deepened module? Run the
```
$codebase-design
```
skill and use its design-it-twice parallel sub-agent pattern.

一旦用户选定某个候选方案，运行

$grilling

技能与他们一起梳理决策树——包括约束条件、依赖关系、深化后module的形态、seam背后的内容、保留的测试等。

随着决策逐渐明确，同步执行相关操作——运行

$domain-modeling

技能以保持领域模型的时效性：

若为深化后的module命名了
CONTEXT.md
中未提及的概念？将该术语添加到
```
CONTEXT.md
```
中。如果文件不存在，则按需创建。
若在对话中明确了模糊术语的定义？ 立即更新
```
CONTEXT.md
```
。
若用户以关键理由拒绝了候选方案？ 提议创建ADR，表述为：“需要我将此记录为ADR，以便未来的架构评审不会再次提出相同建议吗？” 仅当该理由确实能帮助未来的探索者避免重复提出相同建议时才提议——跳过临时理由（“现在不值得做”）和不言自明的理由。
若想探索深化后module的替代interface？ 运行
```
$codebase-design
```
技能，并使用其“两次设计”并行子Agent模式。