handoff

セッション引き継ぎスキル

Claude のセッション間で作業をシームレスに継続できるよう、構造化されたドキュメントを作成します。

使用するタイミング

• その日の作業セッションを終了するとき
• タスクの途中で休憩する前
• 一時的に別のプロジェクトに切り替えるとき
• 次のセッションに向けて状況を記録したいとき
• 予定されているコンテキストのリセットの前

引き継ぎの手順

ステップ 1：セッションの状況を確認する

次の点を手短に確認します。

1. どのフェーズにいますか？（調査、計画、実装、デバッグ、レビュー）
2. 現在のタスクは何ですか？（達成しようとしていること）
3. どのくらい進んでいますか？（開始直後、途中、ほぼ完了）

ステップ 2：重要なことを尋ねる

ユーザーに尋ねます。

「引き継ぎドキュメントを作成します。特に記録しておきたいことはありますか？（重要な決定、コードスニペット、問題の背景、忘れそうなことなど）」

ステップ 3：引き継ぎドキュメントを作成する

構造化されたドキュメントを作成します。

# Session Handoff: [Brief Description]

**Date:** [YYYY-MM-DD] **Project:** [project name/path] **Session Duration:**
[approximate]

## Current State

**Task:** [What we're working on] **Phase:**
[exploration/planning/implementation/debugging/review] **Progress:** [where we
are - percentage or milestone]

## What We Did

[2-3 sentence summary of the session's work]

## Decisions Made

- **[Decision]** — [Rationale]
- **[Decision]** — [Rationale]

## Code Changes

**Files modified:**

- `path/to/file.ts` — [what and why]
- `path/to/other.ts` — [what and why]

**Key code context:** [Critical snippets or patterns to remember]

## Open Questions

- [ ] [Question needing resolution]
- [ ] [Question needing resolution]

## Blockers / Issues

- [Issue] — [current status]

## Context to Remember

[Important background, constraints, user preferences, domain knowledge - things
that would take time to re-establish]

## Next Steps

1. [ ] [First thing to do next session]
2. [ ] [Second thing]
3. [ ] [Third thing]

## Files to Review on Resume

- `path/to/key/file.ts` — [why it matters]

ステップ 4：ファイルを書き込む

書き込み先：.claude/handoffs/[YYYY-MM-DD]-[brief-description].md

保存場所をユーザーに確認します。

「.claude/handoffs/[filename].md に保存します。別の場所がよいですか？」

記録する内容

必ず含める内容

1. 理由を添えた決定事項 — 多くの場合、「何を」より「なぜ」のほうが価値があります
2. コードの変更 — ファイルパス、変更内容、変更の意図
3. 現在の進捗 — タスクのどこで作業を中断したか
4. 次のステップ — 作業を再開するための、明確で実行可能な項目
5. ユーザーのコンテキスト — ユーザーが共有した制約、好み、分野に関する知識

関連する場合に含める内容

• 発生したエラー — 解決したかどうか、その方法
• 行き詰まったアプローチ — 試してうまくいかなかった方法（再調査を減らせます）
• 重要なファイル — 状況を把握し直すために読むファイル
• 外部依存関係 — 関連する API、サービス、ツール

省略する内容

• 冗長なツールの出力（ファイル一覧、grep の結果など）
• 結論に至った途中の推論
• 繰り返された同様の操作
• コードを見れば明らかな情報

書式のガイドライン

• 箇条書き — 説明文よりも一覧性を重視します
• ファイルパス — 「その関数」ではなく src/foo.ts:42 のように記載します
• アクションにはチェックボックス — 次のステップや未解決の質問には - [ ] を使います
• 具体的に記述 — 「改善した」ではなく「fetchUser() にリトライロジックを追加」のように記載します

品質チェック

保存する前に、次の点を確認します。

1. 初めて読む Claude がこの内容から作業を再開できますか？ — 続けるための十分なコンテキストがありますか？
2. 決定の経緯をたどれますか？ — 決定の理由が明確ですか？
3. 次のステップは実行可能ですか？ — 最初に何をすべきか正確にわかりますか？
4. コード作業の内容は明確ですか？ — どのファイルが重要かわかりますか？

引き継ぎドキュメントの使用方法

新しいセッションを開始するとき、ユーザーは次のことができます。

1. セッション開始時に引き継ぎファイルを共有する
2. 「この引き継ぎから再開してください：[貼り付けまたはパス]」と伝える
3. 対応している場合は、@ メンションで参照する

引き継ぎドキュメントを使えば、長々と説明し直さなくても、すぐに作業を再開できます。

引き継ぎの例

# Session Handoff: Auth System Implementation

**Date:** 2025-01-15 **Project:** /Users/robert/projects/my-api **Session
Duration:** ~2 hours

## Current State

**Task:** Implementing user authentication for the API **Phase:** Implementation
**Progress:** ~60% - basic flow works, need refresh tokens

## What We Did

Built the core JWT authentication flow including token generation, validation
middleware, and login/logout endpoints. Hit an issue with key rotation that we
resolved by moving to config-based key paths.

## Decisions Made

- **JWT with RS256** — Stateless auth, works with distributed setup
- **Redis for refresh tokens** — Need revocation capability
- **15-min access token expiry** — Balance security/UX for mobile app

## Code Changes

**Files modified:**

- `src/auth/jwt.ts` — Token generation and validation logic
- `src/middleware/auth.ts` — Request authentication middleware
- `src/routes/auth.ts` — Login/logout endpoints
- `config/keys/` — RSA key pair storage

**Key code context:** Token validation uses RS256. Keys loaded from
`config/keys/` based on NODE_ENV.

## Open Questions

- [ ] Automatic vs opt-in refresh token rotation?
- [ ] Rate limit for login attempts? (User mentioned 10k DAU)

## Context to Remember

- Client is a mobile app - tokens need offline capability
- User has 10k daily active users - scale matters
- Using PostgreSQL for user storage
- User prefers explicit error messages over generic ones

## Next Steps

1. [ ] Implement `/auth/refresh` endpoint
2. [ ] Add rate limiting to `/auth/login`
3. [ ] Write tests for token expiry edge cases
4. [ ] Update API docs with auth flow

## Files to Review on Resume

- `src/auth/jwt.ts` — Core token logic
- `src/routes/auth.ts` — Current endpoint implementation

重要な注意事項

• 作成する前に、ユーザーにとって何が重要かを尋ねる
• 決定には理由が必要 — 「なぜ」を記録する
• ファイルパスは作業の手がかり — 必ず含める
• 次のステップはすぐに実行できる内容にする
• 短く曖昧なものより、多少長くても役立つものにする