handoff

交接

目标

自动生成一份全面的交接文档，记录当前工作状态、进度和上下文。这适用于复杂任务的“记录并清理”工作流：创建交接文档，/clear 会话，然后稍后通过阅读交接文档恢复工作。

默认情况下，文档会写入仓库根目录，因此它与所描述的工作相邻，你可以按需提交它。传入路径即可将文档放在其他位置。

由于文档位于工作树中，它会显示为未跟踪文件——这意味着后续的 /verify 可能会将它纳入审查范围，而 /create-pr 可能会将它暂存。 如果你不想提交交接文档，请将 handoff-*.md 添加到仓库的 .gitignore 中，或传入仓库外部的路径。

输入

• $ARGUMENTS（可选）：自定义文件名或路径，不含扩展名
  • 默认值：仓库根目录中的 handoff-{timestamp}.md
  • 示例：/handoff → ./handoff-2024-01-15-1430.md
  • 示例：/handoff auth-feature → ./auth-feature.md
  • 示例：/handoff ~/notes/auth-feature → ~/notes/auth-feature.md

流程

1. 验证 Git 仓库

检查当前目录是否位于 git 仓库中（交接文档会记录 git 状态）：

git rev-parse --git-dir

如果检查失败，则创建一份不含 git 上下文的简要交接文档，并提醒用户。

2. 收集 Git 上下文

收集全面的 git 信息：

# Current branch
CURRENT_BRANCH=$(git branch --show-current)

# Base branch (for comparison)
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$BASE_BRANCH" ]; then
  if git show-ref --verify --quiet refs/heads/main; then
    BASE_BRANCH="main"
  elif git show-ref --verify --quiet refs/heads/master; then
    BASE_BRANCH="master"
  else
    BASE_BRANCH="HEAD"
  fi
fi

# Commit history on current branch
git log --oneline $BASE_BRANCH..HEAD 2>/dev/null || git log --oneline -5

# Commits ahead count
COMMITS_AHEAD=$(git rev-list --count $BASE_BRANCH..HEAD 2>/dev/null || echo "unknown")

# Changed files with status
git diff --name-status $BASE_BRANCH...HEAD 2>/dev/null

# Uncommitted changes
git status --porcelain

# Recent commits with full messages
git log -5 --format="%h - %s%n%b" --no-merges

# Current git user
GIT_USER=$(git config user.name)
GIT_EMAIL=$(git config user.email)

3. 检查现有 TODO 列表

如果本次会话中使用过任务列表，应在文档中包含其当前状态：

• 检查是否有活跃的 TODO 列表
• 按状态对任务分类（已完成、进行中、待处理）
• 在交接文档中包含任务说明

4. 收集文件上下文

为已更改的文件提供上下文：

# Count changes by status
git diff --name-status $BASE_BRANCH...HEAD | awk '{print $1}' | sort | uniq -c

# Group files by directory
git diff --name-only $BASE_BRANCH...HEAD | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn

# Diff stats for magnitude of changes
git diff --stat $BASE_BRANCH...HEAD

5. 可选：收集用户上下文

仅当有大量工作正在进行时（超过 3 次提交，或有未提交的更改，或有活跃的 TODO）才使用 AskUserQuestion。

有策略地提出有用的问题：

Question 1: "What's the current blocker or challenge (if any)?"
Options:
- "No blockers - work is progressing smoothly"
- "Waiting on code review or feedback"
- "Technical issue - something not working as expected"
- "Unclear requirements or design decision needed"

Question 2: "What's the most important context to remember?"
Options:
- "Implementation approach or architecture decisions"
- "Key files or functions to focus on"
- "Dependencies or integration points to be aware of"
- "No specific context - handoff document captures it"

只有在能带来价值时才提问。对于简单任务（1–2 次提交，范围明确），跳过提问并自动生成。

6. 生成交接文档

按照以下结构创建全面的 Markdown 文档：

# Handoff: {Work Description from Commits or Branch Name}

**Generated**: {ISO timestamp}
**Branch**: {CURRENT_BRANCH}
**Created By**: {GIT_USER} <{GIT_EMAIL}>

---

## Quick Summary

{One-paragraph summary of what's being worked on, inferred from:
- Branch name
- Recent commit messages
- Changed files
}

## Current State

### Branch Information
- **Current Branch**: {CURRENT_BRANCH}
- **Base Branch**: {BASE_BRANCH}
- **Commits Ahead**: {COMMITS_AHEAD}
- **Uncommitted Changes**: {Yes/No} ({count} files)

### Repository Status

{git status 的输出}

## Work Progress

{If TODO list exists:}

### ✅ Completed Tasks
- {List completed tasks from TODO}

### 🔄 In Progress
- {List in-progress tasks from TODO}

### ⏭️ Pending Tasks
- {List pending tasks from TODO}

{If no TODO list:}

Based on commit history, work appears to be focused on:
{Infer from commit messages what's been done}

## Changes Overview

### Commit History

{显示当前分支提交记录的 git log 输出}

### Files Changed

**Summary**: {X} files ({A} added, {M} modified, {D} deleted)

{Group by directory:}

**{Directory}** ({count} files)
- {file1} (Status)
- {file2} (Status)

### Change Statistics

{git diff --stat 输出}

## Technical Context

{Analyze changes to provide context:}

### Components Modified
- {List major components/modules affected}

### Key Files to Review
{Highlight important files based on:
- Largest changes (diff stats)
- Core functionality (e.g., main.py, app.js)
- New files (might be important)
}

### Dependencies or Integration Points
{Check for changes to:
- package.json, requirements.txt, go.mod, Cargo.toml
- Config files
- API contracts
- Database migrations
}

## Known Issues or Blockers

{If user provided blocker info via AskUserQuestion, include it}
{Otherwise, check for TODO/FIXME/HACK comments in recent changes}

{If found, list them; if not:}
No known blockers documented.

## Key Decisions or Context

{If user provided context via AskUserQuestion, include it}
{Otherwise, extract from commit messages or skip}

## Resumption Guide

### To Resume This Work:

1. **Checkout the branch**:
   ```bash
   git checkout {CURRENT_BRANCH}

2. 审查当前状态：

   git status
   git log {BASE_BRANCH}..HEAD
   

3. 了解更改：

   /catchup  # Use catchup command to get oriented
   

4. {如果存在未提交的更改：} 审查未提交的工作：

   git diff  # See what's changed but not committed
   

5. 继续实施： {如果存在 TODO 列表：}

   • 下一项任务：{TODO 中的第一项待处理任务} {否则：}
   • 查看提交消息以确定后续步骤
   • 检查代码中的 TODO 注释

环境设置

{检查以下内容；如果存在，则纳入文档：}

• 依赖项：{说明 package.json/requirements.txt 等是否有更改}
• 配置更改：{说明配置文件是否有修改}
• 构建/测试：{如有相关性，建议运行测试}

相关资源

{扫描并链接以下内容：}

• docs/design/ 中的设计文档
• 相关问题（检查提交消息中是否有 #123 格式的引用）
• 拉取请求（如果分支已推送到远程）
• 相关任务文件（在 docs/tasks/ 中） }

后续操作

{根据当前状态提出具体的后续步骤：}

立即执行（接下来的 1–2 项任务）：

1. {根据待处理的 TODO 或提交历史推断}

稍后执行（后续工作）：

1. {根据分支范围或提交消息推断}

---

如何使用此交接文档：

• 将本文档复制到你的笔记或项目管理工具中
• 恢复工作时，先阅读本文档，然后运行 /catchup 以确认当前状态
• 如果工作过程中发现新的上下文，请更新本文档

### 7. Save Handoff Document

Determine filename:

```bash
OUTPUT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
TARGET="${ARGUMENTS%.md}"

if [ -z "$TARGET" ]; then
  FILENAME="$OUTPUT_DIR/handoff-$(date +%Y-%m-%d-%H%M).md"
elif [ "$TARGET" != "${TARGET#*/}" ] || [ "$TARGET" != "${TARGET#\~}" ]; then
  # Looks like a path. Expand a leading ~ ourselves — parameter expansion never
  # tilde-expands, so quoting the result would otherwise create a literal ~ dir.
  case "$TARGET" in
    "~"|"~/"*) TARGET="$HOME${TARGET#\~}" ;;
  esac
  case "$TARGET" in
    /*) FILENAME="$TARGET.md" ;;
    *)  FILENAME="$OUTPUT_DIR/$TARGET.md" ;;   # relative paths anchor to the repo
  esac
else
  # Bare name: sanitize, but never sanitize it down to nothing
  CLEAN_NAME=$(echo "$TARGET" | tr ' ' '-' | tr -cd 'a-zA-Z0-9-_')
  [ -z "$CLEAN_NAME" ] && CLEAN_NAME="handoff-$(date +%Y-%m-%d-%H%M)"
  FILENAME="$OUTPUT_DIR/$CLEAN_NAME.md"
fi

mkdir -p "$(dirname "$FILENAME")"

使用 Write 工具将交接文档写入文件。

8. 告知用户

输出：

✅ Handoff document created: {FILENAME}

The document includes:
- Branch state and commit history ({X} commits)
- Changed files ({Y} files)
- {If TODOs exist: Task progress (X completed, Y pending)}
- Resumption instructions

📋 Copy the file content to wherever you need it.
📁 File location: {FILENAME}

💡 To resume this work later:
   1. Read the handoff document
   2. Run /catchup to verify current state
   3. Continue from where you left off

错误处理

不在 Git 仓库中

⚠️  Warning: Not in a git repository.

Creating minimal handoff without git context...

继续生成一份较简单的交接文档，记录：

• 当前工作目录
• 活跃的 TODO 列表（如有）
• 通过 AskUserQuestion 收集的用户上下文

未检测到更改

ℹ️  No commits or changes detected on this branch.

Creating minimal handoff with current directory state...

包含：

• 当前目录
• 工作目录中的文件列表（ls）
• 用户提供的上下文

分离 HEAD 或复杂状态

⚠️  Warning: Detached HEAD state detected.
Current commit: {hash}

Including state snapshot in handoff...

写入失败

❌ Error: Could not write to {FILENAME}

Possible issues:
- Target directory not writable
- Disk full
- Permission issues

Try specifying a different location:
/handoff ~/my-handoff

输出指南

• 全面：涵盖所有相关背景信息
• 结构清晰：便于浏览和查找信息
• 可执行：包含明确的恢复步骤
• 自动化：尽量减少手动输入，除非确有价值
• 便于移植：使用 Markdown 格式，方便复制/粘贴

使用示例

# Basic usage - auto-generated filename
/handoff

# Custom filename
/handoff auth-refactor

# After significant work, before taking a break
/handoff user-api-work

# Before handing off to teammate
/handoff feature-x-for-alice

# After /handoff, typical workflow:
# 1. Copy content from the generated handoff-*.md to your notes
# 2. Run /clear to reset session
# 3. Later: Read your notes, run /catchup, resume work

与其他命令集成

此命令与以下命令配合良好：

• /clear - 执行 /handoff 后，确认状态已记录，再清除会话
• /catchup - 恢复工作时，使用 /catchup 验证交接信息是否准确
• /create-pr - 创建 PR 前，使用 /handoff 记录要提交的内容
• /check-ci - 执行 /handoff 后，确保测试通过再暂停工作

高级功能

智能 TODO 集成

如果任务列表处于活动状态：

• 列出所有任务及其状态
• 将下一个待处理任务标记为“从这里开始”
• 注明是否有任务受阻

提交消息分析

解析提交消息中的：

• 问题编号（#123）→ 链接到对应问题
• 重大变更（BREAKING:、breaking change）
• 正在进行的工作（消息中的 WIP、TODO、FIXME）

文件重要性启发式

在“关键文件”部分优先列出：

• 变更行数最多的文件（diff 统计）
• 符合以下模式的文件：main.、index.、app.、_test.*
• 新文件（可能包含核心功能）
• 配置文件（变更可能影响设置）

上下文保留

保留临时上下文：

• 会话中设置的环境变量
• 最近运行的构建/测试命令
• 已采取的调试步骤
• 聊天中做出的决定

最终说明

1. 自动化优先：只有确实有价值时才向用户提问
2. 推断意图：利用提交消息和文件变更了解工作内容
3. 完整全面：宁可多提供背景信息，也不要遗漏关键信息
4. 格式统一：一致的结构便于阅读交接内容
5. 可执行：始终包含明确的“后续步骤”和“恢复指南”
6. 便于移植：默认使用仓库根目录；由用户决定最终存放位置
7. 快速：对于常见分支，在 10 秒内生成

目标是让暂停复杂工作变得毫不费力，并能在之后带着完整上下文继续进行。

---

最初改编自 mattpocock/skills，MIT © 2026 Matt Pocock。复制此文件时请保留此行。