project-session-management

プロジェクトのセッション管理スキル

SESSION.md、Git チェックポイント、具体的な次のアクションを使って、作業セッション間の進捗を追跡します。

---

使用するタイミング

• project-planning が IMPLEMENTATION_PHASES.md を生成した後にプロジェクトを開始するとき
• コンテキストがクリアされた後に作業を再開するとき
• コンテキストがいっぱいになったときのフェーズ途中のチェックポイント
• フェーズの移行時
• 実装 → 検証 → デバッグのサイクルを追跡するとき

---

フェーズとセッションの違い

フェーズ（IMPLEMENTATION_PHASES.md）：作業の単位です（例：「データベーススキーマ」「認証 API」）。検証基準や終了基準があります。複数のセッションにまたがる場合があります。

セッション（SESSION.md）：コンテキストの単位です。コンテキストをクリア／圧縮する前に完了します。フェーズ全体、一部、または小規模な複数のフェーズを完了できます。

例：フェーズ 3（タスク API）→ セッション 1（GET/POST）→ セッション 2（PATCH/DELETE）→ セッション 3（検証）✅

---

ワークフロー

新規プロジェクトの開始：

1. project-planning が IMPLEMENTATION_PHASES.md を作成した後、「進捗を追跡するために SESSION.md を作成しますか？」と提案します。
2. フェーズをもとに SESSION.md を生成し、フェーズ 1 を 🔄（進行中）に設定して、具体的な「次のアクション」を設定します。

セッションの終了：

• 自動：/wrap-session（SESSION.md を更新し、チェックポイントコミットを作成して、概要を出力します）
• 手動：SESSION.md を更新 → Git チェックポイント → 具体的な「次のアクション」を設定

再開：

• 自動：/continue-session（コンテキストを読み込み、概要を表示して、「次のアクション」から続行します）
• 手動：SESSION.md を読む → 「次のアクション」を確認 → 続行

---

自動化コマンド

/wrap-session：状態を分析 → SESSION.md を更新 → 関連ドキュメントを更新 → チェックポイントコミットを作成 → 概要を出力 → 必要に応じてプッシュ

/continue-session：SESSION.md と計画ドキュメントを読み込み → Git 履歴と概要を表示 → 検証基準を表示（検証ステージの場合）→ 「次のアクション」のファイルを開く → 続行の許可を求める

---

SESSION.md の構成

目的：計画ドキュメントへの参照をまとめ、現在の進捗を追跡するナビゲーションハブ 目標：プロジェクトのルートに 200 行未満で配置 更新：大きな進捗があった後（変更のたびではありません）

テンプレート

# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation (or Verification/Debugging)
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup ✅
**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database ✅
**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API 🔄
**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:
- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

**Key Files**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

---

ステータスアイコン

次の絵文字ステータスアイコンを一貫して使用します。

• ⏸️ = 未着手（保留中）
• 🔄 = 進行中
• ✅ = 完了
• 🚫 = ブロック中

---

フェーズ内のステージ

1. 実装 → コードを記述
2. 検証 → 基準に照らしてテスト
3. デバッグ → 問題を修正

現在のステージと進捗を SESSION.md に更新します。例：

**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)

**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts

---

SESSION.md のガイドライン

✅ 完了したフェーズは簡潔にまとめる（2～3 行）。具体的な「次のアクション」（ファイル＋行番号＋タスク）を記載し、計画ドキュメントを参照し、フェーズ終了時またはコンテキストがいっぱいになったときにチェックポイントを作成します。

❌ コードをコピーしない、IMPLEMENTATION_PHASES.md の内容を重複させない、曖昧なアクションを書かない、200 行未満に保つ

---

Git チェックポイントの形式

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]

例（フェーズ完了）：

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)

Next: Phase 4 - Start building Task List UI component

---

想定される未コミットファイル（重要）

チェックポイントサイクル：/wrap-session はコミットを作成 → ハッシュを取得 → SESSION.md をハッシュで更新します。そのため、再開時には SESSION.md は常に未コミットです（仕様どおりの動作です）。

想定される未コミットファイル（警告なし）：

• SESSION.md - チェックポイントハッシュはコミット後に更新されるため、セッション間では常に未コミットです（正常）
• CLAUDE.md - 開発中に更新されることが多く、未コミットの場合があります（正常）
• .roomodes - エディター／IDE の状態であり、セッションの引き継ぎには関係ありません（無視して問題ありません）

警告の対象（想定外）：

• ソースファイル（.ts、.tsx、.js）
• 設定ファイル（vite.config.ts、wrangler.jsonc）
• 計画ドキュメント（IMPLEMENTATION_PHASES.md、ARCHITECTURE.md）
• 新しい未追跡ファイル

/continue-session の動作：

• SESSION.md／CLAUDE.md／.roomodes のみが未コミットの場合は ℹ️ 情報メッセージを表示
• コード／ドキュメントの変更が未コミットの場合は ⚠️ 警告を表示（想定ファイルを除いた一覧を表示）

コンテキスト管理

フェーズ途中でコンテキストがいっぱいになった場合：SESSION.md を更新 → チェックポイントを作成 → コンテキストをクリア → SESSION.md と計画ドキュメントを読む → 「Next Action」から続行

フェーズ完了時：検証基準を確認 → 🔄→✅ に変更 → チェックポイントを作成 → 次のフェーズを ⏸️→🔄 に変更

トラブルシューティング：「Debugging」ステージに更新 → 「Current Issue」を記録 → 解決したら「Verification」または「Implementation」に戻る

---

project-planning との連携

project-planning が IMPLEMENTATION_PHASES.md（計画）を生成 → project-session-management が SESSION.md（進捗トラッカー）を作成 → フェーズを順に進める → git チェックポイントを作成 → SESSION.md から再開

計画ドキュメント（/docs）：参照資料であり、変更はほとんどありません SESSION.md（ルート）：常に更新されるドキュメント

---

新規プロジェクトでの SESSION.md の作成

project-planning の実行後：

1. IMPLEMENTATION_PHASES.md を読む
2. ルートに SESSION.md を作成：フェーズ 1 は 🔄、その他は ⏸️
3. フェーズ 1 をタスクリストで詳細化
4. 具体的な「Next Action」を設定
5. レビュー用に出力

提案：「これらのフェーズの進捗を追跡するために SESSION.md を作成しますか？（現在のフェーズを明確化、進捗を追跡、簡単に再開、git チェックポイント形式）」

---

同梱リソース

テンプレート：SESSION.md.template、checkpoint-commit-format.md、CLAUDE-session-snippet.md

スクリプト：resume.sh（現在の状態を表示）

参考資料：session-handoff-protocol.md、best-practices.md