improve-codebase-architecture

Files (3)

• HTML-REPORT.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 改进代码库架构

揭示架构摩擦，并提出 **deepening 机会** —— 把 shallow module 变成 deep module 的重构。目标是可测试性与 AI 可导航性。

本命令以项目的领域模型为 _依据_，并建立在一套共用的设计词汇之上：

- 运行 `/codebase-design` 技能以获取架构词汇（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其原则（deletion test、「interface 就是测试面」、「一个 adapter = 假想 seam，两个 = 真实」）。每一条建议都必须精确使用这些术语 —— 不要滑向 "component"、"service"、"API" 或 "boundary"。
- `CONTEXT.md` 中的领域语言为好的 seam 命名；`docs/adr/` 中的 ADR 记录了本命令不应重新争辩的决策。

## 流程

### 1. 探索

**先定范围再扫描 —— YAGNI。** 加深一个 module 的回报，在于让它未来的改动更容易，因此要额外重视代码库中最近发生过变更的部分。先决定 *往哪里看*，再动手看：

- 若用户已经点明方向 —— 某个 module、某个子系统、某个痛点 —— 就采用它，并跳过下面的推断。
- 否则，回溯一段足够长的提交历史（`git log --oneline`），找出代码库的热点 —— 反复出现的文件与区域 —— 并让这些路径优先吸引你的注意。若变更四处分散、没有清晰热点，再把网撒开。

先阅读项目的领域术语表（`CONTEXT.md`）以及你将触及区域中的任何 ADR。

然后派一个 subagent 走读代码库。不要死守僵硬启发式 —— 有机地探索，并记下你感到摩擦的地方：

- 理解一个概念，是否必须在许多小 module 之间来回跳转？
- 哪些 module 是 **shallow** —— interface 几乎与实现一样复杂？
- 哪些纯函数只是为了可测试性才被抽出来，而真正的缺陷藏在它们被调用的方式里（没有 **locality**）？
- 哪些紧耦合的 module 会跨越 seam 泄漏？
- 代码库的哪些部分未经测试，或很难通过当前 interface 来测试？

对任何你怀疑是 shallow 的东西做 **deletion test**：删掉它会把复杂度集中起来，还是只是挪走？「会，会集中」才是你要的信号。

### 2. 以 HTML 报告呈现候选

把一份自包含的 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 与手绘 CSS/SVG 视觉混合使用 —— 当关系是图状（调用图、依赖、序列）时用 Mermaid；当你想要更偏编辑性的东西（质量图、剖面、折叠动画）时用手写 div/SVG。每个候选都要有 **前后可视化**。要视觉化。

对每个候选，渲染一张卡片，包含：

- **文件** —— 涉及哪些文件/module
- **问题** —— 当前架构为何造成摩擦
- **方案** —— 用直白语言描述会改什么
- **收益** —— 用 locality 与 leverage 来解释，以及测试会如何改善
- **Before / After 图** —— 并排、定制绘制，说明 shallowness 与 deepening
- **建议强度** —— `Strong`、`Worth exploring`、`Speculative` 三者之一，渲染为徽章

报告末尾加一个 **首选建议** 小节：你会先处理哪个候选以及原因。

**领域用 CONTEXT.md 词汇，架构用 `/codebase-design` 词汇。** 若 `CONTEXT.md` 定义了 "Order"，就谈 "the Order intake module" —— 不要说 "the FooBarHandler"，也不要说 "the Order service"。

**ADR 冲突**：若某个候选与已有 ADR 矛盾，只有当摩擦真实到值得重开该 ADR 时才呈现它。在卡片中明确标出（例如警告提示框：_"contradicts ADR-0007 — but worth reopening because…"_）。不要列出每一项 ADR 所禁止的理论上的重构。

完整 HTML 脚手架、图示模式与样式指引见 [HTML-REPORT.md](HTML-REPORT.md)。

此时还不要提出 interface。文件写好后，询问用户："你想探索其中哪一项？"

### 3. Grilling 循环

用户选定候选后，运行 `/grilling` 技能，与他们一起走决策树 —— 约束、依赖、deepened module 的形态、seam 后面放什么、哪些测试能留下来。

副作用在决策成形时就地发生 —— 运行 `/domain-modeling` 技能，边走边让领域模型保持最新：

- **用 `CONTEXT.md` 中没有的概念给 deepened module 命名？** 把该术语加入 `CONTEXT.md`。若文件不存在则惰性创建。
- **对话中打磨了一个模糊术语？** 当场更新 `CONTEXT.md`。
- **用户以一条有分量的理由拒绝该候选？** 提议写 ADR，措辞为：_"要我把它记成 ADR，好让以后的架构评审不再重复建议它吗？"_ 只有当未来探索者确实需要这条理由才能避免再次提出同一件事时才提议 —— 跳过短暂理由（「现在不值得」）和显而易见的理由。
- **想为 deepened module 探索替代 interface？** 运行 `/codebase-design` 技能，并使用其 design-it-twice 并行 subagent 模式。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn