Claude Codeの「Compacting Conversation」を体感50%減！ CLAUDE.md + 8 Skills で挑むコンテキスト管理術

2025/12/17 AI駆動開発勉強会 沖縄支部 第3回の発表内容です

Transcript

1. Claude Codeの「Compacting Conversation」を体感50%減！ CLAUDE.md + 8 Skills で挑むコンテキスト管理術 村濱 一樹 / Scalebase株式会社 VPoE 1
2. 自己紹介 村濱 一樹 (@muraaaaa_san) Scalebase株式会社 執行役員 VPoE Claude Code / Devin / ChatGPT を組織に展開推進中 今日話すこと: Claude Codeのコンテキスト管理で試行錯誤した話 2
3. 今日のゴール Claude Codeを使っていて感じる 「Compacting conversation...」の絶望 を減らすための 実践的なアプローチを共有する 3
4. 目次 1. 課題: Compacting Conversationとは何か 2. 試行錯誤: 3つの失敗パターン 3. 解決策: CLAUDE.md + 8 Skills アーキテクチャ 4. 実践: 具体的なファイル構成 5. Tips: プランニングセッションの分離 6. 結果と学び 4
5. Part 1 課題: Compacting Conversationとは 5
6. Claude Codeを使っていると... Compacting conversation... この表示が出た瞬間の 絶望感 数十秒〜数分の待ち時間 思考の中断 コンテキストが失われる不安 6
7. なぜ Compacting が発生するのか Claude Codeには コンテキストウィンドウの制限 がある 会話が長くなると... 1. 古い会話を圧縮して要約 2. 重要な情報が失われるリスク 3. 再度説明が必要になることも → できるだけ発生を減らしたい 7
8. コンテキストを食う要因 要因 影響度 長い会話履歴 大 大きな設定ファイル（CLAUDE.md等） 大 コードの読み込み 中 プランニング・思考過程 中 設定ファイルの肥大化 が意外と効いている 8
9. Part 2 試行錯誤: 3つの失敗パターン 9
10. Phase 1: 1ファイルに全部集約 発想 「必要な情報を全部 CLAUDE.md に書けば最強では？」 やったこと プロジェクト構成、コーディング規約、API仕様... 全てを1つの CLAUDE.md に集約 10
11. Phase 1: 結果 最初は良かった Claudeが文脈を理解してくれる 指示の一貫性が保たれる しかし育てていくうちに... 情報を充足させるほど 肥大化 1ファイルが数千行に 毎回のリクエストでコンテキストを圧迫 Compacting頻発 11
12. Phase 2: 階層構造で分割 発想 「必要な時だけ参照させればいいのでは？」 やったこと .claude/ ├── CLAUDE.md ├── architecture/ │ └── overview.md, api.md... ├── guidelines/ │ └── coding.md, testing.md └── ... 12
13. Phase 2: 結果 期待 「タスクに応じて必要なファイルだけ読んでくれるはず」 現実 3階層目を読んでくれない 当時は「このファイルを読んで」も効かなかった ハルシネーションで適当に答える 階層を深くしても自動で辿ってくれない 13
14. Phase 3: 1階層にまとめる（揺り戻し） 発想 「階層が深いから辿ってくれない」 やったこと @ファイル名 で全参照 階層をフラットに 結果 最初から全部読み込まれる コンテキスト圧迫 Phase 1 と同じ問題 14
15. 3つの失敗から学んだこと アプローチ 問題 1ファイル集約 肥大化でCompacting頻発 階層構造 3階層目を読んでくれない 1階層にまとめ 全部読み込み→Phase1に戻る 必要なのは「適切な粒度」と「読ませる仕組み」 15
16. Part 3 解決策: CLAUDE.md + 8 Skills 16
17. CLAUDE.md + Skills とは Claude Codeの公式機能を活用したアーキテクチャ .claude/ ├── skills/ # タスク別の小さな設定 │ ├── api-development/ │ ├── ui-development/ │ ├── unit-test/ │ └── ... └── settings.json CLAUDE.md # エントリーポイント（軽量） 17
18. なぜ Skills なのか？ - CLAUDE.md と の違い 観点 CLAUDE.md Skills 読み込み セッション開始時に常に全部 タスクに応じて必要なものだけ 判断主体 自動（階層を辿って全読み込み） Claudeがdescriptionを見て判 断 コンテキス ト 毎回フルで消費 オンデマンドで最小限 18
19. 読み込みの違い（図解） CLAUDE.md の場合 セッション開始 ↓ 全部読み込み（1000行でも） ↓ 毎回コンテキスト圧迫 Skills の場合 セッション開始 ↓ description だけスキャン ↓ 該当Skillだけ読む 19
20. これが Compacting 50%減の本質 Before: 「常に全部読む」 CLAUDE.md に全情報 → 毎回1000行読み込み After: 「必要な時に必要なものだけ」 CLAUDE.md（軽量）+ 該当Skillだけ読み込み API実装時: CLAUDE.md + api-development (計200行程度) コンテキストの節約 = Compacting の抑制 20
21. Skills の特徴 Claude Code が「タスクに応じて自動で読み込む」 skill: キーワードで明示的に呼び出せる 各Skillは 単一責任 で小さく保つ 必要な時だけコンテキストに載る → 常に全部読み込む必要がない 21
22. 我々の 8 Skills 構成 Skill 役割 api-development API実装, tRPC database-migration Prisma, マイグレ ui-development UI, スタイリング unit-test Vitestテスト Skill 役割 e2e-test Playwright github-workflow PR/Issue lint-rules コードスタイル event-driven SNS/SQS 22
23. CLAUDE.md の役割 軽量なエントリーポイント として機能 # Repository Guidelines ## Essential Documentation Before starting any task, refer to appropriate skills: | Task | Skill | |------|-------| | API implementation | `api-development` | | UI components | `ui-development` | | Unit tests | `unit-test` | Skillへの参照テーブルだけを持つ 23
24. CLAUDE.md に書くこと 1. Skillへの参照テーブル（タスク→Skill対応） 2. プロジェクト構成の概要（最小限） 3. 共通ルール（言語設定、優先順位など） 4. 開発コマンド一覧 詳細は全てSkillに委譲 24
25. Skill ファイルの例 # API Development Skill ## Overview tRPC + Prisma でのAPI実装ガイド ## File Structure - `packages/api/src/api/*/index.ts` - APIルート - `packages/ctx-*/src/usecase/*.rsc.ts` - ユースケース ## Patterns - RORO pattern (Receive Object, Return Object) - Error handling with Result type そのタスクに必要な情報だけ 25
26. Part 4 実践: 具体的なファイル構成 26
27. ディレクトリ構成 project-root/ ├── CLAUDE.md # 軽量エントリ └── .claude/ ├── skills/ # 8つのSkill │ ├── api-development/ │ ├── ui-development/ │ └── ... └── settings.json ポイント CLAUDE.md はルート直下 各Skill は独立したフォルダ SKILL.md に詳細を記載 27
28. 各ファイルのサイズ目安 ファイル 行数目安 役割 CLAUDE.md 100-200行 軽量エントリーポイント 各 SKILL.md 50-150行 タスク特化の詳細 以前の1ファイル: 1000行超 → 分散後: 各100行程度 28
29. Skill の呼び出し方 自動呼び出し Claude Codeがタスク内容から判断して読み込む 明示的呼び出し skill: api-development を参照して実装して CLAUDE.md での誘導 テーブルで「このタスクにはこのSkill」と明示 29
30. 実践: カスタムコマンド × Skills カスタムコマンドで Skill を呼び出す # .claude/commands/api-impl.md skill: api-development を参照して、以下の仕様でAPIを実装して: 使い方 /api-impl ユーザー一覧取得API Skill読み込み + 具体的な作業指示 を1コマンドで 30
31. なぜこの組み合わせが効くのか 機能 役割 Skills 知識・ルールの格納（自動読み込み） カスタムコマンド Skill呼び出し + 作業指示のショートカット メリット Skillの自動発見に頼らず 確実に読み込ませる 毎回 skill: xxx と書く手間を省略 チームで使い方を 標準化 できる 31
32. Part 5 Tips: プランニングセッションの分離 32
33. もう一つの重要なポイント プランニング（設計・計画）と実装を分離する 問題 設計の議論で会話が長くなる 「こうしたい」 「いや、こっちが良い」のやり取り 実装前にコンテキストが枯渇 33
34. 解決策: Issue への出力 プランニングセッション 1. Claude Codeで設計を議論 2. 結論を GitHub Issue に出力 3. 会話をリセット 実装セッション 1. 新しい会話で Issue を参照 2. 「Issue #123 を実装して」 3. クリーンなコンテキストで作業開始 34
35. なぜ効果があるのか Before After 設計の思考過程がコンテキストに残る Issueに集約、会話は軽量 実装時に過去の議論も読み込む 必要な結論だけ参照 Compacting で設計意図が消える Issue は消えない 思考と作業の分離 35
36. github-workflow Skill # GitHub Workflow Skill ## Issue Creation - 設計結果は Issue として出力 - テンプレート: 背景、ゴール、実装方針、タスク分解 ## PR Creation - Issue への紐付け必須 - 変更内容のサマリを記載 Skill として Issue 作成のルールも定義 36
37. Part 6 結果と学び 37
38. 実際の効果 定量的 Compacting 発生頻度: 体感 50% 減 1セッションで扱えるタスク量が増加 定性的 長時間の連続コーディングが可能に 「また Compacting か...」のストレス軽減 コンテキスト消失への不安が減少 38
39. 完璧ではない 残る課題 Skill を読んでくれないことがある 明示的に skill: xxx と指示が必要な場面も Skill 間の依存関係の管理 それでも 以前より 明らかに快適 コンテキスト管理の 見通しが良くなった 39
40. 学んだこと 1. 適切な粒度 「1タスク = 1 Skill」が目安 2. 読ませる仕組み Skills機能 + CLAUDE.mdで誘導 3. 思考と作業の分離 プランニング → Issue出力 実装 → 新セッションで 40
41. まとめ Compacting Conversation を減らすには 1. CLAUDE.md + Skills でコンテキストをモジュール化 軽量なエントリーポイント タスク特化の小さなSkill 2. プランニングと実装を分離 設計は Issue に出力 クリーンなコンテキストで実装 41
42. 構成のポイント（再掲） CLAUDE.md (100-200行) └── 参照テーブルで Skill に誘導 .claude/skills/ ├── api-development/SKILL.md ├── ui-development/SKILL.md ├── unit-test/SKILL.md └── ... (タスク別に分割) 「全部入り」から「必要な時に必要なものだけ」へ 42
43. ありがとうございました Q&A 村濱 一樹 / @k_murahama Scalebase株式会社 VPoE 43
44. Appendix: 実際の CLAUDE.md（抜 粋） # Repository Guidelines ## Essential Documentation | Task | Skill | |------|-------| | API implementation | `api-development` | | Prisma migrations | `database-migration` | | UI components | `ui-development` | | Unit tests | `unit-test` | ## Language Rule (strict) - User-facing: 日本語 - Skills files: English 176行 - Skillへの誘導 + 共通ルールのみ 44
45. Appendix: 実際の Skill 例（api- development） --- name: api-development description: API implementation, tRPC, usecase, error handling --- ## Data Flow UI -> tRPC -> usecase -> Prisma 主な内容: neverthrow Result type Guard clauses TanStack Form + Zod 349行 - API実装を網羅 45
46. Appendix: 実際の Skill 例（ui- development） --- name: ui-development description: UI components, Tailwind/Shadcn, data fetching --- 主な内容: データフェッチ4パターン useEffect判断フロー a11y要件 665行 46
47. Appendix: 実際の Skill 例（github- workflow） --- name: github-workflow description: PR creation, issue creation, commits --- 主な内容: PR必須セクション DBマイグレ戦略 Issue テンプレート 242行 47
48. Appendix: Skill のサイズ感 Skill 行数 ui-development 665 e2e-test 581 database-migration 479 event-driven 406 Skill 行数 api-development 349 lint-rules 321 github-workflow 242 unit-test 229 合計 3,272行 → タスクに応じて 必要な分だけ 読み込み 48