Handoff・Scratchpad・Token Burning：長いAIタスクでコンテキストを管理する方法
約13分developer-tools
#ハンドオフ#スクラッチパッド#トークンバーニング#デタッチドHEAD#アップストリーム#.gitignore#AIコーディングツール#用語集
※編集方針：以下の業務状況および人物は、用語の理解を助けるための仮想シナリオです。実際の著者の経験や特定の企業での出来事を再現したものではありません。
3週間の休暇を前に、進行中のAI開発タスクを他のチームメンバーに引き継ぐ必要がある状況を想定してみましょう。
調べてみると、このような状況にぴったりの表現がありました。
席を外す前に、次の担当者へ状況を正確に引き継ぐこと：ハンドオフ
markdown
1# 핸드오프 문서2- 진행 상황: 결제 모듈 80% 완료3- 남은 작업: 환불 API 연동4- 막힌 부분: 외부사 문서 응답 대기 중
これまでに何を行い、何が残っており、どこで立ち往生しているのかを、次の担当者が最初から迷わないように整理して引き渡す作業です。リレーでバトンを渡す際、ただ投げるのではなく、相手がしっかりと受け取ったことを確認してから手を離すのに似ています。
ドキュメントを整理していると、これまでにエージェントが作業中に残した一時的なメモファイルが目に留まりました。もう一度開いてみると、思った以上に充実した内容が書かれていました。
正式なドキュメントではないものの、残り続けているメモファイル：スクラッチパッド
text
1scratchpad.md2- 외부사 API 응답 형식이 문서와 다름 (실제로는 배열)3- 테스트 계정 비밀번호는 슬랙 #payment-dev 참고
正式なコミットには含まれないこのファイルを読み返してみると、実は最も実践的な情報がすべてここに書かれていました。公式文書としてまとめるには少しハードルの高い雑多なメモを、後で参照するために気軽に書き留めておく一時的なノートです。形式張ってはいませんが、すぐに役立つ情報だけが集まっている、会議中に手のひらに書き留めるメモのようなファイルでした。このファイルへのリンクも、ハンドオフ用のドキュメントに残しておきました。
最後に、大きなタスクを一つエージェントに任せようとしたところ、チームのチャンネルで同僚が事前に注意を促してくれました。
休暇前に大きなタスクをまとめて指示してはいけない理由：トークンバーニング
同僚は「それを今丸ごと頼んでしまうと、休暇中に（トークンの）制限をすべて使い切ってしまうかもしれないよ」と教えてくれました。
text
1이번 달 사용량: ▓▓▓▓▓▓▓░░░ 72%
会話が長くなり作業が複雑になるほど、それだけ処理すべき量も増え、設定された制限（トークン）をそれだけ早く消費することになります。同じ目的地を目指すにしても、運転の仕方によってガソリンが多く消費されるのと同じ理屈でした。大きなタスクは分割して依頼することにし、スケジュールを立て直しました。
スケジュールを立て直している最中、以前テスト用に作成しておいたブランチを開いたところ、見慣れない警告が表示されました。
ブランチ名が消え、コミットハッシュ（番号）だけが表示されるとき：デタッチドHEAD
text
1You are in 'detached HEAD' state at a1b2c3d
公式ドキュメントを調べてみると、ブランチ名ではなく、特定のコミットを直接チェックアウトしたときにこのような状態になると書かれていました。
どのブランチにも属さず、特定のコミット地点に直接留まっている状態のため、ここでさらにコミットを重ねても、後でブランチを作成しておかないとその記録が浮いた状態になり、見失われがちになります。名前の書かれた船ではなく、一時的にブイに繋がれたような状態だったため、急いで新しいブランチを作成して移動させました。
このブランチを整理しながらリモートリポジトリの設定を再確認していたところ、以前の同僚が設定していたリモート名が一つ目に留まりました。
オリジナルのリポジトリを継続して参照する必要があるとき：アップストリーム
bash
1$ git remote -v2origin (내 포크)3upstream (원본 저장소)
同僚が以前このオープンソースライブラリをフォークして使用していた際に設定したリモートリポジトリの一覧を見て、気になって調べてみました。
自分が複製して使っているリポジトリではなく、その大元となるオリジナルのリポジトリを指す名前でした。原作者が新しいバージョンをリリースするたびに、このパスを通じて最新の内容を自分の環境に取り込むことができます。川の上流から流れてくる水流を意味する言葉（Upstream）が、そのままリポジトリ名に使われているのでした。
最後にコミット前のステータスを確認したところ、
git statusに表示され続けていたログファイルが気になりました。コミットしたくないファイルが追跡されてしまうとき：.gitignore
bash
1$ git status2Untracked files:3 debug.log4 node_modules/
毎回これらのファイルを無視して進めていましたが、今回は完全に表示されないようにする方法を調べてみました。ツールが教えてくれた通りに一つのファイルにリストを記述しておくと、それ以降は二度と表示されなくなりました。
コミットの対象から完全に除外したいファイルやフォルダーのリストをあらかじめ記述しておくファイルです。家事代行サービスに「この部屋には手をつけないでください」と事前に張り紙をしておくようなものです。これで引き継ぎドキュメントの整理終わりました。
退勤の直前になって、ようやく引き継ぎドキュメントを閉じました。3週間後にこのドキュメントを読むのがチームメンバーではなく自分自身かもしれないという気がして、最後の段落は他人に宛てたものではなく、戻ってくる自分自身に宛てたメッセージのように書き直しました。
よくある質問
ハンドオフ用のドキュメントはどの程度詳しく書くべきですか？
受け取る人が背景の補足説明なしで、すぐに作業を引き継げるレベルが基準となります。特に行き詰まっている箇所とその理由は、同じ試行錯誤を繰り返さないように詳しく記述する必要があります。
デタッチドHEAD（detached HEAD）状態で誤ってコミットした場合、すべて消えてしまいますか？
すぐに消えてしまうわけではなく、しばらくはシステム内に残っているため、復旧する方法がある場合がほとんどです。ただし、時間が経つと整理されて消えてしまう可能性があるため、気づいた時点で早急にブランチを作成して移動させるのが安全です。
すでにコミットされたファイルを後から.gitignoreに追加した場合、すぐに消えますか？
いいえ、すでに追跡対象となっているファイルは、別途追跡を解除するコマンドを実行する必要があります。.gitignoreは、今後新しく追加されるファイルに対して適用されます。
前回の記事 ・ 第10回：大きなPRを送る前に、散らかったブランチを整理した一日
AIコーディングツール用語集シリーズの第11回です。次回予告 ・ 第12回：複数のリポジトリを行き来しながら統合リリースを準備した日（オーケストレーター vs ワーカー ・ デリゲート ・ MCP ・ フォーク ・ リリースタグ ・ サブモジュール）
参考・根拠
関連記事
サブエージェント・フック・スラッシュコマンド：AIコーディングツールでよく使われる拡張概念
AIコーディングツールの使用中に出会う「サブエージェント」「フック」「スラッシュコマンド」を、架空の業務シナリオを交えて分かりやすく解説します。
パーミッションプロンプト・Sandbox・Checkpoint：AIエージェントの実行境界を理解する
AIコーディングツールを使う中で直面するパーミッションプロンプト、サンドボックス、チェックポイントなど5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。
Kill Switch・Backoff・Runtime：実行を停止し復旧するための基本機能
AIコーディングツールを使っていると遭遇する、キルスイッチ、バックオフ、リポジトリなどの5つの用語を、仮想の業務シナリオを通じてわかりやすく解説します。