@Humanophilic_development(九大ヒューマノフィリック開発部)

[ClaudeCode]コンテキスト長が溜まると自動で引き継ぎしてくれるプラグインを開発した

Last updated at 2026-04-01Posted at 2026-03-31

はじめに

Claude Code を長時間使っていると、コンテキストウィンドウが埋まって精度が落ちてきます。

そんなとき /handoff と打つだけで、現在のタスク状況・変更ファイル・作業サマリを自動収集して引き継ぎプロンプトを生成するプラグインを作りました。新セッションを起動すれば、前回の作業コンテキストが自動で注入されます。

GitHub: https://github.com/amu815/claude-handoff

claude plugin install claude-handoff

上記で not found になる場合は、マーケットプレイスを手動で追加してください：

claude plugin marketplace add https://github.com/amu815/claude-handoff.git
claude plugin install claude-handoff

何が問題だったか

Claude Code は強力なAIコーディングエージェントですが、1つのセッションで長時間作業を続けると以下の問題が発生します：

コンテキストウィンドウの圧迫 — 会話履歴が長くなると、古い情報が圧縮・削除される
精度の低下 — コンテキストが長いと、指示の見落としや重複作業が増える
手動引き継ぎの手間 — 新しいセッションを開始するたびに「今何をやっていたか」を説明し直す必要がある

特に3番目が厄介で、タスクの状態・変更ファイル・設計方針など、すべてを正確に伝えるのは意外と難しいです。

解決策：`/handoff` プラグイン

インストール

claude plugin install claude-handoff

not found になる場合：

claude plugin marketplace add https://github.com/amu815/claude-handoff.git
claude plugin install claude-handoff

使い方

セッション中にコンテキストが長くなってきたと感じたら：

/handoff

すると以下が自動で実行されます：

タスク状況を収集 — 完了・未完了のタスクを一覧化
変更ファイルを収集 — git status + git diff --stat の結果
プランを収集 — tasks/todo.md があれば読み込み
セッションサマリを生成 — 「今何をやっていたか」をClaudeが自動要約
追加メッセージ＆セッション設定 — 申し送り入力（任意）＋モデル・effort・パーミッション設定を選択
引き継ぎファイル保存 — ~/.claude/handoffs/YYYY-MM-DDTHH-MM.md に保存
claude update を実行 — 最新版に更新

あとはセッションを終了して案内されたコマンドを実行するだけ。新セッション側では SessionStartフックが引き継ぎファイルを自動注入し、位置引数のプロンプトでClaudeが即座に作業を再開します。

実際の流れはこんな感じです：

新セッションの起動コマンド

/handoff 完了後、Step 5 で選択した設定に応じてClaudeが起動コマンドを案内してくれます：

# すべてデフォルトの場合
claude "前回の引き継ぎを確認して、作業を再開してください"

# モデル・effort・パーミッションを指定した場合
claude --model sonnet --effort high --dangerously-skip-permissions "前回の引き継ぎを確認して、作業を再開してください"

オプション	説明
`--model`	`opus` / `sonnet` / `haiku` またはフルモデルID
`--effort`	`low` / `medium` / `high` / `max`
`--dangerously-skip-permissions`	パーミッションチェックをスキップ（サンドボックス環境向け）

Claude Code は claude "プロンプト" のように位置引数でプロンプトを渡すことができます。これを利用して：

SessionStartフック が ~/.claude/handoffs/ から引き継ぎファイルを検出し、コンテキストとして注入
位置引数のプロンプト がClaudeへの最初のメッセージになる

この2つが同時に発動するため、新セッションが開いた瞬間にClaudeが引き継ぎ内容を読み、サマリの表示と作業の再開を自動で行います。claude だけで起動した場合は、ユーザーが最初のメッセージを入力するまで待機します。

引き継ぎファイルの中身

保存される引き継ぎファイルはこんな感じです：

# Handoff: 2026-03-30T14-30

## Session Summary
claude-handoff プラグインの実装を進めていた。
plugin.json、hooks.json、3つのシェルスクリプト、SKILLファイルを作成完了。
コードレビューで発見された cross-platform 互換性の問題を修正済み。
次はGitHub pushが残っている。

## Task Status
- [x] Tasks 1-6: プラグインファイル実装
- [x] Spec + quality review
- [x] ローカルテスト
- [ ] GitHub push


## Changed Files
M scripts/stop-check.sh
M scripts/session-start.sh
M skills/handoff/SKILL.md
M README.md

## Plan
(tasks/todo.md の内容がここに入る)

## Additional Notes
GitHub push後にREADMEのインストールコマンドが正しく動くか確認すること

アーキテクチャ

プラグインの構成はシンプルです：

claude-handoff/
├── .claude-plugin/
│   ├── plugin.json          # プラグインメタデータ
│   └── marketplace.json     # マーケットプレイス定義
├── hooks/
│   └── hooks.json           # SessionStart フック定義
├── scripts/
│   ├── session-start.sh     # 新セッション起動時に引き継ぎ注入
│   └── handoff.sh           # ランチャースクリプト（将来用）
├── skills/
│   └── handoff/
│       └── SKILL.md         # /handoff コマンド定義
├── README.md
└── LICENSE

フック仕組み

SessionStartフック (session-start.sh)：

~/.claude/handoffs/ から最新の .md ファイルを取得
ファイルが 10分以内 に作成されたものだけを読み込む（古い引き継ぎは無視）
内容をJSON形式で systemMessage として出力 → 新セッションに注入

なぜ手動コマンドなのか

自動検知も技術的には可能ですが、あえて 手動の /handoff コマンド にしました。理由は：

セッション終了時に自動ブロックされると煩わしい
「今じゃないんだよなあ...」という場面がある（重要な処理の途中など）
ユーザーが引き継ぎのタイミングを完全にコントロールできる

Requirements

Claude Code CLI
Python 3（フックでのJSON エスケープに使用）

Cross-Platform対応

Linux と macOS の両方で動作します：

stat コマンドの差異（-c %Y vs -f %m）を uname で判定
grep は POSIX互換の [[:space:]] を使用
wc -l の余白はmacOS対策で tr -d ' ' を挿入

まとめ

機能	説明
`/handoff`	引き継ぎプロンプト生成 → update → `claude` で新セッション起動
SessionStartフック	新セッションに引き継ぎコンテキストを自動注入
引き継ぎファイル	`~/.claude/handoffs/` にタイムスタンプ付きで蓄積

長時間のコーディングセッションで「そろそろコンテキストが怪しいな」と思ったら、/handoff 一発で綺麗に引き継げます。

v1.2.0 アップデート（2026-04-01）

v1.2.0 で 新セッションの起動オプション選択機能 を追加しました。/handoff 実行時に --model、--effort、--dangerously-skip-permissions を選択でき、案内される起動コマンドに自動で含まれます。

v1.1.0 アップデート（2026-03-31）

v1.1.0 で Stopフック（セッション終了時の自動ブロック）を削除しました。引き継ぎは /handoff を明示的に実行したときだけ行われます。

既にインストール済みの方は以下でアップデートできます：

claude plugin update claude-handoff@amu815