工程交接与架构归档指南 (Engineering Handover & ADR & SOP)

你好！当你在一次开发会话中完成了关键攻坚、做了重要技术选型、或者跑通了一套复杂的运维跑批流程时，把这些成果及时沉淀下来，是保证后续其他同学或新会话 Agent 能无缝接力、不踩重复坑的最稳妥方式。

一、 框架定位：HDD (Handoff-Driven Development)

本 Skill 属于 HDD 体系的 Handoffs 层：

• 职责核心：专职解决跨会话、跨模型周期的“状态机转移、物理事实防幻觉与真理知识沉淀”；
• 非目标 (Non-Goals)：本 Skill 不做日常编码流程的裁判（不强制 TDD、不限制具体的开发范式），只负责在阶段性收口或交接时打出高保真断点；
• 抗模型迭代衰减：无论未来底层大模型推理能力如何升级，AI 均无法凭空预知你的私有业务决策、客观时序冲突与当前跑批状态。结构化的 Handoffs 是系统长期演进中抵御遗忘的最坚固防线。

本 Skill 采用控制逻辑与参考模板分离的轻量设计：主文件负责流程导航，骨架模板按需单点查阅。

二、 快速确定文档类型 (ADR / SOP / Handover)

根据当前会话的核心成果，挑选最契合的一个类型，并查阅对应的模板文件：

提示：如果用户未指定类型，且当前会话主要是修了 Bug、优化了业务代码并跑通了验证，请默认采用 Handover 类型。

三、 两步正向直出工作流 (SOP)

当被触发执行归档交接时，请直接执行以下两个步骤，杜绝无意义的中间态工具调用：

第一步：查阅对应模板并落盘文档

1. 物理事实核验（杜绝文件幻觉）：
   • 绝对不要凭多轮对话的模糊记忆盲猜改动文件。在列出“改动清单”和“核心代码资产”之前，先锚定真实的物理事实：
     • 若工作区存在 Git：运行 git status -s 查看真实改动；
     • 若工作区非 Git：核实本会话实际通过 write_to_file 或 replace_file_content 动过的文件，或在终端检查目标模块最近修改的文件时间戳；
   • 真实存在性保障：文档中引用的每一个文件路径与链接，必须在磁盘中真实存在，严禁凭空构造不存在的辅助脚本或类库。
2. 规范模板要素（路由地图 + 正向资产交互）：
   • 必须在顶部包含清晰扁平的 路由式摘要（注明当前状态、关键决策、改动范围、接班即刻动作及重点必读章节）；
   • 涉及大型数据底册或日志时，在涉及文件清单中正向注明抽样或 grep 建议，杜绝大篇幅罗列禁区的“负向激发反模式（粉色大象）”。
3. 按需查阅模板：使用 view_file 查阅上述对应的单个模板（例如确定写 ADR 则仅阅读 references/adr_template.md，无需阅读其他模板）。
4. 生成命名并落盘：
   • 文件名规范：YYYY-MM-DD_<topic_slug>.md（如 2026-09-18_quality_gates_upgrade.md）；
   • 写入对应业务模块下的 docs/handovers/ 目录；
   • 使用 write_to_file 工具直接写入目标目录。

第二步：更新归档索引表 (README.md)

1. 使用 view_file 查阅该目录下的 README.md。
2. 时间序归档表追加：在 ## 归档索引 表格的最上方（紧随表头后第一行），插入本次新文档的归档行：

   | YYYY-MM-DD | [YYYY-MM-DD 文档标题](./文档文件名.md) | 核心主题摘要（2~3 句话清晰提炼） | 状态标签 |

3. 主题与分类导航同步：若该 README 维护了按主题分类导航（如 ### 架构决策 (ADR)、### 运维指南 (SOP) 等板块），同步在该分类列表下追加对应的超链接与一句话定位，实现时间序与主题序双维检索。
4. 使用 replace_file_content 将新增内容合并入 README.md，保持索引看板永远最新。

四、 写作风格与接班导引

• 老程序员带新人的口吻：语言平实、温和、逻辑严谨，多解释“为什么要这样做”，避免使用生硬或压迫性字眼；
• 信息高保真度：严禁含糊其辞，关键代码使用可点击的 Markdown 文件链接，运维操作给出完整的带参命令行，验证给出明确的测试断言与耗时；
• 新 Agent 快速冷启动：新接手的 Agent 进入项目时，只需查阅 docs/handovers/README.md 顶部的最新交接文档，通过顶部的 路由式摘要 建立大局观，再按指引跳转到关键章节，即可在 10 秒内理解当前系统状态并执行下一步操作。