architecture

找出结构难以改变之处，并提出 加深方案：将更多行为收纳到更小的接口之后，让代码更易于测试，也更便于 Agent 浏览。

如果是全新的代码库或区域，目前还没有值得查找的摩擦点。此时跳过搜索，直接进入访谈（第 3 步），确定结构和惯例，并将结果写入 ARCHITECTURE.md。

此技能负责的惯例列在 conventions/ 中，只有工作涉及这些惯例时才加载；implement 会在构建时遵循它们。

默认采用快速模式：只搜索用户指出的区域或摩擦点，展示最有力的几个候选方案，并暂不提供并行接口设计，除非用户要求。深度模式（deep 技能处于启用状态）：检查整个代码库、列出所有候选方案，并为选中的方案提供并行接口设计。

术语

始终使用 LANGUAGE.md 中的术语：模块、接口、实现、深度、接缝、端口、适配器、杠杆效应、局部性。偏离这些术语，改用“组件”“服务”“API”或“边界”，会模糊这项技能旨在厘清的区别。它最常依赖的检查方式：

• 删除测试：移除模块会让复杂性消失（说明它只是转手传递），还是会让复杂性重新出现在每个调用方（说明它发挥了作用）？
• 测试应跨越调用方所跨越的接口。
• 第二个适配器填补接缝后，这个接缝才算真实存在。
• 有多个使用方的接口就是一项承诺。 通过新增内容来加深其背后的实现，绝不重塑调用方所依赖的内容；对其进行破坏性更改属于需要规划的迁移，而不是可以顺手进行的重构。

领域模型指导工作方向：良好接缝的命名取自 CONTEXT.md，而 docs/adr/ 中的决策已成定论，不是待讨论的问题。格式参见：TERMS.md、DECISION-RECORD.md。

流程

1. 调查

从已有文档入手：ARCHITECTURE.md（记录模块、接缝和不变量的最新地图；只需重新推导发生变化的部分）、包含各上下文术语表的 CONTEXT.md 或 CONTEXT-MAP.md，以及区域附近的 ADR。文件缺失时无需提及，但有一个例外：对于没有 ARCHITECTURE.md 的非简单代码库，只提出一次建议，询问是否要根据本次工作，使用 FORMAT.md 为其建立该文件，并且只写入用户确认的内容。

然后阅读用户指定区域内的代码；如果运行环境会调度子 Agent，就在子 Agent 中阅读，否则就在此处阅读。顺着摩擦点调查，不要照着清单逐项检查。值得留意的迹象：

• 理解一个概念需要逐一查看许多小模块。
• 接口几乎和其背后的代码一样复杂。
• 提取纯函数只是为了测试，但 Bug 实际出在调用方式上。
• 模块彼此纠缠，改动一个模块会波及相邻模块。
• 代码没有测试，或者现有接口无法支持编写任何测试。

对每个看起来较浅的模块运行删除测试。

2. 提出方案

按编号列出加深候选方案。每项包括：

• 文件：涉及的模块。
• 摩擦点：当前结构造成的困难。
• 改动：用通俗的话说明哪些内容会迁移。
• 收益：对杠杆效应和局部性的提升，以及改动后测试会是什么样。

领域概念使用 CONTEXT.md 中的术语，结构概念使用 LANGUAGE.md 中的术语：写“开具 Invoice 的模块”，而不是“InvoiceHelper”或“invoice service”。

与 ADR 冲突的候选方案，只有在摩擦点足以成为重新审议该 ADR 的理由时才列出，并明确标注，例如：“重新审议 ADR-0007，因为……”。ADR 已明确排除的重构方案不要列出。

此时不要提出接口。最后询问用户想进一步探讨哪个候选方案。

3. 访谈

在选定的候选项上运行 core-interview 技能。需要确定的内容包括：约束、依赖（按 DEPENDENCIES.md 排序）、深化后的模块形态、其边界背后的内容，以及哪些测试得以保留。

确定一项，就记录一项：

• 如果深化后的模块以 CONTEXT.md 中缺少的概念命名：像 drill 那样添加该术语；如果文件尚不存在，就创建它。如果对话中明确了一个模糊术语：更新其条目。
• 如果新增模块、移动边界或引入新不变量：按照 FORMAT.md 更新 ARCHITECTURE.md。
• 如果用户因某个未来评审需要了解的理由否决了候选项：提出编写 ADR，避免再次提议该候选项。像“暂时不考虑”这样可以通过的理由，或显而易见的理由，无须编写 ADR。
• 所选模块的替代接口：INTERFACE.md。

如果结果是实现工作，则按照 SPEC-FORMAT.md，将规格写入 docs/specs/<slug>.md，以深化后的接口和保留的测试作为验收标准，并交给 implement。