version: "1.0.0" name: session-handoff description: 長時間タスクの作業状態をファイルに永続化し、セッション・担当者・モデルをまたいで30分で再開できる状態を保つスキル。中断・引き継ぎが発生するすべての場面で使う。

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

目的

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

セッションが切れる・モデルが変わる・別の担当者が引き継ぐ、いずれの場面でも 「次の担当が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
 
## 環境情報
 

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]] を参照。

典型的な引き継ぎ準備フロー:

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]] — 再開時のコードベース把握