# Handoff

> 生成或读取 Handoff 交接文档。用户说"handoff"、"交接"、"交接文档"、"看前一个 agent"、"上一份 handoff" 时触发。也支持 /handoff 命令。

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

---


# Handoff 交接文档 Skill

## 激活流程

技能激活后，先问用户：**"你是要读一份 handoff（看前一个 agent 做了什么），还是生成一份新的 handoff 交接文档？"**

- 如果用户说 **读** → 执行「读取路由」
- 如果用户说 **写** → 执行「生成路由」
- 如果用户触发词已明确（如"生成交接文档"→ 写，"看看前一个 agent"→ 读），直接走对应路由，跳过询问

---

## 读取路由

### 1. 扫描 handoff 文件

```bash
ls .handoffs/handoff-*.md 2>/dev/null
```

如果没有 `.handoffs/` 目录或没有任何 handoff 文件，告知用户：
> 当前项目没有找到 handoff 交接文档记录。

### 2. 确定读哪一份

- 用户没指定 → 读最新一份（按文件名排序取最后）
- 用户指定了日期（如"看 2026-08-10 的"）→ 读 `handoff-2026-08-10.md`，如果当天有多个版本，取序号最大者
- 如果指定日期的文件不存在，告知用户并用最新一份作为 fallback

### 3. 总结内容

用 Read 工具读取文件，然后按以下模板章节的结构向用户总结：

| 章节 | 总结要点 |
|------|---------|
| 项目概述 | 项目名称、类型、一句话说明 |
| 完成的工作 | 目标 + 核心改动概览 + 几条关键 commit |
| 未完成的工作 | 剩余的高优先项 + 已知问题 |
| 操作指引 | 如何继续的步骤 + 注意事项 |

**不主动执行代码，不检查 git 状态，不推进未完成项。**

---

## 生成路由

### 0. 前置准备

执行 git 提取脚本获取数据：

```bash
# 脚本在 skill 目录下：~/.claude/skills/handoff/scripts/git-extract.sh
# 可用 .cmd 版本（Windows）
bash ~/.claude/skills/handoff/scripts/git-extract.sh    # Bash
# 或 scripts\git-extract.cmd                             # Windows CMD
```

### 1. 收集数据

从以下来源收集信息：

**A. 会话内容（从当前对话提取）**
- 本次会话的目标（用户最初的需求）
- 关键设计决策和理由
- 未完成的工作和已知问题
- 用户偏好（如包管理器、不要 build 等）

**B. Git 提取脚本输出**
- 项目技术栈（package.json、pyproject.toml、go.mod 等元数据 + 目录结构）
- 当前分支名
- 基线 commit（从上一份 handoff 的最后 commit 开始，或最初 commit）
- 从基线到 HEAD 的 commit 日志（表格格式）
- 每个 commit 的变更文件列表
- 关键代码片段（复杂逻辑区域）

**C. 项目结构推断**
- 前端目录结构
- 后端目录结构
- 包管理器类型

### 2. 确定文件名

```
.handoffs/handoff-YYYY-MM-DD.md
```

如果同一天已有文件，追加序号：
```
.handoffs/handoff-YYYY-MM-DD.md       # 第一份
.handoffs/handoff-YYYY-MM-DD-2.md     # 第二份
.handoffs/handoff-YYYY-MM-DD-3.md     # 第三份
```

### 3. 确保输出目录存在

```bash
mkdir -p .handoffs
```

### 4. 生成文档

按以下模板结构生成文档，每个章节的详细模板见 `references/` 目录下的对应文件。

---

## 文档模板

### 1. 项目概述

由 AI 从项目元数据文件和目录结构推断，自动填充。参考 `references/project-overview.md`。

### 2. 本次会话完成的工作

**目标**: 一句话说明本次会话的目标

**Git 节点记录**:

| Commit Hash | 描述 | 关键改动 |
|-------------|------|---------|
| `abc1234` | feat: 添加用户登录 | 新增 `auth/login.tsx`，修改 `api/auth.ts` |
| ... | ... | ... |

**具体改动清单**:

按功能模块分条列出，每条必须包含：
- 修改了哪个文件
- 改了什么（具体到 CSS 变量名、类名、组件名、函数名）
- 为什么这样改（设计决策）
- 关键代码片段（如果涉及复杂逻辑）

**已修改文件列表**:

| 文件路径 | 改动内容摘要 |
|----------|-------------|
| `src/components/Login.tsx` | 新增登录表单组件，使用 `--color-primary` |

### 3. 尚未完成的工作

按优先级分三级：

| 优先级 | 做什么 | 为什么还没做 |
|--------|--------|-------------|
| 高 | 用户密码加密 | 等待后端接口就绪 |
| 中 | 错误提示优化 | 非 MVP 必须 |
| 低 | 添加单元测试 | 功能稳定后再补 |

如果有已知的 bug 或问题，也列在这里。

### 4. 项目约定参考

参考 `references/project-conventions.md`。

AI 根据项目类型自动填充内容。对于前端项目，自动检测 CSS 变量、设计 token、组件库等约定。对于非前端项目，输出架构约定、命名规范、数据流模式等。

### 5. 操作指引

**如何继续**:
1. `cd <project-dir>` 进入项目目录
2. 阅读 `.handoffs/handoff-YYYY-MM-DD.md` 了解上下文
3. 执行 `git log --oneline -5` 查看最新提交

**如何回滚**:
```bash
git reset --hard <commit-hash>
```

**项目启动**:
由 AI 自动检测并生成启动命令

**注意事项**:
- 用户偏好（如"不要 build"、"用 pnpm 而不是 npm"）
- 特殊约定

---

## 写作原则

1. **下一个 AI 不看代码也能操作**: 所有信息必须自包含，不依赖阅读源码
2. **精确到文件和变量**: 不要写"修改了样式"，要写"修改了 `index.css` 的 `--color-primary` 变量"
3. **记录设计决策**: 不只记录"做了什么"，还要记录"为什么这样做"
4. **诚实记录未完成项**: 不要把半成品标为已完成
5. **Git 节点可追溯**: 每个 commit 都要记录，方便回滚
6. **中文撰写**: 所有内容用中文，禁止使用 emoji