handoff

ハンドオフ

現在の劣化したコンテキストを引き継がずに作業を続けられるよう、新しい Claude セッションに必要な情報をすべて伝える、構造化された HANDOFF.md ファイルを生成します。

claude-mem は新しいセッションごとに直近の観察内容をすでに挿入するため、新しいエージェントは何が起きたかの時系列を把握した状態で開始します。ハンドオフでは、その時系列だけでは伝えられない情報、つまり目標、失敗した試みとその理由、現在の仮説、正確な次の手順に加え、より詳しく記憶をたどるための参照先を補います。

使用するタイミング

• セッションが長くなり、Claude が混乱している、または同じことを繰り返している
• Claude が何度も同じ失敗する解決策を試している
• ユーザーが作業を中断し、後で再開したい
• /compact を実行しても、Claude に明確な指針がない
• ユーザーが「handoff」「generate a handoff」「I want to start fresh」「write a handoff doc」と言った

記録する内容

書き始める前に、この会話全体の流れをよく考えてください。このハンドオフは、この会話を一度も見たことのない Claude インスタンスにも役立つものでなければなりません。

必須セクション

1. 目標 — 1 段落で記述します。ユーザーが実際に達成しようとしていることは何ですか？現在の小さな作業ではなく、最終的な状態を明示します。新しいエージェントがすぐに状況を把握できる程度に具体的にしてください。

2. 現在の状態 — 今、何が動作していますか？何が壊れていますか？問題の症状を正確に記述します。該当する場合は、エラーメッセージを一字一句そのまま含めてください。

3. 関連ファイル — このセッション中に読み取り、編集、または作成したファイルのうち、現在の作業に関連するものをすべて列挙します。絶対パスまたはリポジトリ相対パスを使用します。それぞれのファイルが重要な理由を 1 行で説明してください。

4. 試したこと（および失敗した理由） — これが最も重要なセクションです。うまくいかなかったアプローチをすべて列挙し、失敗したという事実だけでなく、その理由を説明してください。このセクションを飛ばす新しいエージェントは、同じ間違いを繰り返します。

5. 現在の最有力仮説 — まだ証明できていなくても、現時点で正しいと考えている進め方を記述します。それを裏付ける証拠や推論も含めてください。

6. 次の手順 — 新しいエージェントが実行する具体的な手順を、順番に記述します。ファイルパス、関数名、実行するコマンドを明記してください。新しいエージェントが手順 1 からすぐに着手できるようにしてください。

7. 重要な制約と背景情報 — 環境の詳細、セッション中に表明されたユーザーの希望、明示的に避けるよう指示されたこと、外部依存関係、パフォーマンス要件など、見落としやすい制約を記述します。

8. メモリの参照先 — claude-mem の検索ツールが利用できる場合は、Smart search を使用します。この作業に関連するキーワードで search を実行し、該当する結果の前後を timeline で確認してから、選んだ記録だけを get_observations で取得します。特に重要な観察 ID（決定事項、根本原因、失敗したアプローチ）をいくつか列挙し、新しいエージェントがその記録を取得できるようにします。再実行する価値のある search クエリも 1 つか 2 つ記載します。ツールが利用できない場合は、このセクションを省略してください。

執筆ルール

• ユーザー向けではなく、新しい Claude に向けてハンドオフを記述します。ユーザーはすでに何が起きたかを知っていますが、新しい Claude は知りません。
• 徹底的に具体的にしてください。曖昧な次の手順は役に立ちません。「認証を直す」は不十分です。「src/auth/middleware.ts:47 でトークンの有効期限チェックに Date.now() が使われていますが、req.timestamp を使うべきです。52 行目の比較を変更してください」のように記述してください。
• 失敗の状況がわかる正確なエラーメッセージ、スタックトレース、テスト出力を含めてください。
• 冗長な記述は避けてください。すべての文が、新しいエージェントにとって重要な情報を含むようにしてください。
• ユーザーの視点でハンドオフを記述しないでください。引き継ぎを受けるエージェントへのブリーフィング文書として記述します。

出力

現在の作業ディレクトリ（プロジェクトルート）にある HANDOFF.md にハンドオフを書き込んでください。

# Handoff

> Generated: [timestamp]  
> Project: [project name or directory]  
> Session summary: [one sentence describing what this session was about]

## Goal

[What the user is trying to accomplish — the actual end state]

## Current State

**Working:**
- [list what is confirmed working]

**Broken:**
- [exact symptom, error message, or failure mode]

## Files in Play

| File | Why It Matters |
|------|---------------|
| `path/to/file.ts` | [one line] |

## What Has Been Tried (and Why It Failed)

### Attempt 1: [short name]
- **What:** [what was done]
- **Why it failed:** [root cause, not just "it didn't work"]

### Attempt 2: [short name]
...

## Current Best Theory

[What you currently believe is the correct approach and why]

## Next Steps

1. [Specific, actionable step with file path or command]
2. [Next step]
3. ...

## Key Constraints

- [Non-obvious constraint or preference the user expressed]
- [Things explicitly ruled out]

## Memory Pointers

- Observations: [#ID — one line on why it matters]
- Searches worth re-running: [`search` query]

作成後

ユーザーに次のことを伝えます。

1. HANDOFF.md を作成したこと
2. /clear を実行するか、新しい Claude Code セッションを開始すること
3. 新しいセッションを開き、**「HANDOFF.md を読んで、前回の続きから進めてください。」**と伝えること
4. claude-mem が新しいエージェントに最近の経緯を自動的に伝え、HANDOFF.md がその内容に加えて正確なブリーフィングを提供すること
5. HANDOFF.md は一時ファイルなので、コミットしないこと（新しいセッションで内容が引き継がれたら削除するか、.gitignore に追加してください）

メッセージは簡潔にしてください。ユーザーはすぐに作業を再開する準備ができています。長文を読ませないでください。