improve-architecture

改进架构

扫描代码库，找出累积的摩擦点，将可深化的候选项整理成可视化报告，并将用户选中的候选项纳入常规规格周期。目标是提升可测试性和可导航性——模块应有足够的深度，让其接口成为测试面。

全程严格使用以下术语：module、interface、implementation、seam、adapter（以及作为特质的 depth/locality/leverage）——seam 是一个公共表面，在此表面上，行为既可观测又可替换（tdd 和 write-design 命名的是同一个 seam）。不要偏离这些术语而使用 “component”、“service”、“layer” 或 “boundary”——术语精准，才能让各次运行的发现具有可比性。

1. 探索摩擦点

先阅读 CONTEXT.md（其中的领域名称有助于识别良好的 seam）和 docs/adr/（避免重新讨论已有决策）。然后派遣一个探索子 Agent，自然地遍历代码库——不要照着僵硬的清单逐项检查，只需留意哪些地方让工作变得困难：

• 模块浅薄——接口几乎与其背后的实现一样复杂
• 局部性差——一个概念上的改动波及多个文件
• seam 缺失或薄弱——需要替换却无法替换，或者存在的 seam 只有一个假设性的 adapter
• 无法通过接口测试——只有越过接口、触及内部实现才能测试代码

对任何可疑之处应用删除测试：如果这个模块消失，调用方需要了解多少内容才能重建其行为？如果答案是“几乎所有内容”，说明模块很浅薄——删除它会使复杂度集中起来，而不是让复杂度消失。这个复杂度集中点就是候选项。

**完成条件：**找出 3–7 个候选项，每个都关联具体模块，并明确指出摩擦类型。

2. 呈现报告

必需子技能：编写任何标记语言之前，先使用 design-page。呈现方式应实用：采用真正的字号层级、选定的配色，不要设计主视觉区——报告是供人快速浏览，而非逐字阅读：置信度徽章和前后对比图必须一目了然。

生成一个自包含 HTML 文件（仅使用内联 CSS/SVG——不使用外部脚本、样式表或 CDN），保存到操作系统临时目录（$TMPDIR，不可用时使用 /tmp；Windows 上使用 %TEMP%），命名为 architecture-review-<timestamp>.html，确保仓库中不会留下任何文件。打开该文件（使用 open / xdg-open / start），并告知用户绝对路径。

每个候选项对应一张卡片：

• 文件——涉及的模块（使用等宽字体列出；本报告是临时文件，因此此处可直接使用路径）
• 问题——用一句话说明痛点及其摩擦类型
• 建议方向——用一句话说明要深化的内容，严格使用规定的术语
• 收益——使用项目符号，每项不超过 6 个词，以特质命名（例如，“局部性：改动集中在一个模块”“接口缩小，测试触及一个 seam”）
• 置信度徽章——只能使用 Strong / Worth exploring / Speculative 之一
• 前后结构示意图——并排绘制（手工构建的 div/SVG）：浅薄与深厚模块的结构图、扇出收敛图、seam 线。示意图本身要能说明问题；如果还需要一段文字解释，就重新绘制。

最后添加首要推荐部分：指出应先选择哪个候选项，并用一句话说明原因。然后询问用户想推进哪个候选项。

暂勿提出具体接口——报告只描述方向，不设计方案。接口的具体形状应留到探讨环节，并让用户参与其中。

**与 ADR 冲突：**与现有 ADR 相矛盾的候选项，只有在证据的置信度为 Strong 时才可纳入；置信度较低时应舍弃，不得列出。纳入的候选项必须标明 ADR 引用，并说明为何值得重新审视该决策。不要列出 ADR 禁止的所有重构。

**完成条件：**报告已在用户的浏览器中打开，并且已询问用户想推进哪个候选项。

3. 塑造选定的候选方案

用户选定后：

• 必须使用子技能：使用 grilling，一次提出一个问题，逐步厘清深化后模块的形态：约束条件、新接口背后的内容、哪些适配器是真实存在的，以及哪些测试可以保留。
• 必须使用子技能：随着决策落地，使用 domain-modeling 处理副作用——新增模块的名称是否对应 CONTEXT.md 中缺失的概念？添加该术语。模糊术语是否在对话中得到明确？立即更新，不要拖到以后。如果用户因为某个关键原因否决候选方案，提供 1–3 句话的 ADR，避免今后的评估再次推荐它（略过临时性或不言自明的原因）。
• 明确说出流程等级——0 表示改动足够小，可以直接进入 tdd；1+ 表示需要先明确需求。

完成条件： grilling 不再有未探索的分支，且已明确说出流程等级为 0 或 1+。

4. 进入规格制定周期

等级 0（机械性改动，不改变行为）可直接按照 tdd/verify 规范推进。等级 1 或更高：必须使用子技能：使用 brainstorm，将塑造好的改进方案交给它，让它按照常规周期推进到需求阶段；架构工作不能豁免于规格审查流程。

完成条件： 工作已进入负责流程——要么按等级 0 的规范进行中，要么已交由 brainstorm 处理。