【技術解説】Claude Codeのセッション管理術 - 長期プロジェクトを効率よく進める方法
Claude Codeで長期プロジェクトを開発していると、こんな悩みに直面します。
「前回どこまでやったっけ？」 「この設定、前のセッションで決めたはずなのに...」 「同じ質問を何度もされる」
Claude Codeはセッションごとに独立して動作するため、文脈の引き継ぎが課題になります。この記事では、合同会社QUESTで実際に運用している「セッション管理術」を全て公開します。
CLAUDE.mdとSkillsフォルダを活用した状態管理、セッション復元機能、自動文脈復元の仕組みを徹底解説します。
この記事で得られること
- Claude Codeのセッション問題とその解決策
- CLAUDE.mdの効果的な書き方
- Skillsフォルダによる知見の蓄積方法
- セッション復元機能(
claude --resume)の活用法 - 長期プロジェクトのベストプラクティス
- 実際の運用例(合同会社QUESTでの実践)
Claude Codeのセッション問題とは
コンテキストウィンドウの制限
Claude Codeは非常に強力なAIコーディングツールですが、セッションごとに独立しています。
┌──────────────────────────────────────┐
│ セッション1 (12/15 10:00-12:00) │
│ - ログイン機能を実装 │
│ - テストを作成 │
└──────────────────────────────────────┘
↓ セッション終了
┌──────────────────────────────────────┐
│ セッション2 (12/16 14:00-16:00) │
│ 「前回何やったっけ？」← 覚えていない │
└──────────────────────────────────────┘
この問題を解決しないと、毎回同じ説明を繰り返すことになり、開発効率が大幅に低下します。
よくある問題シーン
| シーン | 問題 |
|---|---|
| 翌日の作業開始時 | 前日の作業内容を覚えていない |
| 機能追加時 | プロジェクトのルールを忘れている |
| エラー対応時 | 以前解決した同じエラーで止まる |
| コードレビュー時 | 設計意図が伝わっていない |
長期プロジェクトでの影響
特に長期プロジェクト(数週間〜数ヶ月)では、この問題が深刻です。
1週間目: 順調に開発
↓
2週間目: 「あれ、このルールなんだっけ？」
↓
3週間目: 同じ質問を何度もされる
↓
4週間目: 開発効率が半減
私たちのプロジェクトでも、当初は毎回30分以上を文脈説明に費やしていました。
解決策: CLAUDE.mdとSkillsによる状態管理
アーキテクチャ全体像
私たちが採用している「セッション管理システム」の全体像です。
my-claude-project/
├── CLAUDE.md ──────────┐
│ ├─ 言語設定 │ ← 全プロジェクト共通の設定
│ ├─ 作業スタイル │
│ ├─ 自動実行ルール │
│ └─ 効率化ルール │
│ │
├── .claude/ │
│ └── skills/ ────────┤
│ ├── playwright-testing.md │ ← 専門知識を蓄積
│ ├── supabase-troubleshooting.md
│ ├── vercel-deployment.md
│ ├── session-restore.md
│ └── ... │
│ │
└── 各プロジェクト/ │
├── CLAUDE.md ───────────────────┤ ← プロジェクト固有設定
└── .claude/ │
└── CURRENT_STATUS.md ────────┘ ← セッション状態
3層構造による状態管理
| 層 | ファイル | 役割 | 更新頻度 |
|---|---|---|---|
| グローバル | /CLAUDE.md |
全プロジェクト共通ルール | 月1回程度 |
| スキル | /.claude/skills/*.md |
専門知識の蓄積 | 新しい知見が出るたび |
| プロジェクト | /project/CLAUDE.md |
プロジェクト固有ルール | 初回設定のみ |
| セッション | /project/.claude/CURRENT_STATUS.md |
現在の状態 | セッションごと |
この3層構造により、情報を適切な粒度で管理できます。
CLAUDE.mdの活用法
CLAUDE.mdとは
CLAUDE.mdは、Claude Codeが毎回自動で読み込む設定ファイルです。プロジェクトルートに配置することで、セッション開始時に自動的に文脈が復元されます。
プロジェクトルート/
├── CLAUDE.md ← ここに配置
├── package.json
├── src/
└── ...
基本構成
実際に合同会社QUESTで使用しているCLAUDE.mdの構成を紹介します(約700行)。
1. 言語設定
# CLAUDE.md
## 言語設定
**必ず日本語で回答してください。**
- すべての回答、説明、コメントは日本語で行うこと
- 思考プロセスや選択肢提示も日本語で記述すること
- コード内のコメントも日本語で記述すること(英語の技術用語は除く)
Claude Codeは英語で返答することがあるため、最初に明示的に言語を指定しています。
2. 作業スタイルの定義
## 作業スタイル(最重要・必ず従うこと)
### 役割分担
┌─────────────────────────────────────┐
│ ユーザー(ヒューマンセントリックス) │
│ - アイデア・構想を伝える │
│ - UI/UXの判断 │
│ - ビジネス判断(料金、権限) │
│ - 最終確認・承認 │
└─────────────────────────────────────┘
↓ 構想を渡す
┌─────────────────────────────────────┐
│ Claude(自律的ワーカー) │
│ - 企画・設計を具体化 │
│ - 開発・実装を一気に進める │
│ - テスト・デバッグを自動実行 │
│ - デプロイまで完了させる │
│ - 技術的判断はすべてClaudeが行う │
└─────────────────────────────────────┘
これにより、「このライブラリを使っていいですか？」といった不要な確認を減らせます。
3. 確認タイミングの明確化
### 確認が必要な場合(限定的)
- UI/UXの重要な判断(レイアウト、色、操作フロー)
- ビジネスロジックの判断(料金、権限、制限)
- 復旧不可能な危険操作(データ全消去、force push等)
### 確認不要(自律的に進める)
- 技術的な実装方法、ライブラリ選定、コード構造
- エラー修正・デバッグ・リファクタリング
- テスト作成・実行・デプロイ・ドキュメント作成
この明確化により、確認の手間を70%削減できました。
4. Skills自動参照ルール
### Skills自動参照ルール
**Claudeは以下のキーワードを検出したら、該当Skillを自動でReadすること。**
| トリガー(キーワード・文脈) | 自動参照するSkill |
|---------------------------|------------------|
| 「テスト」「Playwright」「E2E」 | `playwright-testing.md` |
| 「デプロイ」「Vercel」「本番反映」 | `vercel-deployment.md` |
| 「Supabase」「RLS」「マイグレーション」 | `supabase-troubleshooting.md` |
| 「クラッシュ」「落ちた」「前回の続き」 | `session-restore.md` |
キーワードを言うだけで、関連する知見が自動で読み込まれます。
実際の動作:
ユーザー: 「テストして」
↓
Claude: playwright-testing.md を自動でRead
↓
Claude: 適切なPlaywrightコマンドを実行
5. 自動実行フロー
### 自動実行フロー(プロアクティブ実行)
| タイミング | 自動実行する処理 |
|-----------|----------------|
| **機能実装完了時** | テスト生成 → テスト実行 → 失敗時は自動修正 |
| **PR作成前** | セキュリティ監査(XSS, SQLi, 認証バイパス) |
| **デプロイ前** | ビルド確認 → テスト全実行 → 問題なければデプロイ |
| **エラー修正後** | 関連テスト実行 → 回帰テスト |
| **DB変更後** | RLSポリシー確認 → 型生成(`npx supabase gen types`) |
これにより、「テスト忘れてた」「セキュリティチェックしてなかった」を防げます。
6. 口語体での指示対応
### プロジェクト自動判断(口語体から推測)
| 口語体 | 判断するプロジェクト |
|-------|-------------------|
| 「プレスタ」「Press」「記事生成」 | `Press-Starter/` |
| 「コーポレート」「会社サイト」 | `corporate-site-rebranding/` |
| 「モチベ」「motivation」 | `motivation-app/` |
実際の使用例:
ユーザー: 「プレスタのバグ直して」
↓
Claude: Press-Starter/ に移動 → エラー調査開始(確認不要)
非エンジニアでも自然に指示できるようになります。
CLAUDE.mdのサイズ感
私たちのCLAUDE.mdは約700行ありますが、セクションごとに分かれているので管理は容易です。
| セクション | 行数 | 内容 |
|---|---|---|
| 言語設定・MCP設定 | 80行 | 基本設定 |
| 作業スタイル | 120行 | 役割分担・確認ルール |
| 自動処理ルール | 200行 | トリガーと自動実行 |
| スタイリング・デザイン | 50行 | UI/UXルール |
| 効率化ルール | 150行 | 口語体対応、並列処理 |
| その他 | 100行 | セキュリティ、デプロイ等 |
Skillsフォルダの整理と活用
Skillsとは
Skillsは「よく使う知見をまとめたファイル」です。CLAUDE.mdから参照され、専門的な知識を蓄積します。
.claude/skills/
├── README.md
├── playwright-testing.md ← テスト自動化
├── supabase-troubleshooting.md ← DB関連の知見
├── vercel-deployment.md ← デプロイ手順
├── session-restore.md ← セッション復元
├── design-system.md ← デザインルール
└── platform-integration-patterns.md ← API連携
トリガーワードによる自動参照
Skillsは、CLAUDE.mdで定義したトリガーワードに反応して自動で読み込まれます。
仕組み:
## CLAUDE.md
| トリガー | 自動参照するSkill |
|---------|------------------|
| 「テスト」 | `playwright-testing.md` |
↓
ユーザー: 「ログイン機能のテスト書いて」
↓
Claude: キーワード「テスト」を検出
↓
Claude: playwright-testing.md を自動でRead
↓
Claude: Skillsの内容に従ってテストを生成
Skillsの具体例: playwright-testing.md
実際に使用しているSkillsの一部を公開します。
# Playwright テストスキル
**最終更新**: 2025-12-17
Playwright自動テストの実行方法、よくあるエラーと解決策。
---
## テスト実行コマンド
### 基本コマンド
npx playwright test # 全テスト実行
npx playwright test --ui # UIモードで実行
npx playwright test --debug # デバッグモード
### 特定テストのみ
npx playwright test tests/login.spec.ts
npx playwright test -g "ログイン" # パターンマッチ
## よくあるエラーと解決策
### タイムアウトエラー
- `timeout: 30000` を増やす
- `waitForLoadState('networkidle')` を追加
### 要素が見つからない
- セレクタを `data-testid` に変更
- `waitForSelector` を追加
### Console/Networkエラー検出
expect(consoleErrors).toHaveLength(0);
expect(networkErrors).toHaveLength(0);
## テスト自動生成のパターン
### ログイン機能のテスト
test('ログイン成功', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="email"]', 'test@example.com');
await page.fill('[name="password"]', 'password');
await page.click('button[type="submit"]');
await expect(page).toHaveURL('/dashboard');
});
このSkillsがあることで、「テストして」と言うだけで適切なテストが生成・実行されます。
Skillsの例: session-restore.md
セッション復元に関するSkillsです。
# セッション履歴の自動復元
**最終更新**: 2025-12-21
CLIがクラッシュした際の復元手順。
---
## クラッシュ検出の自動提案
**トリガーワード**:
- 「クラッシュ」「crash」
- 「落ちた」「落ちちゃった」
- 「消えた」「消えちゃった」
- 「前回の続き」
**検出時の自動対応**:
ユーザー: 「さっきクラッシュしちゃって...」
↓
Claude: 「CLIがクラッシュしましたね。前回のセッションを復元しますか？
以下のコマンドで自動復元できます:
claude --resume
実行しましょうか？」
---
## 復元手順(優先順位)
### 1. Claude標準機能(推奨)
claude --resume # 過去セッション一覧から選択
claude --continue # 直前のセッションを再開
### 2. 独自復元(標準機能で失敗した場合)
npm run restore
知見の自動蓄積ルール
Skillsは手動で作るだけでなく、自動で蓄積させることもできます。
## CLAUDE.md
### ナレッジ自動蓄積
**Claudeは以下のタイミングで、学んだ知見をSkillsに自動追記すること。**
| タイミング | 追記内容 |
|-----------|---------|
| **新しいエラーを解決した** | エラーパターンと解決策 |
| **新しいAPI連携を実装した** | API仕様とコード例 |
| **ユーザーから指摘を受けた** | 指摘内容と改善ポイント |
実際の動作:
セッション中にSupabaseのRLSエラーを解決
↓
Claude: supabase-troubleshooting.md に自動で追記
↓
次回から同じエラーはすぐ解決できる
セッション復元機能の活用
claude --resumeとclaude --continue
Claude Code CLIには、標準でセッション復元機能が搭載されています。
| コマンド | 機能 |
|---|---|
claude --resume |
過去セッション一覧から選択して復元 |
claude --continue |
直前のセッションを再開 |
claude --resumeの使い方
# 過去セッション一覧を表示
$ claude --resume
Select a session to resume:
1. [2025-12-20 14:30] Press-Starter: ログイン機能実装
2. [2025-12-19 10:00] corporate-site: ブログ記事追加
3. [2025-12-18 16:45] motivation-app: リファクタリング
Enter session number: 1
選択したセッションの会話履歴・ツール実行結果が完全に復元されます。
claude --continueの使い方
# 直前のセッションを再開
$ claude --continue
Resuming session from 2025-12-20 14:30...
[前回の会話が復元される]
クラッシュ時の対応フロー
CLAUDE.mdに以下のルールを設定しています。
## セッション復元
**トリガーワード**: 「クラッシュ」「落ちた」「消えた」「前回の続き」
**Claudeの対応**: ユーザーが上記ワードを言ったら:
1. まず `claude --resume` の使用を案内
2. それでも復元できない場合は独自ツール `npm run restore` を案内
実際の動作:
ユーザー: 「さっきクラッシュしちゃった」
↓
Claude: 「CLIがクラッシュしましたね。以下のコマンドで復元できます:
claude --resume
過去セッション一覧から選択できます。実行しますか？」
独自復元スクリプト(npm run restore)
標準機能で復元できない場合のために、独自のセッション復元スクリプトも用意しています。
// scripts/restore-session.ts
import { readFileSync, readdirSync } from 'fs';
import { join } from 'path';
const SESSION_DIR = join(
process.env.HOME || process.env.USERPROFILE || '',
'.claude',
'projects',
'C--Users-tatsu-my-claude-project'
);
// 最新のセッションファイルを特定
const sessions = readdirSync(SESSION_DIR)
.filter(f => f.endsWith('.jsonl'))
.sort()
.reverse();
const latestSession = sessions[0];
// セッション履歴を解析
const lines = readFileSync(join(SESSION_DIR, latestSession), 'utf-8')
.split('\n')
.filter(Boolean)
.map(line => JSON.parse(line));
// 最後のユーザーメッセージを抽出
const userMessages = lines
.filter(msg => msg.role === 'user')
.slice(-5);
// 最後のClaude応答を抽出
const assistantMessages = lines
.filter(msg => msg.role === 'assistant')
.slice(-1);
// ツール実行履歴を抽出
const toolCalls = lines
.filter(msg => msg.content?.some?.(c => c.type === 'tool_use'))
.slice(-5);
console.log('📋 前回のセッション復元結果');
console.log('');
console.log('【最後のユーザー指示】');
console.log(userMessages[userMessages.length - 1]?.content);
console.log('');
console.log('【最後の作業内容】');
console.log(assistantMessages[0]?.content);
console.log('');
console.log('【次にやるべきこと】');
// ここで次のアクションを提案
CURRENT_STATUS.mdによる状態管理
CURRENT_STATUS.mdとは
各プロジェクトに配置する、現在の状態を記録するファイルです。
Press-Starter/
├── CLAUDE.md
└── .claude/
└── CURRENT_STATUS.md ← セッション状態を記録
フォーマット例
# CURRENT_STATUS.md(自動更新)
## 現在のフェーズ
MVP開発中
## 直近の作業(最新5件)
- 2025-12-20: ログイン機能を実装
- 2025-12-19: DB設計を完了
- 2025-12-18: プロジェクトセットアップ
## 未完了タスク
- [ ] パスワードリセット機能
- [ ] メール通知
- [ ] 管理画面UI
## 既知の問題
- note連携でタイムアウトが発生することがある
- RLSポリシーの権限設定要確認
## 次にやること
パスワードリセット機能の実装
自動更新のルール
CLAUDE.mdに以下を設定しています。
### セッション開始時の自動文脈復元
**新しいセッション開始時、Claudeは以下を自動実行:**
1. `{project}/.claude/CURRENT_STATUS.md` があれば読み込む
2. 直近のgitログを確認(`git log -5 --oneline`)
3. 未コミットの変更を確認(`git status`)
4. 前回の作業を把握して続きから開始
**セッション終了時(または重要なマイルストーン完了時)、Claudeは自動で状態を保存**
実際の動作:
セッション開始
↓
Claude: CURRENT_STATUS.md を自動でRead
↓
Claude: 「前回はログイン機能を実装中でした。
次はパスワードリセット機能ですね。続きから始めます」
↓
作業開始
Git連携による状態確認
CURRENT_STATUS.mdに加えて、Gitログも自動で確認します。
# Claudeが自動で実行するコマンド
git log -5 --oneline # 直近5件のコミット
git status # 未コミットの変更
これにより、ファイル更新とコードの実態の両方から状態を把握できます。
長期プロジェクトのベストプラクティス
1. 定期的なCLAUDE.md更新
CLAUDE.mdは「生きたドキュメント」です。定期的に見直しましょう。
| 更新タイミング | 内容 |
|---|---|
| 週次 | よく使う指示をトリガーワードに追加 |
| 月次 | 不要なルールを削除、整理 |
| フェーズ変更時 | プロジェクトの状態を反映 |
2. Skillsの粒度
Skillsは「1ファイル1テーマ」が原則です。
良い例:
.claude/skills/
├── playwright-testing.md ← テスト自動化
├── supabase-troubleshooting.md ← DB関連
└── vercel-deployment.md ← デプロイ
悪い例:
.claude/skills/
└── everything.md ← 全部入り(検索性が悪い)
3. コミットメッセージとの連携
Gitコミットメッセージを充実させることで、CURRENT_STATUS.mdの更新が楽になります。
# 良いコミットメッセージ
git commit -m "feat: ログイン機能を実装
- メール認証対応
- セッション管理をSupabase Authで実装
- テストも作成済み"
Claudeはこのログから作業内容を把握できます。
4. セッション終了時のチェックリスト
セッションを終える前に、以下を確認しましょう。
- 重要な変更をコミット
- CURRENT_STATUS.mdを更新(Claudeが自動更新)
- 次にやることを明記
- 既知の問題があれば記録
5. プロジェクト横断の知見共有
複数プロジェクトで同じSkillsを使い回せます。
my-claude-project/
├── .claude/skills/ ← 全プロジェクト共通
│ ├── playwright-testing.md
│ └── supabase-troubleshooting.md
│
├── Press-Starter/
│ └── CLAUDE.md ← 上のSkillsを参照
│
└── corporate-site-rebranding/
└── CLAUDE.md ← 上のSkillsを参照
メリット:
- Press-Starterで学んだSupabaseの知見が、コーポレートサイトでも使える
- 同じエラーを二度と解決しなくていい
実践例: 合同会社QUESTでの運用
プロジェクト概要
合同会社QUESTでは、複数のプロジェクトを並行開発しています。
| プロジェクト | 概要 | 開発期間 |
|---|---|---|
| Press-Starter | 独自CMS付きプレスリリース配信 | 3ヶ月 |
| コーポレートサイト | 会社サイトリブランディング | 2ヶ月 |
| QUESTBook CRM | 顧客管理システム | 進行中 |
セッション管理の実際
朝の開発スタート
ユーザー: 「プレスタの続きやろう」
↓
Claude: CURRENT_STATUS.md を読み込み
↓
Claude: 「前回はログイン機能を実装中でした。
RLSポリシーの設定が残っているので、続きから始めますね」
↓
Claude: 自動で作業開始
機能実装
ユーザー: 「記事公開予約機能を作って」
↓
Claude: 設計・実装・テスト生成を自動実行
↓
(15分後)
↓
Claude: 「記事公開予約機能を実装しました。
- スケジュール機能(cron)
- Edge Functionsで定期実行
- テストも全てパスしています
デプロイしますか？」
エラー対応
ユーザー: 「本番でエラー出てる」
↓
Claude: Vercel/Supabaseログを自動収集
↓
Claude: 「RLSポリシーの設定ミスでした。
- customers テーブルの SELECT ポリシーが不足
- 修正してデプロイ完了です
この知見を supabase-troubleshooting.md に追記しました」
効率化の成果
セッション管理システムを導入した結果、以下の改善を実現しました。
| 項目 | 改善前 | 改善後 | 削減率 |
|---|---|---|---|
| セッション開始時の説明時間 | 30分 | 5分 | 83%削減 |
| 同じ質問の繰り返し | 週5回 | 月1回 | 80%削減 |
| エラー解決時間 | 平均60分 | 平均15分 | 75%削減 |
| デプロイまでの所要時間 | 2時間 | 30分 | 75%削減 |
特に効果的だった設定
1. 口語体対応
「プレスタ」→ Press-Starter/
「コーポレート」→ corporate-site-rebranding/
プロジェクト名を正確に言わなくても、Claudeが自動で判断してくれます。
2. 自動テスト実行
機能実装完了 → テスト自動生成・実行 → 失敗時は自動修正
「テストして」と言わなくても、自動でテストが実行されます。
3. Skills自動参照
「デプロイして」→ vercel-deployment.md を自動でRead
デプロイ手順を毎回説明する必要がなくなりました。
トラブルシューティング
セッション復元が失敗する場合
原因1: セッションファイルが見つからない
# セッション履歴の場所を確認
ls ~/.claude/projects/
原因2: JSONLファイルが破損
# 最新のセッションファイルを確認
tail ~/.claude/projects/C--Users-tatsu-my-claude-project/*.jsonl
破損している場合は、CURRENT_STATUS.mdとGitログから手動で復元します。
CLAUDE.mdが読み込まれない場合
確認1: ファイル名が正しいか
CLAUDE.md ← 正しい(全て大文字)
claude.md ← 間違い
確認2: プロジェクトルートに配置されているか
my-project/
├── CLAUDE.md ← ここに配置
├── package.json
└── src/
確認3: 文字コードがUTF-8か
file -I CLAUDE.md
# charset=utf-8 であることを確認
Skillsが自動参照されない場合
トリガーワードの確認
CLAUDE.mdでトリガーワードが正しく設定されているか確認します。
| トリガー | 自動参照するSkill |
|---------|------------------|
| 「テスト」 | `playwright-testing.md` |
Skillsのパス確認
.claude/skills/playwright-testing.md ← 正しい
.claude/skill/playwright-testing.md ← 間違い(sが抜けている)
まとめ: 長期プロジェクトを成功させるために
Claude Codeで長期プロジェクトを開発する際の「セッション管理」は、成功の鍵です。
重要なポイント:
- CLAUDE.mdで基本ルールを定義 - 毎回読み込まれる設定ファイル
- Skillsで専門知識を蓄積 - トリガーワードで自動参照
- セッション復元機能を活用 -
claude --resumeで過去に戻れる - CURRENT_STATUS.mdで状態管理 - セッション間の引き継ぎ
- Gitと連携 - コミットログからも状態把握
導入のステップ:
Step 1: CLAUDE.md の基本設定(言語、作業スタイル)
↓
Step 2: よく使う知見をSkillsに追加
↓
Step 3: トリガーワードを設定
↓
Step 4: CURRENT_STATUS.md の自動更新
↓
Step 5: セッション復元の運用開始
最初の1週間は設定に時間がかかりますが、その後は圧倒的に楽になります。
私たちのチームでは、この仕組みにより:
- セッション開始時の説明時間を83%削減
- 同じ質問の繰り返しを80%削減
- エラー解決時間を75%削減
を実現しました。
Claude Codeは強力なツールですが、セッション管理を制する者が、長期プロジェクトを制します。
ぜひ、この記事の内容を参考に、自分専用のセッション管理システムを構築してください。
参考リンク
関連記事
セッション管理と合わせて読むと効果的な記事:
著者: てんちょー(合同会社QUEST 代表)
普段はSIerで経営企画部員として働きながら、週末起業で高校時代の友人と共同創業。Claude Codeを活用した業務効率化・システム開発を得意としています。
🌐 コーポレートサイト: https://llc-quest.com 🐦 Twitter (X): https://x.com/questceo_ai
