セッション設計：AIとの1セッションをどう区切るか

1
セッション開始（コンテキスト使用率: 5%）
2
  ↓ CLAUDE.md読み込み
3
  ↓ WBS読み込み
4
  ↓ 施策Aの要件定義
5
  ↓ 施策Aの設計
6
  ↓ 施策Aの実装（コード量が多い）
7
  ↓ テスト実行結果の確認
8
  ↓ ---- コンテキスト使用率: 60% ----
9
  ↓ 施策Bの要件定義
10
  ↓ 施策Bの設計
11
  ↓ 施策Bの実装
12
  ↓ ---- コンテキスト使用率: 90% ----
13
  ↓ 施策Cに着手しようとするが...
14
  ↓ Claudeが施策Aで定義した制約を忘れている
15
  ↓ 施策AとCで矛盾するコードが生成される

1
事故: 1セッションで3施策に着手した結果
2
  1. 施策A（フィルター追加）で config.py を修正
3
  2. 施策B（バッチサイズ最適化）で同じ config.py を別の方向に修正
4
  3. 施策C（ログ改善）で logger.py を修正
5
  4. 施策Bのテストが施策Aの変更を前提としていなかった
6
  5. マージ時にコンフリクト発生
7
  6. コンフリクト解消中に施策Aの変更が消失
8
  7. 本番でフィルターが無効化 → 16日間気づかず

1
セッション開始
2
  ↓ A-1: ブランチ作成
3
  ↓ A-2: CLAUDE.md/WBS読み込み → 施策内容把握
4
  ↓ A-3: 競合チェック → ユーザー確認
5
  ↓ B-4〜B-7: 仕様→設計→テスト設計→タスク
6
  ↓ B-8: 実装・テスト（QA自動実行）
7
  ↓ C-9〜C-11: ドキュメント移動→デプロイ手順書→PR作成
8
セッション終了

1
✅ 1施策1セッション
2
  - スコープが明確: このセッションで何を達成するかが決まっている
3
  - コンテキスト窓に余裕: 1施策分のコード・テスト・ドキュメントで収まる
4
  - クリーンなブランチ: feature/{施策名} ブランチに変更が集約される
5
  - 追跡可能: 「このPRはこの施策」と1対1対応
6

7
❌ 1セッションで3施策に着手
8
  - コンテキスト窓が溢れる
9
  - 施策Aの変更が施策Bに影響
10
  - マージコンフリクト発生
11
  - PRに複数施策が混在し、レビュー困難

1
CLAUDE.mdに書くもの:
2
  - 開発ルール（コーディング規約、禁止事項）
3
  - ワークフロー定義（施策開始/完了の手順）
4
  - QAワークフロー（commit前の自動チェック）
5
  - リスク検出ルール（本番影響、データ変更）
6

7
CLAUDE.mdに書かないもの:
8
  - 個別施策の詳細（→ WBS, .docs/）
9
  - 一時的な設計メモ（→ .tmp/）
10
  - 実行結果やログ（→ Git commit message, PR）

1
| ドキュメント     | いつ参照するか           | サイズ目安  |
2
|-----------------|------------------------|-----------|
3
| CLAUDE.md       | セッション開始時（自動）    | 3-5KB     |
4
| .wbs/CURRENT.md | A-2（施策内容把握）       | 2-3KB     |
5
| .docs/NNN_*.md  | B-4（要件定義）で必要な分   | 1-2KB/件  |
6
| .tmp/*.md       | B-5〜B-7で順次生成        | 1-3KB/件  |
7
| ADR             | 設計判断が必要なとき       | 0.5-1KB/件 |

1
# WBSの更新例
2

3
NEW-11（リトライ上限の自動調整）:
4
  ステータス: B-8（実装中）
5
  進捗: 設計完了、コア実装完了、テスト15/24件作成
6
  残作業: テスト9件追加、QAワークフロー実行、PR作成
7
  ブランチ: feature/auto-adjust-retry-limit
8
  最終更新: 2026-03-27 セッション2

1
❌ パターン1: 「ついでに」
2
  「施策Aの実装中にバグを見つけたので、ついでに修正」
3
  → 修正が施策Aのブランチに混入
4
  → PRのスコープが曖昧になる
5

6
  ✅ 対策: バグはissueに記録し、別セッションで修正
7

8
❌ パターン2: 「待ち時間に」
9
  「テスト実行中に暇だから、施策Bの設計を始めよう」
10
  → コンテキストに施策A + 施策Bの情報が混在
11
  → AIが施策Aの制約を施策Bに適用してしまう
12

13
  ✅ 対策: テスト実行中は結果を待つ。設計メモは別ファイルにメモだけ
14

15
❌ パターン3: 「似ているから一緒に」
5 collapsed lines
16
  「施策Cと施策Dは関連が深いから1セッションで」
17
  → 2施策分のコンテキストでウィンドウ圧迫
18
  → 後半で品質低下
19

20
  ✅ 対策: 関連施策でも別セッション。依存関係はWBSで管理

1
対処フロー:
2
  1. 実行中の処理の状態を記録
3
     - 何を実行しているか
4
     - 完了条件は何か
5
     - 結果をどこに保存するか
6
  2. WBSを更新（「B-8: 回帰テスト実行中、結果待ち」）
7
  3. セッションを終了
8
  4. 処理完了後、新セッションで結果を確認して続行

1
# 回帰テストの結果を永続化する例
2
import json
3
from pathlib import Path
4

5

6
def save_test_checkpoint(
7
    measure_id: str,
8
    completed_modules: list[str],
9
    remaining_modules: list[str],
10
    results_so_far: dict[str, float],
11
) -> Path:
12
    """回帰テストの中間結果を保存"""
13
    checkpoint = {
14
        "measure_id": measure_id,
15
        "completed_modules": completed_modules,
7 collapsed lines
16
        "remaining_modules": remaining_modules,
17
        "results_so_far": results_so_far,
18
        "timestamp": "2026-03-27T15:30:00",
19
    }
20
    path = Path(f".tmp/test_checkpoint_{measure_id}.json")
21
    path.write_text(json.dumps(checkpoint, indent=2, ensure_ascii=False))
22
    return path

1
緊急時の原則:
2
  1. WIPコミットを行う（git commit -m "WIP: {施策名} - {現在のステップ}"）
3
  2. WBSに進捗を記録
4
  3. .tmp/ に現在の作業状態を保存
5

6
復旧時:
7
  1. 新セッション開始
8
  2. CLAUDE.md → WBS → .tmp/ の順に読み込み
9
  3. WIPコミットの差分を確認
10
  4. 中断箇所から再開

1
圧縮で失われやすい情報:
2
  - 会話の序盤で定義した制約条件
3
  - コードの具体的な行番号や変数名
4
  - エラーメッセージの詳細
5

6
圧縮でも残りやすい情報:
7
  - 直近の作業内容
8
  - 繰り返し言及された重要なルール
9
  - CLAUDE.mdの内容（毎回読み込まれるため）

1
情報の種類          → 永続化先            → 復元方法
2
─────────────────────────────────────────────────
3
開発ルール          → CLAUDE.md          → 自動読み込み
4
施策の進捗          → .wbs/CURRENT.md    → A-2で読み込み
5
設計判断            → ADR                → 必要時に参照
6
一時的な設計メモ     → .tmp/*.md          → 必要時に参照
7
実装済みコード       → Gitリポジトリ       → ファイル読み込み
8
テスト結果          → CI/CDログ           → 必要時に参照

1
□ 1施策のみを対象とする
2
□ CLAUDE.md の自動読み込みを確認
3
□ WBSから施策の現在ステータスを把握
4
□ ブランチが正しいことを確認
5
□ 前セッションのWIP commitがあれば差分を確認

1
□ WBSのステータスを更新
2
□ .tmp/ に作業中の設計メモがあれば保存
3
□ 未完了のタスクがあればWBSに残作業を記録
4
□ コミットメッセージに施策IDを含める
5
□ 次セッションで最初にやるべきことをWBSに記載