write-handoff

次のエージェントに作業を引き継ぐ

未完了の作業が残ったまま作業が止まり、その理由を知っているセッションがまもなく消えようとしています。次のエージェントは何も知らない状態で始めます。会話も推論もなく、あるのはツリーと、あなたが残したものだけです。 docs/<feature>/HANDOFF.md（別の場所を使っていない限り、プロジェクトの計画フォルダー内）が、あなたが残すものです。

次のエージェントの最初の1時間が、発掘作業ではなく生産的な時間になるか――つまり、作業の場所と最初にすべきこと、これから見つけることのうち、すでに把握されているものが何かを理解できるかどうかで評価されます。

これは write-acceptance ではありません。 そちらは、完了した作業を人に引き渡してテストと受け入れを行うものです。こちらは、未完了の作業をエージェントに引き渡すものです。読み手も問いも異なります。フェーズを完了したうえで未完了の作業が残った実行では、両方を作成します。

作成するタイミング

• 依頼された範囲が完了していない場合：フェーズを延期した、判断待ちでブロックされている、またはその日の作業を中断した。
• 作業中にコンテキストが尽きそうな場合。
• 別のブランチ、チェックアウト、マシン、または他の人のセッションに作業を移す場合。

範囲が完了している場合は作成しないでください。 完了した作業はEXECUTION.mdに記述し、close-planまたはclose-roadmapで終了します。引き継ぎ文書を作ると、同じ作業の実行内容を4回目に要約することになり、内容が古くなっても信じられてしまいます。

記載する内容

まずツリーの状態から始めてください。最初に問題になるのはそこだからです。 ブランチ名とチェックアウト（またはワークツリー）のパス、作業ツリーがクリーンかどうか、何がプッシュ済みで何が未プッシュかを記載してください。originに作業があると思い込んだエージェントは、存在しないブランチで作業してしまいます。次に最初のアクションを記載します。メインの統合ブランチ（例：mainやdev）が進んでいる場合は、「ツリーに触れる前に<main>をマージする」と明記し、ページのほかの内容より先に記載してください。

• 再開する場所を、最初に、見落としようのない形で示す。 次に行うことを1文で記載します。ページのほかの情報はすべて、そのための背景情報です。
• 作成したものは、詳述ではなく参照先として示す。 正式な文書（最終計画、判断記録、生成されたリファレンス）を挙げ、要約は仕様ではないとはっきり記載します。何かが変更された瞬間に、文章での要約は計画の誤ったコピーになります。
• コミット一覧は、何かの説明になる場合に限って記載する。 EXECUTION.mdには、ハッシュ付きで取り込まれた内容がすでに記載されています。表を繰り返すのではなく、リンクしてください。ここに記載するのは、形が意外なコミットです。判断記録の番号を振り直したもの、マージのみのもの、まだこのブランチにしかないものなどです。
• 落とし穴。 繰り返し発生するコンフリクトと前回それを解決したルール、ブランチのベースで失敗し自分の変更が原因ではないテスト、その兆候のある不安定なテスト、壊れているように見えて実際は壊れていないものなどです。ツリーからは復元できないため、ここは1行あたりの価値が最も高い部分です。落とし穴を一度記載すれば、次のエージェントはその分のコストを払わずに済みます。
• ユーザーが不在の間に行った判断。質問ログ（プロジェクトで未解決の質問を記録している場所。決まりがなければ、計画の横に質問セクションまたはファイルを作成）への参照先も記載します。次のエージェントが黙って判断をやり直さないようにし、どの項目が未解決のままかも分かるようにしてください。
• 意図的に未対応の内容。次のエージェントが意図的な未対応箇所を「修正」するのではなく、作業を拡張できるようにします。

冒頭に日付とセッションの作業範囲を記載してください――「マイルストーン1を構築した作業の終了時に記載」のようにします。引き継ぎ文書の内容が正しいのは、その時点においてです。日付がなければ、正しくなくなった後も長く信じられてしまいます。

書き方

• 読者は、プロジェクトのエージェント向けオリエンテーション（AGENTS.md、CONTRIBUTING.md など）だけを読み、ほかは何も読んでいないものとします。 そのことを明記し、該当ドキュメントを示してください。リポジトリ全体に適用されるルールを繰り返す必要はありません。作業対象のコードに関するエリア別ドキュメントは示してください。
• パス、ブランチ、コマンドを具体的に記載してください。 「ワークツリー」は場所を特定できません。ブランチ spell-check/p4 の ../myapp-wt/spell-check なら特定できます。
• 再発見に時間がかかる事実を優先してください。 git log や grep を一度実行すればわかることに、段落を割く必要はありません。解明に1時間かかったことは、必ず記載してください。
• 作業を始める前に最後まで読める長さにしてください。誰も読み終えない引き継ぎは、何も引き継いでいないのと同じです。

保存場所

• docs/<feature>/HANDOFF.md に記載し、作業セッションの最後のコミットとしてコミットしてください。そうすれば、次のエージェントがクローンするツリーの内容が反映されます。
• 2つ目を追記するのではなく、既存のファイルを更新してください。古い引き継ぎが最新の引き継ぎと並んでいる状態は、どちらもない状態より悪いです。
• 引き継ぎを読むのは resume-handoff です。記載を信頼する前に、ツリー上の内容と照らし合わせて各項目を確認します。そのため、コミットハッシュ、ahead/behind の件数、チェックアウトパス、親ブランチで失敗するテスト名など、検証可能な事実は検証可能な形式で記載してください。次のセッションには伝わらない可能性のある個人的な記憶やメモに頼らないでください。ユーザーが方針に同意すると、このページは削除されます。引き継ぎは消費され、維持管理されるものではありません。引き継ぎを受け取ったセッションは、自身のツリーから次の引き継ぎを書きます。
• 機能のドキュメントが完了したら、close-plan または close-roadmap で引き継ぎを終了します。