AlemTuzlak/skills

Touch Map（变更触及图）

构建一份本变更必须触及哪些部分的心智地图。不要编写实现计划。不要编写代码。不要加载流水线中的下一个技能。后续的工作流技能会将此地图与其他技能衔接。

地图本身就是产物：即完成该变更所需的部件和文件。

何时使用

在用户已经决定变更是什么以及他们已选择的任何如何之后加载。

• **适用于：**新功能、错误修复、移动边界的重构。
• **跳过：**错别字、注释、格式化、仅锁文件变更、无代码的文档。
• 如果意图仍不明确（例如“实现X”但未选择具体行为）：停止。询问直到变更确定。然后再绘制地图。不要为尚未确定的特性绘制地图。

硬性关口

1. 不要编写代码，也不调用下一个技能。 本技能只负责绘制地图。它不规划代码块，也不实现功能。
2. 展示地图后立即停止。 不要等待批准。如果地图有误，用户会主动打断。
3. 不要读取 coupling.json。 那是一个后续的、独立的检查。
4. 不要遍历整个仓库查找工具函数。 仅记录代理在实际涉及的域名中看到的复用代码。后续技能会负责全面搜索。

持久化域映射

路径：<repo>/.agent/domain-map.json

随仓库一同提交。仅限域粒度。函数名不应出现在此处。

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — 短名称，一个单词或使用短横线命名法（kebab-case）。
• owns — 包或文件夹路径。
• talksTo — 其他域的 ID。

**仅当域级别的信息发生变化时才写入此文件：**添加、删除或重命名域；owns 路径；或 talksTo 链接。在现有域内添加一个函数不得编辑此文件。

流程

流程 1：确认已明确的意图

1. 如果变更已经清晰（已知的 Bug 名称、函数名称、行为名称），继续。
2. 如果用户仍在选择他们想要的内容，停止绘制地图。询问直到意图明确。然后返回此处。

流程 2：加载或引导初始化域映射

1. 如果 .agent/domain-map.json 存在，读取它。
2. 如果缺失，在仅限域粒度下构建初始域映射：
   • 优先使用 packages/*（或仓库的包文件夹）。
   • 否则使用 src/（或主源码根目录）下的顶层区域文件夹。
   • 根据这些 owns 路径之间的导入边设置 talksTo。
   • 不要在域映射中包含函数名。
3. 按需创建 .agent/ 目录。写入文件。在同一个会话回合中展示新的域映射。继续。不要等待。

流程 3：聚焦本变更

1. 根据域映射和已明确的意图，选择涉及的域。
2. 从明确属于本变更的模块开始。
3. 读取这些文件。仅在“待触及文件列表”仍在变化时追踪导入。
4. 当新打开的文件不再改变地图时停止。不要为了完整性而读取整个包。
5. 将部件命名为模块加上本变更将使用或紧邻的现有函数和类型。文件是指针，不是地图本身。
6. 记录在这些文件中实际看到的复用代码（路径 + 符号）。不要为了查找辅助函数而全局搜索整个工作区。

流程 4：如果存在多条路径，选择一条

如果只有一条诚实的路径，用一行陈述。

如果存在多条路径，选择一条。在决定性的梯子第一步停止：

1. 复用已有的内容，而不是编写新模块。
2. 留在涉及的域名内。不要打开新域。
3. 如果内部变更可行，不要添加新包、层或公共 API。
4. 然后是文件数量最少。

命名胜出的路径以及它是由梯子的哪一步决定的。文件数量最少是平局决胜项，而非完整规则。不要为了赢得文件数量而将新行为塞进一个神级文件。

流程 5：更新域映射（仅限域级别）

1. 如果本变更添加、删除或重命名了域，或更改了 owns / talksTo，在同一个工作回合中修补 .agent/domain-map.json。
2. 如果在域粒度上没有变化，保持文件不变。

流程 6：展示按变更绘制的触摸图

按顺序展示以下六个板块。不要编写每个任务的 markdown 文件。

1. 命中域 — 来自域映射。
2. 部件 — 模块以及涉及的现有函数和类型。包括已见的复用代码（路径 + 符号）。
3. 它们如何通信 — 仅本变更使用的边（调用、类型、数据）。不是完整的调用图。仅当这些边在无序列表中难以看清时才添加 Mermaid 图。
4. 待触及的文件 — 最终的文件列表。这是独立的产物。
5. 不会触及的文件 — 明确声明。防止附带编辑。
6. 路径选择 — 如果只有一条路径，用一行说明。如果存在多条路径，则说明胜出的路径及其梯子步骤。

流程 7：停止

1. 完成流程 6 后停止。
2. 不要编写代码。不要从本技能中加载另一个技能。

决策树

• 意图未明确 → 流程 1，然后停止直到明确。
• 意图明确，行为变更 → 流程 2 → 3 → 4 → 5 → 6 → 7。
• 错别字 / 注释 / 格式 / 锁文件 / 仅文档 → 本技能不适用。
• 域映射文件缺失 → 流程 2 第二步（引导初始化），然后继续。
• 一条路径 vs 多条路径 → 流程 4。

红线标志

信号	含义	应怎么做
在用户选择特性前绘制地图	意图未明确	流程 1。先追问清楚。
打开 owns 中的每一个文件	巡回参观而非绘制地图	流程 3：当文件列表稳定时停止。
在单体仓库中全局搜索 isRecord	全局搜索属于另一个技能	仅记录已见的复用代码。
读取 coupling.json	错误的文件	将该检查留给后续步骤。
等待地图“看起来不错？”	关口是展示并停止	展示六个板块后立即停止。
在地图绘制后开始编码	本技能只负责绘制地图	流程 7。不写代码。
从此处加载下一个流水线技能	让编排留在工作流	停止。让工作流技能进行编排。
写入 .agent/touch-maps/<task>.md	过时的任务垃圾	仅在聊天（或会话）中保留。域映射文件是唯一的持久化内容。
因为添加了一个辅助函数而编辑域映射	函数粒度出现在域映射中	保持域映射不动。将辅助函数放在板块2中。
优先选择文件数量最少的路径	神级文件陷阱	运行完整的决策梯子。

错误处理

• **不在 git 仓库内：**用六个板块绘制本变更的地图。跳过域映射文件。用一行说明。
• **域映射 JSON 无效：**不要猜测。报告解析错误。仅在用户同意时从流程 2 第二步重新构建，或者如果意图明显（如尾随逗号、缺失括号）则修复 JSON。
• **命中域不明确：**选择能够拥有该变更的最小域名集合。在路径选择中说明不确定性。不要为一个单文件 Bug 发明新域。
• **用户中断指出地图有误：**修正六个板块。如果路径发生变更，重新运行流程 4。然后停止。