scan-architecture

改进架构

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

术语必须始终严格统一：module、interface、implementation、seam、adapter（另加作为特质的 depth/locality/leverage）——seam 是一个公共表面，其行为既可观察又可替换（test-first 和 design-solution 使用的是同一个 seam）。切勿偏离这些术语，改用“component”“service”“layer”或“boundary”——名词精准，才能让不同轮次的发现保持可比。

1. 明确立场

扫描从这里开始，先于任何阅读。运行它，不要估算：

cd <repo root> && python3 <skill-root>/scripts/posture.py --days 180

工作目录决定测量哪个仓库——从待扫描的仓库中运行，绝不要从 skill 自身的文件夹运行。

它会打印并记录四项内容：规则的 mechanised/total 数量，并列出仅由文字描述的规则 ID；变更局部性（每次提交涉及的文件和模块数的中位数，以及涉及多个模块的提交占比）；跨模块共同变更的配对；以及变更最多的文件。没有检查机制保障的规则只是愿望，这个计数说明仓库背负着多少这样的规则。

记录保存在 .skills/scan-architecture/posture.json（本地保存，绝不提交）。如果该文件已存在，每个数字都会附带自上次扫描以来的变化量——这个变化量是上次选中的方案是否产生影响的唯一证据。

然后，在掌握这些数字后阅读 CONTEXT.md（其中的领域名称有助于找出良好的 seam）和 docs/adr/（其中记录了不应重新讨论的决策）。共同变更的配对和变更最多的文件会指出应优先检查的模块：只有历史才能揭示的设计缺陷，不会在阅读代码时浮现。

完成条件： 已写入 posture.json，并且你能清楚说出仅由文字描述的规则 ID。

2. 探查摩擦点

派遣一个 explore 子 Agent 遍历代码库，从 posture 指出的模块开始，再自然地继续探索，不必遵循僵硬的检查清单，只需记录工作中令人棘手的地方：

• 浅层模块——接口几乎和其背后的实现一样复杂
• 局部性差——一个概念上的变更会扩散到许多文件
• 缺少或薄弱的 seam——需要替换的地方无法替换，或者虽有 seam，却只有一个假设性的 adapter
• 未通过接口测试——只有越过接口、触及内部实现，代码才可测试

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

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

3. 呈现报告

必需子技能：编写任何标记之前，先使用 craft-page。整体采用实用主义风格——使用真正的字号层级，选定配色，不设主视觉；报告是供人快速浏览的，而不是逐字阅读的：置信度徽章和前后结构草图必须一目了然。草图是主要图示：将任务命名为 before/after structure，并遵循 craft-page 的图示规范（按照规范编写的内联 SVG 需手工制作）。

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

必需——报告开头必须是态势栏，并置于任何候选项之前：规则的 mechanised/total 数量及仅以文字表述的 ID、三个 locality 数值，以及仓库自身检查记录的任何未解决例外项。如果存在先前态势，每项都要标出变化量。这部分供后续扫描时对比，因此要展示数字，而不是文字描述。

逐字段读取 posture.json 来构建态势栏——页面上的每个数字都必须从该文件复制，绝不能凭记忆引用本轮会话中的先前数据。如果文件中有实际数字，态势栏却显示 0/0、first scan 或短横线，就是捏造态势，会污染之后每次扫描的变化量。

每个候选项使用一张卡片：

• 文件——涉及的模块（使用等宽字体列出；这份报告是临时的，因此可以使用路径）
• 问题——用一句话说明痛点及其所属的摩擦类型
• 建议方向——用一句话说明需要深化什么，严格使用规定的词汇
• 收益——列出不超过 6 个词的要点，并以特质命名（“locality：更改只影响一个模块”“接口缩小，测试聚焦于一个接缝”）
• 置信度徽章——只能是 Strong / Worth exploring / Speculative 之一
• 前后结构草图——并排展示规范 SVG（before/after structure）：浅层与深层的体量示意图、扇出收敛、接缝线。让草图承载论点；如果需要一整段文字才能解释，就重新绘制。

结尾添加首要建议部分：指出应先处理哪个候选项，用一句话说明原因，并指出接下来要交给检查的一条仅以文字表述的规则——这是下次扫描前让态势发生变化的最省力方法。然后询问用户想推进哪个候选项。

暂时不要提出具体接口——报告只说明方向，不描述设计。接口形态应在澄清决策步骤中由用户参与确定。

**ADR 冲突：**只有当证据的置信度徽章为 Strong 时，才纳入与现有 ADR 冲突的候选项；置信度较低的候选项应舍弃，而不是列出。纳入时，注明 ADR 引用，并说明为何值得重新审议此决策。不要列出 ADR 禁止的所有重构方案。

**完成条件：**态势栏包含步骤 1 中的所有计数，报告已在用户的浏览器中打开，并且你已询问用户要推进哪个候选项。

4. 明确所选候选项的形态

用户选定后：

• 必需子技能：使用 clarify-decisions——每次提出一个问题，逐步明确要深化的模块形态：约束、新接缝背后的内容、哪些适配器是真实存在的、哪些测试会保留。
• 必需子技能：随着决策逐步确定，针对副作用使用 define-domain——如果新增模块以 CONTEXT.md 中缺失的概念命名，就添加该术语。若对模糊术语的定义在对话中变得明确，立即更新，不要拖到之后。如果用户基于关键原因拒绝某个候选项，就提供一份 1–3 句的 ADR，避免未来扫描再次推荐该方案（对于临时性或不言自明的原因则跳过）。
• 明确说明仪式级别：0 表示改动足够小，可以直接进入 test-first；1+ 表示需要先编写需求。

完成条件：clarify-decisions 已没有尚未探索的分支，并且已明确说明仪式级别为 0 或 1+。

5. 推进规格周期

Tier 0（机械性改动，不改变行为）可直接按照 test-first/prove-claim 纪律推进。Tier 1 及以上：必须使用 REQUIRED SUB-SKILL：frame-change——将整理好的改进交给它，让它按照常规周期推进到需求阶段；架构工作也不能免于规格关卡。

完成条件： 这项工作已有负责人流程——要么正按照 Tier 0 纪律推进，要么已交给 frame-change。