Session handoff

セッション引き継ぎ: 作業状態の永続化

目的

コンテキストは消えるがリポジトリは残る。これが大原則。

セッションが切れる・モデルが変わる・別の担当者が引き継ぐ、いずれの場面でも 「次の担当が30分で作業を再開できる状態」を常に保つ技術を定める。

使うタイミング

• タスクが複数セッションにまたがる見込みのとき(着手前)
• 中断する前(セッション終了・切り替え時)
• 担当者・モデルを変えて引き継ぐとき
• 長時間タスクの区切り(1タスク完了ごと)

進め方

1. progress.md を作業開始時に作る

リポジトリ内 docs/progress.md(または PROGRESS.md)を作成する。 作業後ではなく作業しながら更新する。

docs/
  progress.md     ← 一時的な作業状態(随時更新)
  adr/            ← 恒久的な設計判断 ([[architecture-design]])
CLAUDE.md         ← プロジェクト規約 ([[documentation]])

2. progress.md を育てながら作業する

1つのタスクが終わるたびに「完了したこと」に移動し、「次にやること」を更新する。 「あとでまとめて書く」は機能しない——書かれない。

3. 区切りを設計して止める

「テストが通る状態」「1タスク完了」など、再開しやすい区切りで止める。 中途半端な状態で止まるなら、その旨と再開手順を progress.md に明記する。

4. 区切りでコミットする

未コミットの巨大差分を残して中断しない。WIPでもブランチ上でコミットし、 コミットメッセージに文脈を書く。詳細は [[git-workflow]] を参照。

git add -p                          # 意図した変更だけを選択
git commit -m "WIP: ○○機能の骨格 — テストは未着手、XXXが未解決"

5. 引き継ぎ文書を作成する

中断・引き継ぎ時は docs/handoff.md を作成または更新する。 テンプレートは後述の「成果物テンプレート」を参照。

6. 定期的に棚卸しする

長期プロジェクトでは progress.md が肥大化する。 完了項目は docs/progress-archive.md に移動し、 progress.md は常に「今の状態」だけを映すようにする。

再開手順

1. docs/handoff.md(なければ docs/progress.md)を読む
2. git log --oneline -20 と git diff HEAD~1 で直近の変更を確認する
3. テストを回して現状の健全性を確認する(npm test 等)
4. progress.md の「次にやること」の先頭から着手する
5. 不明点があれば判断履歴を確認し、同じ検討を繰り返さない

成果物テンプレート

progress.md

# 作業進捗

最終更新: YYYY-MM-DD HH:MM

## ゴール

<!-- 1〜3文で。何を達成したら完了か -->

## 完了したこと

- [x] ○○の実装 (commit: abc1234)
- [x] △△のテスト追加

## 次にやること(優先順)

1. [ ] **□□のエラーハンドリング** — src/foo/bar.ts の TODO を実装する
2. [ ] ××のマイグレーション作成
3. [ ] E2Eテストの追加

## 未解決の問題

- **問題**: ○○APIのタイムアウトが再現不定期
  - 試したこと: リトライ3回、タイムアウト値を30sに変更
  - 仮説: ネットワーク起因か、レスポンスのパース処理か
  - 次のアクション: ログを増やして再現を待つ

## 重要な判断と理由

- ○○ライブラリは採用しない → ライセンスがXXで商用利用不可(2024-01-15)
- DBスキーマはマイグレーションで管理 → 本番DBとの差分追跡が必要なため

引き継ぎ文書(handoff.md)

# 引き継ぎ文書

作成日: YYYY-MM-DD
作成者: (モデル名 or 担当者名)
引き継ぎ先: (モデル名 or 担当者名)

## ゴールと背景

<!-- なぜこのタスクが存在するか。ユーザーが何を達成したいか -->

## 現状(何がどこまで動くか)

- **動く**: ○○機能(手動で確認済み、テスト通過)
- **動かない / 未実装**: △△機能(src/foo/bar.ts の TODO)
- **不安定**: ××(再現条件が不明)

## 残タスク(優先順・具体的に)

1. **□□のエラーハンドリング** — src/foo/bar.ts L42 の TODO を実装
   - 期待動作: 接続エラー時に503を返しリトライを促す
2. ××のマイグレーション — `npx prisma migrate dev` で生成する
3. E2Eテスト — cypress/e2e/login.cy.ts に追加

## ハマりポイントと回避策

- **○○APIは初回呼び出しが遅い**: コールドスタートあり。テスト時は2回目以降の結果を使う
- **YYY環境変数が必要**: `.env.example` に記載あり。本番値は1Passwordの「PJ-XXX」vault

## 環境情報

```bash
node -v   # v20.x が必要
npm ci
cp .env.example .env  # 値は1Password参照
npm run dev

• 認証情報の所在: 1Password vault「PJ-XXX」
• ステージング環境: https://staging.example.com (VPN必要)

判断履歴

やったこと・やらないと決めたこと

判断	理由	日付
○○を採用	△△と比較してXXXの点で優れる	2024-01-10
○○を採用しない	ライセンスが商用不可	2024-01-15
リファクタリングは後回し	期限優先。Issueに積んである	2024-01-18

## チェックリスト

中断前の確認:

- [ ] progress.md を最新状態に更新した
- [ ] 「次にやること」が具体的で、ファイル名・行番号レベルで書いてある
- [ ] 未解決の問題に「試したこと」と「次のアクション」が書いてある
- [ ] 重要な判断に「理由」が書いてある
- [ ] WIPコミットをした(未コミット差分が巨大でない)
- [ ] 環境セットアップ手順が書いてある(認証情報の所在を含む)
- [ ] 引き継ぎ先が読む必要のある追加ファイルを列挙した

## アンチパターン

- **頭の中だけで状態管理**: セッションが切れたら消える。必ずファイルに書く
- **「あとでまとめて書く」**: 書かれない。作業しながら更新する
- **巨大な未コミット差分での中断**: 次の担当が変更の意図を読めない。区切りでコミットする
- **抽象的すぎる引き継ぎ文書**: 「もろもろ対応中」「いい感じに進んでいる」→ 次の担当が全部再調査する
- **判断理由を残さない**: 後任が同じ検討を繰り返す。「やらないと決めたこと」こそ書く
- **progress.md の放置肥大化**: 完了項目が溜まり続けて「今の状態」が見えなくなる
- **引き継ぎ文書を最後に作る**: 中断が突然来たとき何も残らない。随時更新が原則

## モデル委譲ガイド

共通原則は [[orchestration]] を参照。

| 役割 | 担当 | このスキルでの作業 |
|---|---|---|
| **司令塔(メインモデル)** | 判断・記録の責任者 | 何を記録に残すかの判断、引き継ぎ文書の構成決定、「次にやること」の優先順位付け |
| **Opus相当** | 高品質な文書化 | 複雑な判断履歴の整理、設計判断のADR化、引き継ぎ文書の品質レビュー |
| **Sonnet相当** | 記録の整形・更新 | progress.md の定型更新、handoff.md のドラフト作成、完了項目のアーカイブ |
| **Haiku相当** | 現状の収集 | `git status`・直近ログの収集、テスト実行結果の取得、ファイル一覧の調査 |

典型的な引き継ぎ準備フロー:
1. Haiku相当で現状(git log、テスト結果)を収集
2. Sonnet相当でprogress.md / handoff.md を更新
3. 司令塔が内容をレビューし、判断理由の抜け漏れを補完

## 関連スキル

- [[orchestration]] — モデル委譲の共通原則
- [[git-workflow]] — コミット戦略・ブランチ運用
- [[architecture-design]] — 恒久的な設計判断のADR化
- [[documentation]] — CLAUDE.md等のプロジェクト規約管理
- [[task-execution]] — タスク実行の基本フロー
- [[task-breakdown]] — 長期タスクの分割と管理
- [[project-management]] — 進捗管理・マイルストーン設計
- [[codebase-exploration]] — 再開時のコードベース把握