# Design Handoff

> 为项目设计新功能/系统并交接给新会话实施：先调研验证（读代码和依赖源码落实事实，不靠猜），产出 spec（.local/docs/design/spec/）+ 实施 plan（.local/docs/design/plan/），创建跨会话沟通频道（.local/agent-work/channel/<主题>/HANDOFF.md）。当用户要求「设计 XX」「写 spec 和 plan」「做 handoff / 交接给新会话」「安排新会话实施」时使用。

- Skill: `jaxton07/design-handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jaxton07/design-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jaxton07/design-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Jaxton07 (https://skillmd.com/u/jaxton07)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jaxton07/design-handoff

---


# 设计 + 交接流程（发起会话用）

把「想清楚 → 写下来 → 交给下一个会话」固化为三份产物：**spec**（决策层）、**plan**（文件级执行）、**HANDOFF**（新会话入口）。目录不存在就先建（`mkdir -p`）。

## 第 0 步：调研与验证（最重要，别跳过）

1. 读项目索引与相关代码（若项目维护了 `.local/docs/INDEX.md` 或根目录 `AGENTS.md` / `CLAUDE.md`，先读它们）。
2. **验证而非猜测**：凡涉及 SDK/API/外部依赖行为的关键论断（函数签名、覆盖语义、默认值、扫描范围），必须读 `node_modules` / 依赖包里的源码或 `.d.ts`，或官方文档落实，并记录出处（文件:行）。
3. 已有的 UI/基础设施要先盘点——很多时候「半边已经完工」（比如渲染层已有对应组件/解析逻辑），设计只需补缺的那半。
4. 方案对比要有结论：列对比表，说明为什么否掉备选（如「子进程方案在打包态不可用」），不要只列可能性。

## 第 1 步：写 spec — `.local/docs/design/spec/<主题>.md`

决策层文档，回答「为什么这么做」，**不含文件级任务拆分**。结构惯例：

- 背景与现状盘点（已有什么、缺什么、为什么现成方案不可用）
- 目标 / 非目标（非目标写清本期边界，防实施会话膨胀范围）
- 核心决策（对比表 + 一句话机制）
- 架构与代码位置（目录结构、改动点归属哪个模块/包）
- 契约（参数 schema、跨模块/跨进程类型、数据形状——精确到字段）
- 安全清单（输入校验、权限、数据隔离等，按项目情况）
- 里程碑（P1/P2 分期）
- **风险与已验证事实**：第 0 步验证的结论逐条列出处；验证不了的标为「待验证」，交给 plan 阶段 0

## 第 2 步：写 plan — `.local/docs/design/plan/<主题>-plan.md`

执行层文档，给实施会话照着做。结构惯例：

- **阶段 0 冒烟验证**：把 spec 里每个「待验证」变成一个可执行断言脚本（最小可运行脚本 + 明确通过标准）；**卡点处理规则写死：失败回 channel 留言，不许绕过**（后续决策依赖这些事实）
- 后续阶段按文件拆任务：每个任务写清新建/修改哪个文件、做什么、配什么测试
- 验收清单：项目自带的 lint / typecheck / test 全绿 + 逐项手测步骤 + 收尾纪律（关闭测试过程中起的服务/进程、更新项目索引）
- 「明确不做」清单（与 spec 非目标呼应）
- 引用 spec 而非重复其内容

## 第 3 步：建沟通频道 — `.local/agent-work/channel/<主题>/HANDOFF.md`

新会话的唯一入口，自包含、不依赖本次聊天记录。必含：

1. **任务一句话** + 完成定义（= plan 验收清单全过 + 用户 review 通过）
2. **必读文档顺序**：HANDOFF → spec → plan → `AGENTS.md` + 项目索引（如有）
3. **关键约束**：项目通用纪律（以仓库根 `AGENTS.md` / `CLAUDE.md` 约定为准，如数据隔离、零破坏性变更、代码风格等）+ 本任务特有的硬约束（如递归防护、目录隔离）
4. **已验证事实表**（事实 | 出处）——实施会话直接采信，禁止重复考证
5. **待决策点**：实施中遇到二选一时自行决策并记录进 IMPL-NOTES
6. **沟通协议**（见下）

### 沟通协议（写进 HANDOFF，跨会话只认文件不认聊天）

- 实施会话：进度/卡点/决策追加写 `IMPL-NOTES.md`（倒序、每条带日期时间、标注阶段）；完成后写 `DONE.md`（验收清单逐项打勾 + 改动文件清单 + 自测记录）
- review 方：意见追加写 `REVIEW.md`；实施会话开工前先读它（存在的话）
- spec/plan 与代码现状冲突 → 停下来在 channel 留言，**不要自由发挥**

## 第 4 步：收尾

**不要把 spec/plan 文件写进项目索引（如 `.local/docs/INDEX.md`）**——用户会不定期清理过时的 spec/plan，不一定记得同步索引，所以索引只标目录（`design/spec/`、`design/plan/`、`channel/`），不标单个文件。HANDOFF.md 里有完整路径，可发现性靠频道目录本身。

回复用户：交付物清单 + 关键决策摘要 + 「新会话从 channel 的 HANDOFF.md 进」。

## 反模式

- spec 里堆实现细节 / plan 里重复设计论证——两层分离
- 未验证的 API 断言直接写进设计当事实
- HANDOFF 引用「见上面的讨论」——新会话没有上面