Share
Embed
Claude Codeの「Compacting Conversation」を体感50%減! CLAUDE.md + 8 Skills で挑むコンテキスト管理術
2025/12/17 AI駆動開発勉強会 沖縄支部 第3回の発表内容です
Kazuki Murahama
December 16, 2025
Transcript
48 slides
-
Claude Codeの「Compacting Conversation」を体感50%減! CLAUDE.md + 8 Skills で挑むコンテキスト管理術 村濱 一樹
/ Scalebase株式会社 VPoE 1 -
自己紹介 村濱 一樹 (@muraaaaa_san) Scalebase株式会社 執行役員 VPoE Claude Code /
Devin / ChatGPT を組織に展開推進中 今日話すこと: Claude Codeのコンテキスト管理で試行錯誤した話 2 -
目次 1. 課題: Compacting Conversationとは何か 2. 試行錯誤: 3つの失敗パターン 3. 解決策:
CLAUDE.md + 8 Skills アーキテクチャ 4. 実践: 具体的なファイル構成 5. Tips: プランニングセッションの分離 6. 結果と学び 4 -
なぜ Compacting が発生するのか Claude Codeには コンテキストウィンドウの制限 がある 会話が長くなると... 1. 古い会話を圧縮して要約
2. 重要な情報が失われるリスク 3. 再度説明が必要になることも → できるだけ発生を減らしたい 7 -
コンテキストを食う要因 要因 影響度 長い会話履歴 大 大きな設定ファイル(CLAUDE.md等) 大 コードの読み込み 中 プランニング・思考過程
中 設定ファイルの肥大化 が意外と効いている 8 -
Phase 1: 結果 最初は良かった Claudeが文脈を理解してくれる 指示の一貫性が保たれる しかし育てていくうちに... 情報を充足させるほど 肥大化 1ファイルが数千行に
毎回のリクエストでコンテキストを圧迫 Compacting頻発 11 -
Phase 2: 階層構造で分割 発想 「必要な時だけ参照させればいいのでは?」 やったこと .claude/ ├── CLAUDE.md ├──
architecture/ │ └── overview.md, api.md... ├── guidelines/ │ └── coding.md, testing.md └── ... 12 -
Phase 3: 1階層にまとめる(揺り戻し) 発想 「階層が深いから辿ってくれない」 やったこと @ファイル名 で全参照 階層をフラットに 結果
最初から全部読み込まれる コンテキスト圧迫 Phase 1 と同じ問題 14 -
CLAUDE.md + Skills とは Claude Codeの公式機能を活用したアーキテクチャ .claude/ ├── skills/ #
タスク別の小さな設定 │ ├── api-development/ │ ├── ui-development/ │ ├── unit-test/ │ └── ... └── settings.json CLAUDE.md # エントリーポイント(軽量) 17 -
なぜ Skills なのか? - CLAUDE.md と の違い 観点 CLAUDE.md Skills
読み込み セッション開始時に常に全部 タスクに応じて必要なものだけ 判断主体 自動(階層を辿って全読み込み) Claudeがdescriptionを見て判 断 コンテキス ト 毎回フルで消費 オンデマンドで最小限 18 -
読み込みの違い(図解) CLAUDE.md の場合 セッション開始 ↓ 全部読み込み(1000行でも) ↓ 毎回コンテキスト圧迫 Skills の場合
セッション開始 ↓ description だけスキャン ↓ 該当Skillだけ読む 19 -
これが Compacting 50%減の本質 Before: 「常に全部読む」 CLAUDE.md に全情報 → 毎回1000行読み込み After:
「必要な時に必要なものだけ」 CLAUDE.md(軽量)+ 該当Skillだけ読み込み API実装時: CLAUDE.md + api-development (計200行程度) コンテキストの節約 = Compacting の抑制 20 -
Skills の特徴 Claude Code が「タスクに応じて自動で読み込む」 skill: キーワードで明示的に呼び出せる 各Skillは 単一責任 で小さく保つ
必要な時だけコンテキストに載る → 常に全部読み込む必要がない 21 -
我々の 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 -
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 -
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 -
ディレクトリ構成 project-root/ ├── CLAUDE.md # 軽量エントリ └── .claude/ ├── skills/
# 8つのSkill │ ├── api-development/ │ ├── ui-development/ │ └── ... └── settings.json ポイント CLAUDE.md はルート直下 各Skill は独立したフォルダ SKILL.md に詳細を記載 27 -
各ファイルのサイズ目安 ファイル 行数目安 役割 CLAUDE.md 100-200行 軽量エントリーポイント 各 SKILL.md 50-150行
タスク特化の詳細 以前の1ファイル: 1000行超 → 分散後: 各100行程度 28 -
Skill の呼び出し方 自動呼び出し Claude Codeがタスク内容から判断して読み込む 明示的呼び出し skill: api-development を参照して実装して CLAUDE.md
での誘導 テーブルで「このタスクにはこのSkill」と明示 29 -
実践: カスタムコマンド × Skills カスタムコマンドで Skill を呼び出す # .claude/commands/api-impl.md skill:
api-development を参照して、以下の仕様でAPIを実装して: 使い方 /api-impl ユーザー一覧取得API Skill読み込み + 具体的な作業指示 を1コマンドで 30 -
なぜこの組み合わせが効くのか 機能 役割 Skills 知識・ルールの格納(自動読み込み) カスタムコマンド Skill呼び出し + 作業指示のショートカット メリット
Skillの自動発見に頼らず 確実に読み込ませる 毎回 skill: xxx と書く手間を省略 チームで使い方を 標準化 できる 31 -
解決策: Issue への出力 プランニングセッション 1. Claude Codeで設計を議論 2. 結論を GitHub
Issue に出力 3. 会話をリセット 実装セッション 1. 新しい会話で Issue を参照 2. 「Issue #123 を実装して」 3. クリーンなコンテキストで作業開始 34 -
github-workflow Skill # GitHub Workflow Skill ## Issue Creation -
設計結果は Issue として出力 - テンプレート: 背景、ゴール、実装方針、タスク分解 ## PR Creation - Issue への紐付け必須 - 変更内容のサマリを記載 Skill として Issue 作成のルールも定義 36 -
実際の効果 定量的 Compacting 発生頻度: 体感 50% 減 1セッションで扱えるタスク量が増加 定性的 長時間の連続コーディングが可能に
「また Compacting か...」のストレス軽減 コンテキスト消失への不安が減少 38 -
完璧ではない 残る課題 Skill を読んでくれないことがある 明示的に skill: xxx と指示が必要な場面も Skill 間の依存関係の管理
それでも 以前より 明らかに快適 コンテキスト管理の 見通しが良くなった 39 -
学んだこと 1. 適切な粒度 「1タスク = 1 Skill」が目安 2. 読ませる仕組み Skills機能
+ CLAUDE.mdで誘導 3. 思考と作業の分離 プランニング → Issue出力 実装 → 新セッションで 40 -
まとめ Compacting Conversation を減らすには 1. CLAUDE.md + Skills でコンテキストをモジュール化 軽量なエントリーポイント
タスク特化の小さなSkill 2. プランニングと実装を分離 設計は Issue に出力 クリーンなコンテキストで実装 41 -
構成のポイント(再掲) CLAUDE.md (100-200行) └── 参照テーブルで Skill に誘導 .claude/skills/ ├── api-development/SKILL.md
├── ui-development/SKILL.md ├── unit-test/SKILL.md └── ... (タスク別に分割) 「全部入り」から「必要な時に必要なものだけ」へ 42 -
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 -
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 -
Appendix: 実際の Skill 例(ui- development) --- name: ui-development description: UI
components, Tailwind/Shadcn, data fetching --- 主な内容: データフェッチ4パターン useEffect判断フロー a11y要件 665行 46 -
Appendix: 実際の Skill 例(github- workflow) --- name: github-workflow description: PR
creation, issue creation, commits --- 主な内容: PR必須セクション DBマイグレ戦略 Issue テンプレート 242行 47 -
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