架构体检与深化

呈现架构摩擦,提出深化机会:把浅模块变深模块的重构。目标是可测性与 AI 可导航性。

本命令建立在项目领域模型与共享设计词汇之上:

• 调 Skill 工具执行 codebase-design 获取架构词汇(模块、接口、深度、接缝、适配器、杠杆、局部性)及其原则(删除测试、"接口就是测试面"、"一个适配器 = 假想接缝,两个 = 真")。每条建议精确使用这些词,不漂移到"组件"、"服务"、"API"、"边界";
• .agentdocs/glossary.md 的领域语言为好接缝命名;adr/ 里记录的决策不重新开庭。

流程

1. 探索

**先定范围:YAGNI。**深化一个模块的回报是让对它的未来变更更容易,所以给近期变过的部分加权。看之前先决定看哪:

• 用户点名了方向(模块、子系统、痛点)就直接采用,跳过下面的推断;
• 否则回看一段足够长的提交历史(git log --oneline)找热点:反复出现的文件与区域,让这些路径先拉住注意力。变更散落无热点时,放宽网。

先读项目术语表(.agentdocs/glossary.md)与所涉区域的决策记录。

然后派一个子代理扫代码库。不循僵硬的启发式,有机地探索,记下摩擦发生处:

• 理解一个概念要在许多小模块之间来回跳吗?
• 哪里模块浅:接口几乎和实现一样复杂?
• 哪里为了可测性抽了纯函数,真 bug 却藏在怎么调用它(没有局部性)?
• 哪里紧耦合的模块渗漏过接缝?
• 哪些部分没测试,或通过当前接口很难测?

对任何疑似浅的东西做删除测试:删掉它,复杂度是集中还是只是挪了地方?答"集中"才是要的信号。

2. 候选呈现为 HTML 报告

写一个自包含 HTML 文件到系统临时目录,不进仓库。从 $TMPDIR 解析临时目录,回退 /tmp(Windows 用 %TEMP%),写 <tmpdir>/architecture-review-<timestamp>.html,每次运行一个新文件。为用户打开(macOS open,Linux xdg-open,Windows start)并告知绝对路径。

报告用 Tailwind(CDN) 排版,关系图用 Mermaid(CDN):图状关系(调用图、依赖、时序)用 Mermaid,编辑性的视觉(体量图、剖面图、折叠动画)用手写的 div/SVG。每个候选带前后对比可视化。要有视觉冲击。

每个候选渲染一张卡:

• 文件:涉及哪些文件/模块;
• 问题:当前架构为何产生摩擦;
• 方案:平实的中文,会怎么变;
• 收益:用局部性与杠杆解释,测试会怎么变好;
• 前后图:并排手绘,展示浅与深;
• 推荐强度:强、值得探索、投机 之一,渲染为徽章。

报告以首推收尾:先做哪个候选、为什么。

**领域词汇用 .agentdocs/glossary.md,架构词汇用 codebase-design。**术语表定义了"订单",就说"订单受理模块",不说"FooBarHandler",也不说"订单服务"。

ADR 冲突:候选与既有 ADR 矛盾时,只在摩擦大到值得重审该决策时才呈现。在卡片上明确标记(如警示框:"与 ADR-0007 矛盾,但值得重审,因为……")。不罗列每条 ADR 理论上禁止的重构。

完整 HTML 脚手架、图示模式与样式指导见 HTML-REPORT.md。

**此时不提接口方案。**文件写好后问用户:"想深入探讨哪一个?"

3. 访谈循环

用户选定候选后,调 Skill 工具执行 interview,沿决策树走:约束、依赖、深化后模块的形状、接缝后面是什么、哪些测试存活。

决策定型时的沉淀由 interview 内联完成(它组合了 agent-docs 的写纪律):

• 给深化模块起的名字不在术语表里?加入 .agentdocs/glossary.md,文件不存在就懒创建;
• 对话中磨利了模糊术语?当场更新术语表;
• 用户以承重的理由否决了候选?提供 ADR:*"要不要记成决策记录,免得未来的架构体检再提它?"*只在理由真的会被未来探索者需要时提供;一时性的("现在不值得")和自明的理由跳过;
• 想为深化模块探索备选接口?调 Skill 工具执行 codebase-design,用它的 design-it-twice 并行子代理模式。