handoffkit

handoffkit

この会話で得たすべての情報を、今回のコンテキストを持たない新しいエージェントが読んで作業を続けられる、単一の引き継ぎドキュメントにまとめます。目的はアーカイブではなく、情報の受け渡しです。このセッションでのみ得られた状態と考え方を記録し、既存の成果物（仕様書、PR、コミット、差分、Issue）を複製するのではなく、参照先を示します。デフォルトでは docs/handoffs/ の下に Markdown ファイルとして保存します。ユーザーがインライン出力またはターミナル出力を明示的に求めた場合、あるいは書き込み可能なファイルシステムがない場合に限り、コピーして貼り付けられるブロックとして出力します。

この指示が有効になる場合

ユーザーがコンテキストの境界を越えた継続を求めた場合に有効になります。「引き継ぎを書いて」「これを引き継いで」「次のセッション向けに要約して」「別のエージェントに渡して」「コンテキストが尽きる前に整理して」などが該当します。ユーザーが引数（例：「移行の完了に向けた引き継ぎ」）を指定した場合は、それを次のセッションの焦点として扱い、ドキュメント全体の内容をそれに合わせます。その目標に必要な情報を先に示し、不要な情報は省きます。

含める内容と省く内容

引き継ぎに価値があるのは、新しいエージェントが自力では再構成できない情報を伝えることです。

• 含める：目標とその重要性、完了済みの作業と未完了の作業、直ちに行う次のアクション、決定事項とその理由、すでに除外した行き詰まる方法、注意点や制約、実行方法と検証方法。
• 省く（代わりに参照する）：すでに文書化されている内容。仕様書、ADR、計画、Issue、コミットメッセージ、差分、PR の説明などが該当します。パスまたは URLで参照し、内容を貼り付けないでください。差分をそのまま書き直した引き継ぎはノイズです。
• 削除する：API キー、トークン、パスワード、個人を特定できる情報。秘密情報をドキュメントに残してはいけません。値ではなく名前（「.env にあるステージング DB のパスワード」など）で参照してください。

ドキュメントの構成

以下のセクションを記述してください。実際に該当する内容がないセクションは、水増しせず省略してください。

セクションごとに文体を使い分けます。 Current state、Next steps、How to run / verify は、作業を行う人が読むセクションです。ASD-STE100 Simplified Technical English で記述してください。1 文につき 1 つの指示とし、手順を示す文は 20 語以内にします。能動態と現在形を使い、行為者を明示し、比喩や慣用表現は使わず、ドキュメント全体で同じ対象には同じ用語を使います。冒頭で worker と呼んだ対象を、後半で job runner と呼んではいけません。Goal と Decisions & constraints は、作業に着手する前に判断を行う人が読むセクションです。理由を含めた通常の文章を使います。却下した方法を短い手順にまとめると、次のエージェントが同じ方法を繰り返さないために必要な理由が失われます。

# Handoff: <one-line title of the work>

## Goal
What we're trying to achieve and why. If the user gave a focus argument, frame this around it.

## Workspace
Required when the task involves code. The repository root and the worktree path, the branch, the HEAD SHA, the upstream and the count of unpushed commits, the dirty state (each modified, staged, or untracked path, or "clean"), and any stash the session made.

## Current state
What's done and working, what's half-done, what's untouched. Be concrete. Name each check that has not run or is failing, with the command that shows it.

## Next steps
The ordered actions the next agent should take. Start with the very first one.

## Key files & artifacts
Paths and URLs that matter (source files, the spec, the open PR, the failing test). Reference, don't reproduce.

## Decisions & constraints
Choices made and *why*; approaches already ruled out; hard limits and things not to break.

## Open questions / blockers
Unknowns, pending answers, or anything waiting on the user.

## How to run / verify
Commands to build, run, or test, enough to reproduce the current state.

## Suggested skills
Capabilities the next session should reach for, e.g. a commit skill to land the work, a PR skill to open the pull request, a test-plan skill to verify. Name them by function, not by a specific tool that may not be installed. Recommend by relevance to the goal.

手順

1. セッションを読み直します。 会話を確認し、目標、現在の状態、決定事項、未解決の点を把握します。これらが文書の素材になります。各セクションに素材が含まれているか、空であることが確認できたら、この手順は完了です。

2. タスクにコードが関係する場合は、ワークスペースを読みます。 セッションの記憶ではなく、必ず git から読み取ってください。セッションの内容が最後のコミットより古い可能性があるためです。

   git rev-parse --show-toplevel; git worktree list
   git branch --show-current; git rev-parse HEAD
   git rev-parse --abbrev-ref @{upstream}; git rev-list --count @{upstream}..HEAD
   git status --short; git stash list
   

   Bash は、これらの読み取り専用クエリに限って宣言されています。上流へのクエリに失敗した場合は「上流なし」と見なし、その旨を文書に記載します。今回の実行で読み取った値が、すべてのワークスペース項目に設定されたら、この手順は完了です。

3. 引き継ぎ事項と参照情報を分けます。 記載する価値のある項目ごとに、それがこのチャットにしかない情報（引き継ぐ）なのか、すでに成果物になっている情報（リンクする）なのかを判断します。すべての項目にどちらかのラベルを付けたら、この手順は完了です。

4. 上記の形式に沿って文書を作成します。 焦点となる論点が指定されている場合は、それを重視します。リンク先の成果物にない情報をすべての文に含め、空のセクションを削除し、次の手順の冒頭に、次のエージェントがほかの箇所を読まずに実行できるアクションを置いたら、草案の作成は完了です。

5. 機密情報を削除します。 出力前に、秘密情報や個人を特定できる情報を削除してください。キー、トークン、パスワード、個人情報が値そのままで記載されていないことを確認したら、この手順は完了です。

6. 以下の出力ルールに従って保存または表示し、引き継ぎに従って終了します。

出力

既定：Markdown ファイルを保存します。 完成した引き継ぎ文書をワークスペースの docs/handoffs/ に保存します。ディレクトリが存在しない場合は作成します。ファイル名は NNNN-handoff-<slug>-YYYY-MM-DD.md とし、次の連番、短い小文字のケバブケースの件名スラッグ、末尾に引き継ぎ文書の作成日（ISO 形式）を使用します（例：0005-handoff-auth-migration-2026-07-13.md）。連番 NNNN を決めるには、このワークツリー、git worktree list が示すすべてのワークツリー、origin/HEAD（git fetch origin 後の git ls-tree --name-only origin/HEAD docs/handoffs/）を対象に、docs/handoffs/ にある先頭4桁の連番の最大値を調べ、1を加えます。該当するものがない場合は 0001 から始めます。並行して作業するワークツリーで連番が重複しないよう、3つすべてを確認してください。リモートがない場合など、確認に失敗したソースはスキップします。git がない場合はディレクトリだけを確認します。連番はディレクトリごとに管理し、再利用しません。同じ引き継ぎ文書を編集する場合は、ファイル名を変えず、既存ファイルを更新します。ユーザーには正確なパスを伝えます。

明示的な依頼がある場合：インラインで表示します。 ユーザーがターミナル出力、インライン表示、チャットのみ、またはコピー可能な出力を明示的に求めた場合は、完成した引き継ぎ文書を Markdown のコードブロック1つで出力し、ファイルには書き込みません。

書き込み可能なファイルシステムがない場合：代替手段を使います。 ファイルに書き込めない環境では、完成した引き継ぎ文書を Markdown のコードブロック1つで出力し、ファイルを作成しなかったことを伝えます。

引き継ぎ

このセクションは手順を示す文体で書きます。各文は1つの指示とし、能動態、現在形を使い、比喩を避けます。

変更点。 プロジェクト自体には変更を加えません。引き継ぎ文書を新規作成または更新したことと、その文書を明記します。

保存先。 正確なパス（docs/handoffs/NNNN-handoff-<slug>-YYYY-MM-DD.md）を記載します。インラインで出力した場合は「インラインで表示。ファイルは未作成」と記載します。

次の手順。 1つだけ実行します。この文書を起点に新しいセッションを開始し、引き継ぎ文書の最初の次の手順から着手します。ユーザーがファイルを開かなくても内容がわかるよう、その手順をここに記載します。このセッションでは、それ以外の作業を続けません。この引き継ぎによって、このセッションのコンテキストを終了できるようにします。