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.

识别架构中的摩擦点，并提出架构深化机会——即将浅层模块重构为深层模块的方案。目标是提升可测试性与AI可导航性。

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

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

Process

流程

1. Explore

1. 探索

Read the project's domain glossary (

CONTEXT.md

) 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.

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

CONTEXT.md

）以及你所涉及领域的所有ADR。

然后使用

subagent_type=Explore

的Agent工具遍历代码库。不要遵循僵化的规则——以自然方式探索，并记录你遇到摩擦的地方：

理解某个概念需要在多个小型模块间反复跳转的位置？
哪些模块是浅层的——接口复杂度几乎与实现相当？
哪些纯函数仅为了可测试性而被提取，但真正的bug隐藏在调用逻辑中（缺乏locality）？
哪些紧耦合模块的实现细节跨接缝泄露？
代码库中哪些部分未被测试，或难以通过当前接口进行测试？

对所有你怀疑是浅层的模块应用删除测试：删除它会集中复杂度，还是只是转移复杂度？如果是“会集中复杂度”，那就是你要找的信号。

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, render a card with:

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 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 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>

——并告知用户文件的绝对路径。

报告通过CDN引入Tailwind进行布局和样式设计，通过CDN引入Mermaid绘制图表，当图形/流程/序列图能清晰传达结构时使用Mermaid。将Mermaid与手工编写的CSS/SVG可视化结合——当关系为图形化（调用图、依赖图、序列图）时使用Mermaid，当需要更具编辑性的展示（规模图、剖面图、折叠动画）时使用手工构建的div/SVG。每个候选方案都配有前后对比可视化图。注重可视化效果。

每个候选方案的卡片应包含：

文件——涉及哪些文件/模块
问题——当前架构为何会产生摩擦
解决方案——用通俗易懂的语言描述变更内容
收益——从locality和leverage的角度解释收益，以及测试将如何改进
前后对比图——并排展示，手工绘制，说明浅层问题与深化后的效果
推荐强度——分为
```
Strong
```
（强烈推荐）、
```
Worth exploring
```
（值得探索）、
```
Speculative
```
（推测性），以徽章形式呈现

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

**领域术语使用

CONTEXT.md

中的词汇，架构术语使用

/codebase-design

中的词汇。**如果

CONTEXT.md

定义了“Order”，则使用“Order录入module”进行描述——而非“FooBarHandler”或“Order service”。

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

查看HTML-REPORT.md获取完整的HTML框架、图表模式和样式指南。

暂不要提出接口方案。文件写入完成后，询问用户：“你想深入探索哪一个方案？”

3. Grilling loop

3. 深入探讨循环

Once the user picks a candidate, run the

/grilling

skill to 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 — 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

技能与用户一起梳理设计树——包括约束条件、依赖关系、深化后模块的形态、接缝背后的内容、哪些测试可以保留。

随着决策逐渐明确，同步产生附带操作——运行

/domain-modeling

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

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