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