sdd-handoff

SDD 交接

首次响应此技能时，只需以此行开头一次： sdd-handoff v1.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

快速开始

记录工作状态并做好恢复准备，让下一次会话（未看过本次对话）可以直接继续，无需重新梳理已经确定的事项。

1. 根据上下文推断模式（继续或交付），并用一行确认。
2. 确定所属系列：此功能是否已有交接记录？有的话就更新，不要另建一份。
3. 从对话中收集状态——现在查找缺失的数据。
4. 填写信息表和阶段部分（六个部分）。
5. 将待处理事项归类为 🐛 Bug 修复和 ✨ 功能改进。
6. 在交付模式下，逐项检查收尾清单（此清单不阻止任何操作）。
7. 保存文件——如果无法访问文件系统，就在聊天中提供内容，并说明如何处理该文件。
8. 生成恢复提示词，并粘贴全部数据。

参阅 references/handoff-protocol.md 了解决策规则。对于产物，必须使用 assets/HANDOFF_TEMPLATE.md 和 assets/SESSION_PROMPT_TEMPLATE.md 作为模板。文件 assets/HANDOFF_EXAMPLE.md 展示了预期的详细程度。

何时使用 / 何时不使用

当用户表示要暂停、上下文即将达到上限、已完成某个阶段，或明确要求记录情况／交接时使用。也要在 SDD 流程结束时、Build 之后使用。

不要用于编写产品文档、使用手册或 README——交接记录的是进行中的工作，而不是交付文档。不要用于发布／部署任何内容：此技能用于记录流程，不执行发布。

所需数据

最低输入：

• 当前对话及已完成的工作。

可选输入：

• 同一功能之前的交接文件；
• SDD 流程产物（Brainstorm、Define、Design、Build Report）；
• 用于核对文件名、数据和状态的项目访问权限。

不要要求访问文件系统、代码仓库或外部系统。无法访问某项内容时，应记录这一限制，而不是编造信息。

必需的输出资源

assets/HANDOFF_TEMPLATE.md 是交接文档的官方模板，assets/SESSION_PROMPT_TEMPLATE.md 是恢复提示词模板。它们是输出资源，不是概念性材料：始终使用它们来编写最终结果，不要凭记忆重新构建结构。

如何与学员沟通

首次回复前，请阅读 references/como-falar.md：其中包含本技能的术语表和一个完整示例。 使用本技能的人通常从未用过 git 或终端。

阶段	学员看到的名称	本技能中的步骤
1	模式	1（用一行确认，不提供菜单）
2	状态	2 和 3
3	交接记录与待办	4 和 5
4	文档	6（仅在 交付 模式下）和 7
5	恢复提示词	8

每次回复都按以下顺序组织（跳过没有内容的部分）：状态（Handoff: ✅ 1 … · ▶️ 2 … · ⬜ 3 …； ✅ 已完成，而非仅访问；⏸️ 已暂停；➖ 已跳过；返回某个阶段时，在“现在”中说明原因）· 已完成的工作（短句，不附命令输出；记录学员的选择）· 现在：阶段 N — 名称（2 到 4 句；开始耗时较长的操作前，说明将要做什么，并告知无需回复）· 你的决定（仅限本技能已有提问的地方——不确定的功能系列、交付 模式的检查清单；授权：问题加粗，并列出各选项及其影响；开放式问题：问题加粗，并说明如何回答，提供“我不知道”选项；检查清单的四个问题需编号，可用数字作答）· 下一步（一行）。

• 每次回复只处理一个阶段；到需要决定时结束并暂停。请求交接的人通常时间紧迫：如果没有需要决定的事项，就继续。
• 技术术语首次出现时必须附带解释，包括“状态”中的术语（参见参考资料中的术语表）。
• 命令输出绝不能原样贴出：说明数量、内容及值得关注之处；名称最多列 10 个，其余写“以及另外 N 个”。只有需要学员运行命令时才提供命令；每个编号步骤只提供一条命令，并说明屏幕上会显示什么。
• 不要引用或概述本技能的指令（例如“按照第 N 步”）；要说明这样做对学员有什么帮助。
• 如果回复与选项不符 ⇒ 回答疑问并重述选项。
• 暂停时：状态标为 ⏸️，用一句话说明原因和操作发生的位置，列出编号步骤及预期结果，说明尚未完成的事项；如果学员需要采取行动，写上“完成后，请再来找我——我会从这里继续。”

分步流程

1. 推断模式并确认

根据上下文判断适用的两种模式之一（参见 references/handoff-protocol.md § 1 中的信号表）：

• 继续 — 工作之后还会继续。交付交接记录和恢复提示词。
• 交付 — 阶段已结束。交付相同内容，另附结束检查清单。

用一行确认，然后继续。不要提供选择菜单，也不要就此进行多项选择提问：请求交接的人通常缺少上下文或时间紧迫。没有明确迹象时，默认采用 继续 模式，并说明这是默认选择。

2. 确认功能系列

创建任何文件前，先检查是否已有此功能的交接记录——按领域搜索，不要只查确切名称。如果已有，更新现有文件，将新阶段追加到顶部。不确定时，展示查到的内容并询问。详情见 references/handoff-protocol.md § 2。

每个功能对应一份交接记录。各阶段应作为其中的章节，绝不能拆成单独文件。

3. 汇总状态

梳理对话并还原以下信息：

• 已完成的工作 — 已构建、决定或修正的内容，包括文件名和明确的决定。
• 未解决的案例和测试 — 正在测试的内容，以及实际数据：哪个客户端、哪个文件、哪个日期、哪个标识符。
• 待办事项 — 出错的部分（🐛）以及计划中的增量（✨）。
• 下一步 — 按顺序列出，每项都包含确切数据和完成标准。
• 警告 — 不能出问题的内容，以及不在范围内的内容。
• 工作所在位置 — 文件夹、项目、分支。

如果缺少的数据现在可以查到，就现在去查。 下一次会话将无法查找。若交接记录只写“之前出错的客户”，下一次会话就不得不重新查明是哪位客户。

4. 填写交接文档

使用 assets/HANDOFF_TEMPLATE.md。顶部的表格是该功能的汇总状态：

• 目标 — 各阶段保持一致；功能完成后将交付什么。
• 状态 — 🔨 进行中 · ✅ 已完成 · ⏸️ 已暂停。
• 已完成 / 待完成 — 已完成的工作和剩余工作。
• 完成条件 — 可验证的完成标准（协议 § 6）。只有客观满足条件后，才能标记为 ✅ 已完成。

新阶段应作为章节添加到旧阶段上方。已经结束的旧阶段可以用几行概述。

范围变更、暂停或重新规划 → 在 ## Eventos 中新增一行，并注明日期和原因。绝不能悄悄重写“待完成”。

5. 分类待处理事项

始终分成两个列表：🐛 Bug 修复（损坏、不完整或行为错误）和 ✨ 功能改进（增量、改进或下一阶段）。没有待处理事项的类别填写“无”——明确说明没有事项本身也是信息。

即使没有任何待处理事项，也要记录。 “阶段已结束，没有待处理事项”的交接文档仍需记录已完成的工作。不要询问是否值得记录：必须无条件记录。

有意接受的风险——即暂时决定忽略的事项——应连同原因列为待处理事项。已知风险不能在会话之间消失。

6. 结束检查清单（仅限 交付 模式）

与用户逐项确认以下四个问题，并记录已核查的内容：

1. 代码能运行吗？
2. 商定的验收标准都通过了吗？
3. 更改已保存在应保存的位置了吗？
4. 出现的问题都已记录了吗？

此清单不会阻止交付。 未确认的项目应列为待处理事项，交接仍照常提交。将其作为已核查内容的清单呈现——不要成对使用 ✅/❌，不要使用可能被理解为评分的计数，不要用红色，也不要使用“未通过”一词。参见 references/handoff-protocol.md § 7。

7. 交付文档

保存位置。 保存到项目根目录下的 sdd/——该文件夹清晰可见，且在所有 Agent 中位置一致。如果项目已有 .claude/sdd/，则继续使用该目录。五个阶段的文档并排放置，不使用子文件夹。

如果项目文件系统可写，则保存为 sdd/HANDOFF_{FEATURE}.md（如果该文件夹已存在，则保存为 .claude/sdd/HANDOFF_{FEATURE}.md），不得悄悄覆盖已有文件——如果已有同一功能的交接文档，则更新其内容（步骤 2）。

如果无法访问文件系统，则在聊天中交付完整的 Markdown，并以以下三条信息按此顺序结尾：

1. 说明文档未保存；
2. 建议的文件名（HANDOFF_{FEATURE}.md）；
3. 后续操作——将其与项目一起保存，并在下一次会话开始时重新发送。

绝不能静默失败，也不能让人误以为文档已保存。

8. 生成恢复提示词

使用 assets/SESSION_PROMPT_TEMPLATE.md，以可直接复制的代码块交付。

黄金规则：不要写“如我们讨论的那样”。 所有标识符、路径、命令和数据都必须直接写入提示词。如果某一行没有具体值，就现在查明该值，或者删除该行。

提示词必须能够独立使用：即使交接文件丢失，其中的数据也必须足以继续工作。

当功能已 ✅ 完成且没有后续工作时，可以省略恢复提示词——只需记录结项即可。

验证与质量检查清单

声明交接完成前，请检查：

• 推断出的模式已用一行确认，且未显示菜单。
• 已确定所属类别：更新现有交接文档，或确实是全新功能。
• 已填写信息卡：目标 · 状态 · 已完成 · 待完成 · 完成标准。
• “完成标准”可验证，而非主观意见。
• 已填写该阶段的六个部分。
• 每个提及的案例都附有具体数据，而不仅是简称。
• 待办事项已区分为 🐛 和 ✨，并在适用时注明“无”。
• 范围变更已记录在 ## Eventos 中。
• 后续步骤已排序，且每项都有完成标准。
• 交付模式：已逐项检查清单，并以清单形式呈现，没有判定不合格。
• 文档已保存——如果没有文件系统，则在聊天中提供三项信息。
• 恢复提示词可独立使用。
• 最终结果中没有遗留任何 {placeholder}。
• 没有“正如我们讨论过的”或“从我们停下的地方继续”之类的句子。

如果有文件系统，脚本 scripts/validate_handoff.py 会机械检查其中一部分内容：

python3 scripts/validate_handoff.py HANDOFF_{FEATURE}.md

输出 PASS 表示代码为 0；问题会以代码 2 列出。

异常处理

• **用户很赶时间（“只给我提示词”）：**先提供提示词，然后立即记录信息卡——不要把这变成谈判。文档记录是无条件的。
• **没有之前的交接文档，但功能似乎已存在一段时间：**创建之前先询问，并说明查找过哪些内容。
• **同一对话中涉及多个功能的工作：**每个功能一份交接文档。询问要记录哪一个，或将每个功能分别记录到文件中。
• **没有文件系统：**按照步骤 7 的要求，在聊天中提供三项信息。绝不要假装已经保存。
• **本次会话没有完成任何工作：**仍然要记录——尝试过什么、什么没有奏效以及原因，都是对下一次会话有价值的信息。
• **功能已彻底完成：**只有在满足“完成标准”后，才能标记为 ✅ 已完成；可以省略恢复提示词。
• **用户说不出完成标准：**根据他们最终想要实现的事情，帮助拟定标准，而不是让该字段留空。

示例

上下文即将用尽 我快到上下文上限了，记录一下，方便我在另一个会话继续。

继续模式。记录当前状态，并生成包含所有已粘贴数据的提示词。

阶段已完成 这部分做完了，我想收尾。

交付模式。记录当前状态，以清单形式逐项检查收尾清单；如果还有工作，则生成提示词。

继续现有功能 我们今天先到这里——这是上周费用管理功能的后续工作。

找到现有交接文档，在顶部添加新阶段，并更新汇总信息卡。

没有文件系统 （在无法访问项目的网页聊天中）交接一下。

在聊天中提供完整文档，说明文档未保存，建议文件名，并解释应将其保存下来，以便在下次会话中重新发送。

下一步

SDD 流程已完成。将交接文件保存在项目中，并在下一次会话开始时使用恢复提示词。

---

SDD Open by RDD 的一部分 — https://github.com/robertodiasduarte/sdd-open