記事一覧に戻る
handoverスキルをOSS公開 - AIエージェントの文脈引き継ぎを標準化する

handoverスキルをOSS公開 - AIエージェントの文脈引き継ぎを標準化する

ZenChAIne·
AI AgentAgent SkillsDeveloper Tools

はじめに

AIエージェントによる開発で本当に難しいのは、コードを書かせることよりも、作業の途中状態を安全に次へ渡すことです。長い調査、未完了の実装、検証済みの判断、触ってはいけないファイルを次のセッションが知らないまま再開すると、同じ探索のやり直しや意図しない巻き戻しが起きます。

私たちは OSS として公開している agent-skills に、新しく handover スキルを追加しました。GitHub PR #58 で追加されたこのスキルは、ローカルの handover.md と .handover/ を使って、AIエージェントのセッション引き継ぎを構造化します。

この記事のポイント

  • AIエージェントの生産性は、単発の回答品質だけでなくセッション継続性に左右される
  • handoverスキルは write / boot / install / status の4モードで引き継ぎを扱う
  • デフォルトでは private なローカルファイルとして保存し、Git状態と照合してから再開する
  • AGENTS.md / CLAUDE.md への起動ガイダンスと、Claude Code / Codex 両対応の SessionStart hook（セッション開始時に実行されるフック）を組み合わせる

なぜAIエージェントにコンテキストの引き継ぎが必要なのか？

AIエージェントの作業は、1回の会話で完結しないことが増えています。実装、レビュー、検証、記事作成、PR対応のような作業は、途中でセッションが切れたり、別のエージェントに移したり、翌日に再開したりする前提で設計する必要があります。

引き継ぎがない場合、次のセッションは次のような問題を抱えます。

  • どのブランチ、どのHEAD、どの作業ツリー状態を前提にすべきかわからない
  • 完了済みの調査と未完了の作業を区別できない
  • ユーザーが明示した制約や「やらないこと」を見落とす
  • 直前に失敗したコマンドや既知の問題を再実行してしまう
  • 前のセッションのメモを信じすぎて、現在のリポジトリ状態とのズレに気づけない

つまり問題は「記憶がない」だけではありません。記憶を現在のリポジトリ状態に照合できないことが問題です。handoverスキルはこの点を中心に設計しています。

handoverスキルは何をするのか？

handoverスキルは、AIエージェントの作業終了時と開始時に使うセッション継続プロトコルです。現行実装では、skills/handover/SKILL.md、英日テンプレート、起動スニペット、Claude Code / Codex 両対応の SessionStart hook（セッション開始時に実行されるフック）用Node.jsスクリプトが含まれています。

基本コマンドは4つです。

text
handover write
handover boot
handover install
handover status

それぞれの役割は次の通りです。

モード役割
write現在のセッションが次のセッション向けに引き継ぎを書く
boot新しいセッションが既存の引き継ぎを読み、現状と照合して開始する
installリポジトリに起動時の引き継ぎ確認ルールを追加する
statushandoverファイル、gitignore、起動ガイダンス、hookの状態を点検する

インストールは他の agent-skills と同じです。

bash
npx skills add anyoneanderson/agent-skills --skill handover -g -y

どのようなアーキテクチャで実装したのか？

handoverスキルの設計は、単純なメモ保存ではなく「検証可能なセッション再開」を中心にしています。構成は大きく4層です。

text
ユーザーまたはエージェントの指示
    |
    v
handoverスキルの各モード
    |-- write   -> handover.md + .handover/current.md + state.json を作成
    |-- boot    -> handoverを読み、ブランチ / HEAD / ファイルを照合
    |-- install -> AGENTS.md / CLAUDE.md に起動ガイダンスを追加
    |-- status  -> ローカル設定の状態を確認
    |
    v
Claude Code / Codex SessionStart hook
    |
    v
短い起動時コンテキスト: 目的、次の作業、停止条件

1. ローカル private をデフォルトにする

handoverはデフォルトで private（ローカル非公開）です。handover.md と .handover/ は作業メモであり、通常はGitにコミットしません。

そのため write や install の前に、.gitignore に次のガードを入れます。

gitignore
# Agent session handovers
handover.md
.handover/

すでに tracked な handover ファイルがある場合は警告しますが、自動で git rm --cached は実行しません。これは、AIエージェントがユーザーの意図しないGit操作をしないための境界線です。

2. handover本文と状態メタデータを分離する

write は、人間とAIが読める handover.md に加えて、機械的に検証しやすい .handover/state.json を作ります。

handover本文には、少なくとも次の情報を含めます。英語テンプレートでは項目名を固定していますが、日本語で読むと次の意味です。

  • updated timestamp: 引き継ぎを更新した日時
  • working directory: 作業していたディレクトリ
  • branch: 作業ブランチ
  • HEAD: 作業時点のGitコミット
  • privacy mode: private（ローカル非公開）/ shared（チーム共有）のどちらで扱うか
  • goal: このセッションで達成したかった目的
  • current state: 現在の作業状態
  • completed work: 完了した作業
  • pending work: 未完了の作業
  • important files: 次のセッションが確認すべき重要ファイル
  • commands run: 実行済みコマンドと結果
  • known issues: 既知の問題や注意点
  • decisions: 途中で決めた方針
  • next action: 次に取るべき作業
  • stop conditions: 作業を止めて確認すべき条件

ここで重要なのは、次のアクションを無理に作らないことです。会話から安全な Next Action（次に取るべき作業）が判断できない場合、handoverには不確実性を明記します。AIにとって「わからない」と書ける設計は、事故を減らす機能です。

3. boot時に現在のリポジトリ状態と照合する

boot は handover を読むだけでは終わりません。現在のブランチ、HEAD、作業ツリー、参照された重要ファイルの存在を確認し、handoverが古くなっていないかを報告します。

この設計により、次のセッションは次の4点を確認してから動き出せます。

  • inherited goal: 前回から引き継いだ目的
  • verified current state: Git状態と照合した現在の状態
  • stale or conflicting notes: 古くなっている、または矛盾している可能性のあるメモ
  • intended next action: 続行する場合に実行する次の作業

AIエージェントの引き継ぎで危険なのは、古いメモを現在の真実として扱うことです。handoverスキルは、handoverを「参考情報」として読みつつ、リポジトリの現在状態を優先します。

4. エージェント共通の起動ガイダンスとhookアダプターを分ける

install は AGENTS.md / CLAUDE.md に起動時の確認スニペットを挿入します。これはCodexやClaude Codeなど、リポジトリの指示ファイルを読むエージェントで使える共通の土台です。

一方で、SessionStart hook（セッション開始時に実行されるフック）を使える環境では、補助スクリプトも利用できます。現行のhookインストーラーは、Claude Code 向けに .claude/settings.json、Codex 向けに .codex/hooks.json を設定します。引数なしでは両方を設定し、--claude / --codex を付けると片方だけを選べます。

bash
node skills/handover/scripts/handover-session-start.js

このhookは、handover全文を丸ごと注入しません。goal（目的）、next action（次の作業）、stop conditions（停止条件）だけを短い起動文脈として出します。長いメモを無条件にコンテキストへ流し込むのではなく、開始時に必要な最小情報だけを渡す設計です。

なぜ全文を自動注入しないのか？

handover全文を毎回自動注入すると、一見便利ですが、コンテキスト汚染のリスクがあります。古い制約、解決済みの問題、今のブランチと合わないメモまでセッション開始時に強く効いてしまうからです。

そのため handoverスキルでは、hookが出す情報を意図的に短くしています。詳細が必要な場合は handover boot で人間に見える形で確認し、現在状態と照合してから続行します。

handoverは「前回のメモを絶対視する仕組み」ではありません。前回の文脈を読み、現在のGit状態と照合し、安全な次アクションだけを採用するための仕組みです。

よくある質問

Q. handoverはメモリ機能と何が違いますか？

A. メモリは長期的な知識や好みを保存する用途に向いています。handoverは特定リポジトリの特定作業を、ブランチやHEADなどの現在状態と照合しながら再開するための短期的な作業メモです。

Q. handover.mdをGitにコミットしてもよいですか？

A. デフォルトでは推奨しません。handoverには未公開の方針、作業途中の判断、ローカルパスなどが入りやすいため private（ローカル非公開）が基本です。チームで共有したい場合だけ --shared を明示します。

Q. 別のAIエージェントでも使えますか？

A. はい。AGENTS.md / CLAUDE.md の起動ガイダンスを共通の土台にしているため、SKILL.md 対応エージェントで利用できます。さらに SessionStart hook は Claude Code と Codex の両方に設定できる追加の自動起動機能です。

Q. cmuxのforkやdelegateとはどう違いますか？

A. cmuxのforkやdelegateは、会話や作業環境を分岐・委任するための操作です。handoverは、セッションが切れた後や別環境で再開するときに、作業状態をローカルファイルとして残して検証するためのプロトコルです。

まとめ

AIエージェント開発では、コンテキストをどれだけ長く持てるかよりも、必要な文脈をどれだけ安全に引き継げるかが重要になります。handoverスキルは、そのための小さなプロトコルです。

今回のPRで、agent-skillsは仕様生成やレビュー支援だけでなく、セッション継続性の問題にも踏み込みました。ZenChAIneでは、AIエージェントを単発の補助ツールではなく、長い開発ワークフローの参加者として扱うための基盤を引き続き整えていきます。

参考ソース

🇺🇸 Read in English