コーディングエージェントがタスクを終えるたび、同じ空白が生まれる。手元に届くのはdiffと「完了しました」という気楽な報告だけで、何が変わったのか、何が飛ばされたのか、何がテストされたのか、エージェントがまだ確信を持てていないのはどこなのかは分からない。だからあなたはdiffを読み直し、テストを自分で再実行し、エージェントが作業を返す時点で答えられたはずの質問を、また投げかけることになる。エージェントを2つ動かせば、そのコストは倍になる。問題は作業そのものではない。問題はハンドオフ、つまり依頼した人とそれを実行したエージェントの間で何が行き交い、何が返ってくるかにある。
コーディングエージェントのハンドオフテンプレートとは、タスクが持ち手を変えるときに何を運ぶかを固定した構造だ。人からエージェントへ割り当てる時と、エージェントから人へレビューのために戻す時。毎回の受け渡しの形をその場で improvisation するのではなく、いつも同じフィールドを埋める。エージェントは始める前に「完了」の意味を知り、あなたはエージェントが止まったときに同じ要約、根拠、未解決の問いを受け取る。
この記事では、実務で通用する2つのテンプレートを、ワークフローとしてSharklyを使いながら順に見ていく。Sharklyはコーディングエージェントの上位に位置するレイヤーで、コンテキスト、進捗、ブロッカー、結果、人間によるレビューを、リクエストからリリースまで可視化し続ける。あなたはすでにコーディングエージェントを持っている。Sharklyはそれをチームに変え、ハンドオフテンプレートが、各受け渡しを推測ではなく記録にする。
コーディングエージェントのハンドオフテンプレートとは
ハンドオフテンプレートは、チェックリストを構造化したものだ。素のdiffが決して答えない3つの問いに答える。何が依頼され、何が起き、今は誰の番か。この3つが一緒に運ばれれば、次の担当者は3つを再構築するのではなく、1つの記録を読めばいい。
テンプレート化する価値があるハンドオフは2つある。逆方向に走り、逆のものを運ぶからだ。
- 割り当てハンドオフ（人またはリードエージェントからエージェントへ）：ゴール、境界、完了の定義を、作業が始まる前に手渡す。
- レビューハンドオフ（エージェントから人へ戻す）：変更、機能する証拠、人間がまだ判断すべき部分を、作業が止まったときに手渡す。
両方をテンプレート化することこそが要点だ。多くのチームは雑なチケットを書くが、戻り側は何もテンプレート化しない。だからレビューは毎回、尋問から始まる。時間を節約できるのは、この戻り道を整えることにある。
テンプレートが体現する運用モデル
テンプレートは、その下にある運用モデル以上のものにはならない。4つの動詞が、各継ぎ目の所有権を決める。誰が割り当て、誰が実行し、誰がレビューし、誰が承認するか。エージェントは調査し、実行し、テストし、報告する。人は方向を定め、権限を与え、結果を承認する。自動化は、チームの判断が必要なところで止まる。
この契約があるからこそ、2つのテンプレートは異なるフィールドを持つ。エージェントは承認がどんな形かを推測すべきではないので、割り当てテンプレートは依頼者にそれを書き留めるよう強制する。人はグリーンが安全を意味するかどうかを推測すべきではないので、レビューテンプレートはエージェントに作業内容を示すよう強制する。以下がコピー&ペーストできる割り当てハンドオフだ。
## Assignment handoff
Task ID: SH-###
Goal: one sentence, in plain language
In scope: the specific files, endpoints, or behaviors to touch
Out of scope: what to leave alone (auth, billing, public contracts)
Definition of done:
- [ ] observable acceptance criterion 1
- [ ] observable acceptance criterion 2
Constraints: frameworks, patterns, or limits to respect
Assignee: the exact Agent that owns this
重い仕事をするのは「out of scope」と「definition of done」の行だ。これらがなければ、エージェントはあなたが意図した成果物ではなく、diffが通ることを最適化してしまう。これらがあれば、コードが1行も存在しないうちに受け入れチェックが書かれている。
レビューハンドオフ：何が返ってくるか
戻りのテンプレートこそ、多くのワークフローが飛ばすものであり、午後を救ってくれるものだ。エージェントが終えたとき、「準備完了」とリンクを送るだけではいけない。埋めた構造を返すべきだ。
## Review handoff
Task ID: SH-###
Summary: what changed, in 2-3 sentences
Acceptance: each definition-of-done item, checked with how it was verified
Tests: typecheck / unit / build results, pasted or linked
Diff: the PR or worktree branch
Known limits: what this does NOT cover, and any risky assumption
Open questions: decisions left for a human
「known limits」と「open questions」のフィールドが、本物のハンドオフと、緑のチェックマークの壁を分ける。正直な限界（「Redisカウンターは単一リージョンを前提としている」）は、盲目的なマージを、情報に基づいたマージに変える。これはタスクレベルの証拠でAI生成コードをレビューするという考え方と同じ原則だ。レビュアーは、diffと願望ではなく、主張とその証明を読む。
はっきり述べておくべき境界がある。レビューハンドオフはマージの依頼ではない。レビューの依頼だ。エージェントは提示し、人が決定する。この2つの行為を分けておくことが、未レビューの作業が出荷されるのを防ぐ。
ステータスとレビューゲート：テンプレートが住む場所
スクロールバックのバッファに住むテンプレートは、誰も読まないテンプレートだ。ハンドオフは何か共有されたものに紐づいている必要があり、ステータスはその自然な住処だ。すべてのTaskはひとつのレーンを通り、各ステータス変更はテンプレートが添付されたハンドオフになる。
| ステータス | オーナー | 添付されるテンプレート |
|---|---|---|
| Todo | 人またはリードエージェント | 割り当てハンドオフ |
| In progress | エージェント | （分離されたworktreeで作業中） |
| Ready for review | エージェント | レビューハンドオフ |
| Done | 人 | 承認ノート + マージ判断 |
これを読みやすくするルールはこうだ。エージェントはTaskをReady for reviewへ動かし、人はDoneへ動かす。エージェントは自分の作業を決してDoneにはせず、人は何が起きたかを再構築する必要がない。レビューハンドオフがすでにTask上にあるからだ。Sharklyでは、実行、ブロッカー、結果、フォローアップの議論がTaskのタイムラインに戻る。だから10のエージェントが動いているとき、あなたは10のターミナルではなくボードを読む。これがエージェントが完了した作業を追跡することと、コミットログが後で説明してくれるだろうと期待することの違いだ。自律的な作業をどこで止めるべきかはそれ自体が設計上の選択であり、承認ゲートをどこに置くかで扱っている。
実例：チケットからマージされたPRまで
実際にありそうなTask、SH-441「レポートページにCSVエクスポートを追加する」を例に取ろう。コードではなく、テンプレートが埋まっていく様子を見てほしい。
人がSH-441を開き、リードエージェントが割り当てハンドオフを完成させる。ゴール（「ユーザーが現在のレポートをCSVでダウンロードできるようにする」）、in scope（レポートコントローラーと新しいエクスポートモジュール1つ）、out of scope（認証、既存のレポートクエリ）、そして検証可能な3項目からなる完了の定義（ダウンロードボタン、カンマと引用符の正しいエスケープ、10k行のフィクスチャを使ったテスト）。Assigneeはバックエンドエージェントだ。テンプレートがあいまいさを許さないので、何もあいまいではない。
バックエンドエージェントはTaskを引き受け、他の作業と衝突しないよう分離されたworktreeで作業し、完了の定義の項目を自分自身のチェックリストとして実行する。typecheck、ユニットテスト、ビルドがグリーンになると、SH-441をReady for reviewへ動かし、戻りのテンプレートを埋める。短い要約、検証方法とともにチェックされた各承認項目、diff、そして1つの既知の限界（「100k行を超えるエクスポートはメモリにバッファリングされる。ストリーミングは未実装」）。
ここでハンドオフの方向が反転する。人はスクロールバックではなく、1つの記録を読む。エスケープのテストを確認し、メモリの限界を実際のレポートサイズと照らし合わせて検討し、当面は承認し、SH-441をDoneへ動かす。これがマージをトリガーする。チケットからマージされたPRまで、両方の継ぎ目に埋められたテンプレートがあり、それぞれのオーナーが誰だったかの記録がある。これは要件からコードまでの道筋を追跡可能にしたものであり、エンドツーエンドだ。
テンプレートが過剰になるとき
テンプレートにはコストがかかる。だから正直な判断ペアを示そう。1つのエージェントが1パスで終える、小さく明確な作業で、ゴールと承認がTaskのタイトルから明らかな場合は、完全なテンプレートは飛ばそう。重要な継ぎ目を越える作業、つまり1つのゴールに複数のエージェントが関わる場合、パブリックコントラクトの変更、認証・請求・簡単には取り消せないデータに触れるものが出た瞬間に、テンプレートに手を伸ばそう。テンプレートはコンテキストの抜け落ちに対する保険であり、損失が痛むところで保険を買う。
これらすべては、共有ボードと規律があれば手作業でも運用できる。それはエージェント、タスク、リポジトリの数が増え、規律が真っ先に失われるまでは機能する。すでに複数のエージェントを動かしているなら、Sharklyがタスクと結果を管理するひとつの場所を提供する。割り当てとレビューのハンドオフを運ぶ共有Task、TaskごとのAssignee、分離されたworktree、エージェントがReady for reviewへ到達し人がDoneを決めるステータスレーンだ。すでに使っているコーディングエージェントはそのまま使える。それらの間の継ぎ目が作業そのものよりコストがかかるようになったら、Sharklyをダウンロードしてほしい。
FAQ
コーディングエージェントのハンドオフテンプレートとは何ですか？ タスクが持ち手を変えるときに何を運ぶかを固定した構造です。2つあります。割り当てハンドオフ（人からエージェントへのゴール、スコープ、完了の定義）と、レビューハンドオフ（エージェントから人へ戻す要約、根拠、既知の限界）です。毎回同じフィールドを埋めることが、担当者間でコンテキストが蒸発するのを防ぎます。
なぜチケットだけでなく、戻り道もテンプレート化するのですか？ 多くのチームはチケットを書くものの、戻り側は何もテンプレート化しません。だからレビューは毎回、尋問から始まります。要約、チェック済みの承認項目、既知の限界を含むレビューハンドオフこそ、テンプレートが最も時間を節約する場所です。詳しくはhuman-in-the-loopのコーディングエージェントをご覧ください。
エージェントは自分の作業を完了とマークすべきですか？ いいえ。エージェントには戻りのテンプレートを埋めてTaskをReady for reviewへ動かさせ、Doneへの移動とマージ判断は人に任せましょう。「提示された」と「承認された」を分けることが、未レビューのコードが出荷されるのを防ぎます。
テンプレートはどこに置くべきですか？ 1つのエージェントしか見ていないターミナルではなく、ステータス変更に紐づけた共有Taskの上です。ハンドオフがテンプレートの添付されたステータスであれば、次の担当者は自分を待っているものが何かを正確に把握できます。これは多くのエージェントが同時に終了するときにレビューがボトルネックになるのを防ぐことにもつながります。
これにツールは必要ですか、それとも手動でできますか？ 共有ボードと規律があれば手動でも運用できます。専用のレイヤーは、複数のリポジトリにわたって複数のエージェントを調整し、手動での追跡が作業そのものになったときに元が取れます。汎用的なエージェント作業のためのAIタスクマネージャーと比較してみてください。
