handoff

ハンドオフ

目的

現在の作業状況、進捗、コンテキストを記録した包括的なハンドオフ文書を自動生成します。これは、複雑なタスクで「記録してクリア」ワークフローを実行するためのものです。ハンドオフ文書を作成し、セッションを /clear してから、後でハンドオフ文書を読んで作業を再開します。

文書はデフォルトでリポジトリのルートに書き込まれるため、説明対象の作業と同じ場所に置かれ、必要に応じてコミットできます。別の場所に置くには、パスを指定してください。

作業ツリーに作成されるため、未追跡ファイルとして表示されます。つまり、後続の /verify でレビュー対象に含まれたり、/create-pr でステージングされたりする可能性があります。 ハンドオフ文書をコミットしたくない場合は、リポジトリの .gitignore に handoff-*.md を追加するか、リポジトリ外のパスを指定してください。

入力

• $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/ 内の設計ドキュメント
• 関連する Issue（コミットメッセージに #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）
• ユーザー提供のコンテキスト

Detached 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 のスマートな連携

タスクリストが有効になっている場合：

• すべてのタスクとそのステータスを含めます
• 次に着手する保留中のタスクを「ここから開始」として強調します
• ブロックされているタスクがあれば記載します

コミットメッセージの分析

コミットメッセージを解析して、次の情報を確認します：

• Issue 番号（#123）→ Issue へのリンク
• 破壊的変更（BREAKING:、breaking change）
• 作業中であることを示す語句（メッセージ内の WIP、TODO、FIXME）

ファイルの重要度に関するヒューリスティック

「主なファイル」セクションでは、次のファイルを優先します：

• 変更行数が最も多いファイル（差分統計）
• 次のパターンに一致するファイル：main.、index.、app.、_test.*
• 新しいファイル（中核機能の可能性があります）
• 設定ファイル（変更がセットアップに影響する可能性があります）

コンテキストの保持

一時的なコンテキストを保持します：

• セッションで設定された環境変数
• 最近実行したビルド／テストコマンド
• 実施したデバッグ手順
• チャットで決定した内容

最終指示

1. まず自動化：本当に価値がある場合に限り、ユーザーに質問します
2. 意図を推測：コミットメッセージとファイルの変更から作業内容を把握します
3. 漏れなく記載：重要な情報を漏らすより、追加のコンテキストを含める方を優先します
4. 標準形式：構成を統一することで、引き継ぎを読みやすくします
5. 実行可能にする：常に明確な「次のステップ」と「再開ガイド」を含めます
6. ポータブルにする：リポジトリのルートを既定の保存先とし、最終的な保存場所はユーザーに委ねます
7. 高速にする：一般的なブランチでは 10 秒以内に生成します

複雑な作業をスムーズに中断し、コンテキストを完全に保ったまま後で再開できるようにすることが目標です。

---

Originally derived from mattpocock/skills, MIT © 2026 Matt Pocock. このファイルをコピーする場合は、この行を残してください。