HANDOFF.mdを使いこなそう AIエージェントの作業を別セッションへ引き継ぐ

HANDOFF.mdを、AIエージェント間で目的、変更ファイル、判断、実行済みコマンド、残タスクを渡すための中継ファイルとして整理します。

この記事の要点

AIエージェントの作業は、ひとつの会話、ひとつのセッション、ひとつのツールの中だけでは閉じない。Claude CodeからCodex CLIへ、Codex AppからCLIへ、ChatGPTで練った企画からGitHubのIssueへ。作業は途中で、別の手へと渡っていく。

そのつど、前の会話で下した判断、やり残したタスク、すでに実行したコマンド、試してダメだった手は、こぼれ落ちやすい。Gitの差分を見ても、なぜその差分の形にしたのかまでは書かれていない。

HANDOFF.mdは、その消えやすい途中の状態を、次のエージェントが読める形にして置いておくためのファイルだ。

HANDOFF.mdに残すのは、長い会話ログではない。いまの目的、作業中のブランチ、変更したファイル、まだ手をつけていないファイル、決まった方針、まだ決めていないこと、実行したコマンド、テスト結果、うまくいかなかった試み、そして次にやること。

これに加えて、次のエージェントへ渡す短い指示文があると効く。まず何を読めばいいか、どこから手をつければいいか、どの判断はもう蒸し返さなくていいか。これが書いてあると、再開の立ち上がりが速い。

残すのは再開に要る情報だけにする。引き継いだ側が、最初の10分を読み解きだけで失わない粒度がちょうどいい。

HANDOFF.mdは便利だが、なんでも置く場所ではない。会話ログの全文、APIキー、OAuthトークン、個人情報、顧客情報、不要な感想、モデルへの愚痴は入れない。

秘密の情報は、「引き継ぎに必要そうだ」と感じる場面ほど紛れ込みやすい。認証が要った、接続に失敗した、特定のメールを参照した。こうした事実は、鍵や値そのものを書かずに、起きたことだけを残す。

HANDOFF.mdは作業の見取り図であって、鍵束をしまう金庫ではない。

HANDOFF.mdは、作業のあいだじゅう書き足して膨らませるものではない。セッションを閉じる前、別のツールへ移る前、PRを出す前、レビューの前、長い調査から実装へ切り替える前。こうした切れ目で更新する。

こまめに書きすぎると、ただのノイズになる。書かなければ、次の誰かが再開できない。区切りのところでだけ、いまの現在地を短く固定しておくのがいい。

とりわけ、うまくいかなかった試みには価値がある。なぜその道をあきらめたのかが残っていないと、次のエージェントは同じ落とし穴をもう一度掘ることになる。

CLAUDE.mdやAGENTS.md、スキルが渡すのは、作業の進め方のルールだ。HANDOFF.mdが渡すのは、今回の作業がいまどうなっているかという状態。この二つは役割が違う。

プロジェクトのルールに「テストを実行する」と書いてあっても、今回どのテストを流し、どこで失敗し、どこまで直したのかまでは残らない。Issueに目的が書かれていても、いまどのブランチで、どのファイルが手つかずなのかは分からない。

ルール、Issue、差分、そしてHANDOFF.md。これがそろって初めて、エージェントの作業は別のセッションへ渡せるようになる。

HANDOFF.mdは万能ではない。最後に頼るべきは、Gitの差分、Issue、PR、テスト結果のほうだ。HANDOFF.mdは、そこへたどり着くまでの中継点でしかない。

だから、PRを出す前には、HANDOFF.mdの中身をPR本文や検証結果へ移しておく。作業が終わったら、古い引き継ぎメモを最新の状態のように残し続けない。

エージェントの作業を、会話の中に閉じ込めない。かといって、途中メモを最終的な答えにもしない。HANDOFF.mdは、その二つのあいだをつなぐための、実務的なファイルだ。

閉域AI、社内データ活用、拠点間ネットワーク、音声・録音データ、クラウド接続など、AIを業務環境に組み込むためのインフラ構成についてご相談ください。

既存ネットワーク、PBX、データセンター、業務システムとの接続を前提に、実装しやすい構成を整理します。

要件を相談する