agent-handoff

Agent Handoff — ブートストラップと管理

このスキルは、AI エージェント（Claude、Codex、Gemini、Cursor、 Windsurf、OpenCode、Copilot など）間のシームレスな引き継ぎを可能にする 共有コンテキストディレクトリ .ai/ をブートストラップし、維持します。

常時有効な読み書き動作は、インストール時に各エージェントの設定ファイル （CLAUDE.md、codex.md、.cursorrules など）に挿入されるスニペットが担います。 このスキルは、初回のブートストラップ、古くなった情報の検出、プロジェクトの スキャンといった、より大掛かりな処理を担います。

ファイル形式のテンプレートについては、references/templates.md を参照してください。 実際の使用例については、references/examples.md を参照してください。

---

このスキルが呼び出される条件

• ユーザーが「agent handoff」「handoff」「bootstrap」「initialize」「set up handoff」「set up agent context」と言う
• ユーザーが「continue」「resume」「keep going」「what was the last agent doing」と言う
• .ai/ の中核ファイルが欠落している、空である、またはインストーラーのプレースホルダーが残っている場合： .ai/PROJECT.md、.ai/PATHS.md、.ai/PLAN.md、.ai/conversations/HANDOFF.md
• HANDOFF.md の情報が古い（最終更新から7日超）
• ユーザーがセッションファイル、引き継ぎ内容が書き込まれていないこと、または別のエージェントが引き継ぎフローを呼び出さないことについて質問する
• ユーザーが /agent-handoff を明示的に呼び出す

---

初回のブートストラップ

必須ファイルが欠落している、空である、またはプレースホルダーのみの場合は、完全なブートストラップを実行します。

• .ai/PROJECT.md
• .ai/PATHS.md
• .ai/PLAN.md
• .ai/conversations/HANDOFF.md

プレースホルダーの例には、Last updated: —、(empty)、"created (empty, will be populated on first agent run)"、または見出ししかないファイルが含まれます。

Step 1: ディレクトリ構造を作成する

mkdir -p .ai/conversations/decisions .ai/conversations/sessions
mkdir -p ".ai/conversations/sessions/$(date +%F)"

Step 2: プロジェクトの種類と技術スタックを検出する

存在するすべてのパッケージマニフェストを読み取ります（複数の言語を使うプロジェクトでは、複数存在する場合があります）。

• composer.json — PHP（Laravel、Symfony など）
• package.json — Node.js／フロントエンド（Next.js、Nuxt、React、Vue、Angular など）
• Gemfile — Ruby（Rails、Sinatra など）
• requirements.txt／pyproject.toml／Pipfile — Python（Django、Flask、FastAPI など）
• go.mod — Go
• Cargo.toml — Rust
• pom.xml／build.gradle — Java／Kotlin
• *.csproj／*.sln — .NET

存在するすべてのエージェント／規約の設定ファイルを読み取ります。

• CLAUDE.md、AGENTS.md、.cursorrules、.windsurfrules、codex.md、GEMINI.md
• README.md、CONTRIBUTING.md
• .editorconfig、リンター設定（.prettierrc、eslint.config.*、phpcs.xml など）

環境に関する手がかりを読み取ります。

• .env.example — 想定される環境変数
• docker-compose.yml／Dockerfile — コンテナ化されたセットアップ
• Makefile／justfile — よく使われるコマンド

Step 3: ドキュメントを見つける

以下の場所でドキュメントファイルをスキャンします。

Root:        *.md files (README, CHANGELOG, CONTRIBUTING, ARCHITECTURE, etc.)
Docs:        docs/  documentation/  wiki/  guides/  .github/
Specs:       specs/  spec/  plans/  rfcs/  adrs/  design/  proposals/
API:         docs/api/  api-docs/
             openapi.yaml  openapi.json  swagger.json  swagger.yaml
             *.postman_collection.json (up to 3 levels deep)
             insomnia*.json  insomnia*.yaml
Nested:      docs/archive/  docs/plans/  any docs/ subdirectory with markdown

見つかった場所ごとに、次の処理を行います。

find {dir} -maxdepth 3 -type f \( -name "*.md" -o -name "*.pdf" -o -name "*.postman_collection.json" -o -name "openapi.*" -o -name "swagger.*" \)

タイトルまたは先頭10行を読み、分類します。

カテゴリ	例	優先度
要件	TRD、PRD、BRD	HIGH — 実装前に読む
アーキテクチャ	システム設計、ADR	HIGH
実装計画	ロードマップ、段階的実装のドキュメント	HIGH
プロジェクト概要	概要、プロジェクト概要書	HIGH
運用ガイド	ユーザーガイド、ランブック	MEDIUM
API ドキュメント	インテグレーションガイド、OpenAPI	MEDIUM
機能仕様	機能ごとの仕様、RFC	ON-DEMAND
アーカイブ	archive/ 内のもの、または古いバージョン	LOW

バージョン検出： 複数のバージョン（例：TRD-v3、TRD-v4、TRD-v5）が存在する場合、 番号が最も大きいもの、または日付が最も新しいものを現行バージョンとして特定します。現行バージョンのみを 「Reference Documents (current)」に記載します。古いバージョンは「Archived」に記載します。

Step 4: 仕様／計画ディレクトリのパターンを検出する

specs/、rfcs/、adrs/ などのディレクトリが存在する場合：

1. すべてのサブディレクトリを一覧表示する
2. 代表的なものを1つ選び、その内容を一覧表示する
3. 検出したパターン（各エントリにどのようなファイルが含まれるか）を記録する
4. すべてのエントリを1行の説明とともに一覧表示する
5. アクティブな項目と完了済みの項目を特定する（Git の履歴またはタスクのチェックボックスを確認する）

正式な仕様管理システムがない場合は、検出できる範囲で、プロジェクトが作業をどのように追跡しているか （GitHub Issues、Jira、非公式な方法など）を記載します。

ステップ 5：コンテキストファイルを生成する

references/templates.md のテンプレートを使用して、以下を生成します。

• .ai/PROJECT.md — 検出したスタック、アーキテクチャ、主要なドキュメントから生成
• .ai/PATHS.md — 発見したファイルとドキュメントから生成
• .ai/PLAN.md — 進行中の作業（Git ブランチ、最近のコミット、仕様のステータス）から生成
• .ai/conversations/HANDOFF.md — 「system initialized」という注記を含む初期状態
• .ai/conversations/LOG.md — ヘッダーのみ

すべての日付には、実際のローカルシステム時刻を使用します。Unix 系システムでは、次の方法で取得します。

date '+%Y-%m-%d %H:%M %Z'
date '+%Y-%m-%d/%H%M%S'

新しいログ／セッション記録を作成するときは、古いプロジェクトドキュメント、モデルの記憶、以前の引き継ぎ記録にある日付を決してコピーしないでください。

ステップ 6：常時有効なスニペットをエージェント設定ファイルに挿入する

エージェントが実際に読み込まない限り、.ai/ ファイルは役に立ちません。このステップでは、すべてのエージェントの設定ファイルに、起動時の読み取り／タスク後の書き込み動作を実行する常時有効なスニペットが含まれていることを確認します。

inject.md からスニペットを読み込みます（この SKILL.md ファイルと同じディレクトリにあります。.claude/skills/agent-handoff/inject.md または .agents/skills/agent-handoff/inject.md を確認してください）。

以下の各エージェント設定ファイルについて、## Agent Handoff (always active) というマーカーがすでに含まれているか確認します。含まれていない場合は、スニペット全体を追加します。すでに含まれている場合は、そのままにします。

エージェント	設定ファイル	挿入する条件
Claude Code	CLAUDE.md	常に — ファイルが存在しない場合は作成
Codex (OpenAI)	codex.md	常に — ファイルが存在しない場合は作成
マルチエージェント／Antigravity	AGENTS.md	常に — ファイルが存在しない場合は作成
Cursor	.cursorrules	ファイルまたは .cursor/ ディレクトリが存在する場合のみ
Windsurf	.windsurfrules	ファイルが存在する場合のみ
Gemini CLI／旧バージョンの Antigravity	GEMINI.md	ファイルまたは .gemini/ が存在する場合のみ
OpenCode	.opencode/instructions.md	.opencode/ ディレクトリが存在する場合のみ
GitHub Copilot	.github/copilot-instructions.md	.github/ ディレクトリが存在する場合のみ

inject.md が見つからない場合は、代わりに次の最小限のフォールバック用スニペットを使用します。

## Agent Handoff (always active)


ON EVERY CONVERSATION START, read these files:
1. .ai/PROJECT.md
2. .ai/PATHS.md
3. .ai/PLAN.md
4. .ai/conversations/HANDOFF.md

If any are missing, empty, or placeholder-only, bootstrap/repair .ai/ before work.
Use `date '+%Y-%m-%d %H:%M %Z'` for real local timestamps.

BEFORE YOU FINISH EVERY RESPONSE, complete the handoff write-back:
- Append to .ai/conversations/LOG.md
- Update .ai/conversations/HANDOFF.md if files changed or decisions made
- Create a session file at .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md if files changed or decisions made
- In your final response, mention that handoff was updated or explain why no handoff write was needed
- Identify yourself by agent name in all writes

ステップ 7：ユーザーに報告する

Agent handoff system initialized.

Discovered: {N} reference documents, {N} feature specs, {N} archived docs.
Key documents: {list top 3}
Active work detected: {feature/branch or "none detected"}
Agent configs updated: {list of files where snippet was injected}
Gaps: {any missing elements like "no test directory found"}

---

古さの検出

HANDOFF.md が古い場合（最終更新から 7 日超）：

1. 引き継ぎの状態をそのまま信用しないでください
2. git log --oneline --since="7 days ago" を実行して、変更内容を確認します
3. Git の履歴と HANDOFF.md を照合します
4. 続行する前に、HANDOFF.md を現在の状態に更新します
5. 注記を追加します：[stale] Handoff was {N} days old. Refreshed from git history.

PATHS.md に存在しなくなったファイルへの参照がある場合：

1. 古い項目を削除します
2. ファイルの名前変更、移動、置き換えが行われたか確認します
3. 置き換え先が見つかった場合は追加します
4. クリーンアップ内容を LOG.md に記録します

---

サイズ制限

ファイル	最大行数	適用方法
PROJECT.md	~80	安定 — スタックまたはアーキテクチャが変わった場合のみ更新
PATHS.md	~150	重要度の低い項目はディレクトリの概要にまとめる
PLAN.md	~60	進行中の機能のみを追跡。完了した項目は一行にまとめる
HANDOFF.md	~100	ローリングウィンドウ：Recent Completions は最大 15～20 件。古い項目は LOG.md へ
LOG.md	~500	90 日より前の項目を LOG-archive-YYYY.md にアーカイブ
セッションファイル	~80 each	差分の繰り返しを避け、コミットハッシュを参照

起動時の読み取りコスト： 4 つのファイル合計で約 800～1500 トークン。
タスクごとの書き込みコスト： 複雑さに応じて約 500～1200 トークン。

---

複数エージェントの同時実行時の安全性

2 つのエージェントが同時に作業すると、ファイルの競合が発生することがあります。

予防策：

• HANDOFF.md の Active Work には、各エージェントが取り組んでいる内容を記載します。 作業を開始する前に、別のエージェントが現在アクティブかどうか確認してください。
• セッションファイルは競合しません — 各エージェントが、それぞれのタイムスタンプ付きファイルに書き込みます。
• LOG.md は追記専用です — 競合は簡単に解決できます（両方の項目を残します）。

HANDOFF.md でマージ競合が発生した場合：

1. 両方のエージェントの Active Work 項目を残します
2. Recent Completions を時系列順に統合します
3. すべての Key Context 項目を統合します

---

セッションファイルプロトコル

エージェントは、ファイルを変更する場合、判断を下す場合、将来のエージェントが必要とする可能性のある調査を行う場合、または別のエージェントの作業を引き継ぐ場合は、必ずセッションファイルを作成してください。

1. 4つの起動ファイルを読みます。
2. 環境から実際のローカル時刻を取得します。
3. 日付ディレクトリを作成します。 mkdir -p .ai/conversations/sessions/$(date +%F).
4. 次のファイル名を使用します。 .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md.
5. ファイルは簡潔かつ事実に基づいたものにします。大きな差分を貼り付けるのではなく、変更したファイル、ドキュメント、コミット、テスト、ブロッカーへのリンクを記載します。
6. HANDOFF.md の Active Work または Recent Completions からセッションファイルを参照します。
7. 対応する LOG.md のエントリーを追加します。
8. ユーザーへの最終回答で、ハンドオフを更新したことを伝えます。書き込みが不要だった場合は、その理由を伝えます。

エージェントがファイル変更を伴うタスクでセッションファイルを作成せずに LOG.md／HANDOFF.md を書き込んだ場合、ハンドオフは未完了です。次のエージェントは、入手可能な証拠に基づいてキャッチアップ用セッションファイルを作成し、修復してください。

---

モノレポプロジェクト

• .ai/ は個々のパッケージ内ではなく、リポジトリのルートに配置します
• PATHS.md には、すべてのパッケージ／サービスとそのパスを記載します
• PLAN.md では、パッケージ接頭辞を使用して複数のパッケージにまたがる作業を追跡できます
• セッションファイルには、変更したパッケージを記載します

---

ルール

1. 作業前に必ず読む。 会話開始時に4つのコンテキストファイルを読みます。例外はありません。
2. 作業後に必ず書き込む。 質疑応答であっても例外ではありません。今日回答した質問は、明日のコンテキストになります。
3. LOG.md は簡潔にする。 1エントリーあたり3～5行にします。詳細はセッションファイルに記載します。
4. サイズ制限を守る。 LOG.md が約500行を超えたらアーカイブします。
5. 決定事項を昇格させる。 アーキテクチャ／設計上の選択は decisions/ ディレクトリに記録します。
6. Git の履歴を重複させない。 差分ではなくコミットハッシュを参照します。
7. 実際のタイムスタンプを使用する。 プレースホルダーは使用しません。
8. LOG.md のすべてのエントリーにタグを付ける。 タグによって内容を確認しやすくなります。
9. PATHS.md を正確に保つ。 新しいファイルやドキュメントを追加したら、PATHS.md も更新します。
10. 進捗に応じて PLAN.md を更新する。 タスクを完了としてマークし、ブロッカーを追加し、担当エージェントを記載します。
11. 段階的に詳細を開示する。 HANDOFF.md → セッションファイル → ソースファイルの順に参照します。
12. 自分が誰かを明記する。 すべての書き込みにエージェント名を含めます。
13. LOG.md は追記専用です。 エントリーを削除しないでください。
14. 作業再開時に確認する。 別のエージェントの作業を続ける前に、ファイルが存在することを確認します。
15. 実装前にドキュメントを読む。 PATHS.md で関連する仕様／計画を確認します。
16. 新しいドキュメントはすぐにインデックス化する。 次のエージェントに任せないでください。
17. アーカイブ済みの情報より現行の情報を優先する。 アーカイブ済みドキュメントを正式な情報源として参照しないでください。
18. 参照元を記録する。 セッションファイルの References セクションに、参照したドキュメントを列挙します。