---
name: handover
description: 将当前会话中的技术决策、运维流程或阶段性研发进展，归档为标准工程文档（ADR / SOP / Handover），并自动更新模块内的 README 归档索引。
argument-hint: "[adr | sop | handover] [核心主题与简要说明]"
---

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

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

---

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

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

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

---

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

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

| 文档类型 | 适用场景 | 状态标签 (Status 推荐) | 对应参考模板 | 核心目标 |
| :--- | :--- | :--- | :--- | :--- |
| **`ADR`** (架构决策) | 技术选型、航道拆分/合并、引入新库、重大权衡或决定“暂不改动” | `架构决策 (ADR)`、`探讨/提案 (RFC)` | [`references/adr_template.md`](references/adr_template.md) | 讲清为什么选 A 不选 B，避免未来盲目推倒重来 |
| **`SOP`** (运维手册) | 定时任务、周末跑批、凭据更新、自动化巡检、故障排查 | `生产固化 (Active)`、`维护中 (Draft)` | [`references/sop_template.md`](references/sop_template.md) | 给出复制即用的命令与自愈预案，保证无人值守稳定运行 |
| **`Handover`** (研发交接) | 每日收工、攻坚战役完成、门禁规则升级、代码重构收口 | `生产基准 (Current)`、`版本归档 (Archived)` | [`references/handover_template.md`](references/handover_template.md) | 交代今天改了哪、跑了什么单测、明天接班第一步敲什么 |

> **提示**：如果用户未指定类型，且当前会话主要是修了 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`](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. **时间序归档表追加**：在 `## 归档索引` 表格的最上方（紧随表头后第一行），插入本次新文档的归档行：
   ```markdown
   | 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 秒内理解当前系统状态并执行下一步操作。