Claude CodeのCLAUDE.mdを83%削減してスキルシステムで効率化した話
目次
課題
Claude Codeを使い始めて数ヶ月、CLAUDE.mdファイルは気づけば355行にまで膨れ上がっていた。プロジェクトの詳細な説明、コンテンツ作成ガイドライン、テスト手順、すべてを詰め込んだ結果、肝心なときにClaudeが重要な指示を見落とすようになってしまった。
前回の記事ではCLAUDE.mdの「書き方」を紹介したが、今回はその逆 — 「いかに減らすか」がテーマだ。一見矛盾するようだが、丁寧に書いたCLAUDE.mdが大きくなりすぎると、本来の目的であるAIの精度向上を妨げてしまう。この問題と、その具体的な解決策を共有する。
コンテキストウィンドウの無駄遣い
Claude Codeの最大の制約はコンテキストウィンドウである。すべての会話、読み込んだファイル、コマンド出力がここに蓄積される。そして、LLMのパフォーマンスはコンテキストが満杯になるにつれて低下する。
なぜこれが問題なのか。CLAUDE.mdはClaude Codeが起動するたびに自動的に読み込まれる。つまり、355行のCLAUDE.mdは毎回のセッション開始時に貴重なコンテキストを消費している。会話が長くなるほど、この初期コストの影響は大きくなる。
私のCLAUDE.mdは以下のような内容で埋め尽くされていた：
## Content Writing
### Common Conventions
**Frontmatter:**
- `title` — Specific and outcome-oriented
- `description` — 80–200 chars, conveys unique value
- `date` — YYYY-MM-DD format
- `published` — true/false
- `tags` — lowercase, hyphenated technology names
### Blog Posts (`content/posts/{en,ja}/`)
**Goal:** Concrete, scannable, genuinely useful posts...
[さらに200行以上続く...]このような詳細な指示は一見有用に見えるが、実際には：
- 毎回のセッションで355行がコンテキストを消費
- 重要な指示がノイズに埋もれる
- Claudeが頻繁に指示を無視する
3つ目が最も深刻だった。「Server Componentsをデフォルトにする」という重要なルールが、コンテンツ作成ガイドラインの200行の後に埋もれていると、Claudeはそのルールを見落とすことがある。人間がマニュアルの重要事項を読み飛ばすのと同じ現象だ。
解決策：スキルシステムの導入
Claude Codeのベストプラクティスドキュメントによると、効果的なCLAUDE.mdの条件は：
各行について「これを削除するとClaudeが間違いを犯しますか？」と尋ねます。そうでない場合は、削除します。
そこで、詳細な手順はスキルに移動し、CLAUDE.mdには最小限の情報のみを残すことにした。
スキルとは、Claude Codeの .claude/skills/ ディレクトリに配置するMarkdownファイルで、/skill-name のようにスラッシュコマンドで呼び出せる。CLAUDE.mdが「常に読み込まれる設定ファイル」なのに対し、スキルは「必要なときだけ呼び出される手順書」だ。この違いが、コンテキスト効率に決定的な差を生む。
実装したスキル構造
.claude/skills/
├── post-guide/ # ブログ記事ライティングガイド＆作成
├── fix-lint/ # Lintエラーの自動修正
├── sync-i18n/ # 多言語コンテンツの同期チェック
├── debug-build/ # ビルドエラーのトラブルシューティング
├── run-tests/ # 変更に応じた適切なテスト実行
├── add-mdx-component/# MDXコンポーネントの追加
└── README.md # スキルのドキュメント
各スキルは独立したディレクトリに格納され、SKILL.md というファイルに手順を記述する。ディレクトリ名がそのままコマンド名になるため、post-guide/ ディレクトリなら /post-guide で呼び出せる。
スキルの例：/post-guide
---
name: post-guide
description: Blog post writing guidelines and creation workflow. Loaded when creating, editing, or reviewing blog posts in content/posts/.
---
Blog post writing guide: $ARGUMENTS
## Writing Principles
These principles apply to both new and existing blog posts.
### Title (Principle 1)
- Include the technology name
- Lead with the outcome, not the topic
[ライティング原則が続く...]
## New Post Creation Workflow
When explicitly invoked with `/post-guide`, follow these steps to create a new post.
1. **Determine post basics**
- Date format: YYYY-MM-DD
- Slug: kebab-case (lowercase with hyphens)
[作成手順が続く...]この例では disable-model-invocation を設定していない。そのため、Claude Codeが「ブログ記事の編集に関連する」と判断したときにライティング原則（Writing Principles）が自動的にロードされる。記事の新規作成時には /post-guide nextjs-performance-tips のように明示的に呼び出すことで、作成ワークフロー（New Post Creation Workflow）も含めて実行される。
この構造のポイントは、ガイダンス部分をファイルの先頭に配置していることだ。段階的開示の第2段階でSKILL.md本文がロードされたとき、先頭のライティング原則がまず目に入る。作成ワークフローは末尾に配置することで、自動ロード時には「知識」として、明示呼び出し時には「手順」として機能する。
一方、/fix-lint のようにファイル変更やビルド実行など副作用のみを含むスキルには disable-model-invocation: true を設定して、明示的な呼び出し時のみ実行されるようにすべきだ。
$ARGUMENTS はユーザーがコマンドの後に入力したテキストがそのまま展開されるプレースホルダーだ。/post-guide nextjs-performance-tips と入力すると、$ARGUMENTS が nextjs-performance-tips に置き換わり、Claudeがその内容をもとに手順を実行する。
結果：59行の簡潔なCLAUDE.md
最適化後のCLAUDE.mdは、わずか59行になった。残っているのは「Claudeが毎回知っておくべき情報」だけだ。コマンド一覧、スキルへの参照、そしてプロジェクト固有の制約。詳細な手順はすべてスキルに移動し、必要なときだけ読み込まれる：
# CLAUDE.md
**Language rule:** Think in English internally.
Always respond to the user in Japanese.
## Commands
npm run dev # Dev server
npm run build # Production build
npm test # Unit tests
[...]
## Skills
Use `/skill-name` for common tasks:
- `/post-guide` — Blog post writing guide
- `/fix-lint` — Fix linting errors
- `/sync-i18n` — Check bilingual content
[...]
## Critical Rules
- Server Components by default
- TypeScript strict mode
- Tailwind only
- Build must pass
[...]効果：劇的な改善
この最適化により、以下の改善を実現した。最も重要なのは、単に行数が減っただけでなく、Claudeの応答品質が目に見えて向上したことだ。
1. コンテキスト効率の向上
- 355行 → 59行（83%削減）
- 重要な指示が埋もれない
- より長いセッションが可能に
2. ワークフローの標準化
/post-guideでブログ記事作成が一瞬/fix-lintでLintエラーを自動修正- チーム全体で同じワークフローを共有
3. メンテナンス性の向上
- スキルごとに独立して更新可能
- ローカルスキル（
.local/）で個人設定も可能 - Gitでバージョン管理
ベストプラクティスのチェックリスト
CLAUDE.mdに何を残し、何をスキルに移すかの判断は、最初は難しく感じるかもしれない。以下の表は、私が実際に使った判断基準だ。根底にある原則は「Claudeがコードを読めば分かることは書かない」ということ：
| ✅ 含める | ❌ 除外する |
|---|---|
| Claudeが推測できないコマンド | Claudeがコードを読んで理解できること |
| デフォルトと異なるコードスタイル | 標準的な言語規約 |
| プロジェクト固有の設定 | 詳細なAPIドキュメント |
| 重要な制約やルール | 一般的なベストプラクティス |
具体的な削除例
理論だけでは判断しにくいので、実際に移動した内容とその理由を示す。共通しているのは、いずれも「手順の詳細」であり「ルール」ではないという点だ。テスト手順が50行あっても、「テストを通すこと」というルールは1行で済む：
| Before（CLAUDE.md内） | After（スキルへ） |
|---|---|
| テスト手順の詳細（50行） | /run-testsスキル |
| コンテンツ作成ガイド（80行） | /post-guideスキル |
| デバッグ手順（40行） | /debug-buildスキル |
| MDXコンポーネント追加手順（30行） | /add-mdx-componentスキル |
実際の使い方
スキルの呼び出しは非常にシンプルだ。Claude Codeの会話中に /スキル名 と入力するだけで、該当するSKILL.mdが読み込まれ、Claudeがその手順に従って作業を開始する。引数を渡すことも可能で、/post-guide nextjs-performance-tips のように具体的な指示を追加できる。
スキルの実行例
# 新しいブログ記事を作成
/post-guide nextjs-performance-tips
# Lintエラーを自動修正
/fix-lint
# ビルドエラーをデバッグ
/debug-build
# 日英コンテンツの同期を確認
/sync-i18nスキルにすべき作業の判断基準
スキルを作りすぎても管理が煩雑になる。逆に少なすぎるとCLAUDE.mdが膨れる。以下の基準で、スキル化すべき作業かどうかを判断している：
✅ スキルにすべき：
- 3回以上繰り返す作業
- 手順が5ステップ以上ある作業
- チームで共有したいワークフロー
- エラーが起きやすい複雑な手順
❌ CLAUDE.mdに残すべき：
- プロジェクト固有の制約
- 常に適用されるルール
- 基本的なコマンド一覧
- Claudeが推測できない設定
実装のヒント
自分のプロジェクトでスキルシステムを導入する際の手順を紹介する。大掛かりな移行ではなく、段階的に進めるのがコツだ。
1. まずは測定から
現在のCLAUDE.mdの行数を確認する。100行を超えていたら最適化の余地が大きい。50行以下なら、現時点では十分かもしれない：
wc -l CLAUDE.md # 現在の行数を確認2. スキルの作成
ディレクトリを作り、SKILL.mdを配置するだけで完了する。複雑な設定は不要だ：
mkdir -p .claude/skills/your-skill
cat > .claude/skills/your-skill/SKILL.md << 'EOF'
---
name: your-skill
description: What this skill does
disable-model-invocation: true # 副作用がある場合
---
Your workflow steps here...
EOF3. .gitignoreの設定
チームで共有するスキルはGitにコミットするが、個人用のカスタマイズは.local/サフィックスで管理し、.gitignoreに追加する。これにより、チーム標準のスキルを維持しつつ、個人の好みも反映できる：
echo ".claude/skills/*.local/" >> .gitignore
echo "CLAUDE.local.md" >> .gitignoreよくある問題と解決策
スキルシステムの導入で遭遇しやすい問題と、その対処法をまとめた。いずれも私が実際に経験したものだ。
Q: スキルが認識されない
A: スキル名がディレクトリ名と一致しているか確認すること。name: フィールドが正しく設定されているか確認すること。
Q: disable-model-invocationの判断が難しい
A: ファイル変更、ビルド実行、テスト実行など「副作用」がある場合はtrueに設定する。読み取り専用の場合は不要である。
Q: CLAUDE.mdがまだ長く感じる
A: 「これを削除してもClaudeは正しく動作するか？」を基準に、さらに削減を検討すること。50行以下が理想である。
補足：スキルとスラッシュコマンドの違い
本記事では .claude/skills/ に配置するファイルを一括して「スキル」と呼んでいるが、Claude Codeにはスラッシュコマンド（.claude/commands/）とスキル（.claude/skills/）という2つの仕組みがあり、設計思想が異なる。『実践Claude Code入門』（技術評論社）では、この区別を以下のように整理している。
| 特性 | スラッシュコマンド | スキル |
|---|---|---|
| 配置先 | .claude/commands/*.md | .claude/skills/*/SKILL.md |
| 呼び出し | ユーザーが /command で明示的に実行 | Claude Codeが関連性を判断し自動ロード |
| 有効範囲 | コマンド実行中のみ | セッション全体 |
| 目的 | ワークフローの定義（何を、どの順番で） | ツールの使い方・考え方を教える |
| ファイル構成 | 単一の.mdファイル | ディレクトリ構造（補助ファイル含む） |
/fix-lint のように disable-model-invocation: true を設定して明示的に呼び出すスキルは、書籍の分類では「スラッシュコマンド」の役割に近い。一方、/post-guide のように disable-model-invocation を設定せず、記事の編集時にライティング原則が自動ロードされるスキルは、スキル本来の使い方だ。この自動ロードを支えるのが**段階的開示（progressive disclosure）**である。
段階的開示の仕組み
CLAUDE.mdは毎セッション全文がコンテキストウィンドウに読み込まれる。59行でも数百トークンを消費し、スキルに移す前の355行なら数千トークンだった。一方、スキルは以下の3段階で必要な分だけ読み込まれる。
第1段階：メタデータのみ（約100トークン/スキル）
Claude Codeはセッション開始時に、すべてのスキルの name と description だけを読み込む。この情報をもとに、現在のタスクに関連するスキルがどれかを判断する。
# この部分だけが最初に読まれる
---
name: typescript-conventions
description: TypeScriptのコーディング規約。型定義、命名規則、エラーハンドリングのパターンを定義
---つまり、description の書き方がスキルの有効性を左右する。「TypeScriptのコードを書く」というタスクに対して、上記の description なら関連ありと判断される。逆に description が曖昧だと、関連するタスクでもスキルがロードされない。
第2段階：SKILL.md本文のロード（5,000トークン未満）
関連ありと判断されたスキルのみ、SKILL.md の本文が読み込まれる。10個のスキルがあっても、TypeScriptの作業中にロードされるのはTypeScript関連の1〜2個だけだ。残りの8個は第1段階のメタデータ（計800トークン程度）しか消費しない。
第3段階：補助ファイル群のロード（必要な場合のみ）
スキルはディレクトリ構造を持てるため、SKILL.md から参照される補助ファイル（テンプレート、コード例、詳細なガイドなど）を含められる。これらは SKILL.md の指示に基づいて必要時にだけ追加ロードされる。
.claude/skills/typescript-conventions/
├── SKILL.md # 第2段階でロード
├── guides/
│ ├── naming.md # 命名規則の詳細（必要時のみ）
│ └── error-handling.md # エラーパターン集（必要時のみ）
└── examples/
└── patterns.ts # コード例（必要時のみ）
CLAUDE.mdとのコンテキスト消費の比較
この段階的開示がなぜ重要かを、具体的なトークン消費で比較する。
仮に、TypeScript規約（500トークン）、React規約（400トークン）、テスト規約（600トークン）、セキュリティ規約（300トークン）の4つのルールセットがあるとする。
CLAUDE.mdに全部書いた場合： 毎セッション 1,800トークンを常に消費。TypeScriptだけ書いている時間もReact・テスト・セキュリティの規約が読み込まれ続ける。
スキルに分離した場合： メタデータのみで 400トークン（100×4）。TypeScriptを書いているときは追加で500トークンだけロード。合計900トークンで、50%のコンテキスト節約になる。作業内容が切り替われば、ロードされるスキルも自動的に切り替わる。
ガイダンス型スキルの設計指針
段階的開示を活かすには、ガイダンス型スキルを適切に設計する必要がある。
description を具体的に書く： Claude Codeが第1段階で関連性を判断する唯一の手がかりが description だ。「コーディング規約」のような抽象的な説明ではなく、「TypeScriptのコーディング規約。型定義、命名規則、エラーハンドリングのパターンを定義」のように、どの作業に関連するかが明確にわかる説明を書く。
SKILL.md本文は5,000トークン未満に収める： 第2段階でロードされる本文が大きすぎると、段階的開示の意味が薄れる。詳細は補助ファイルに分離し、SKILL.md には要約と参照先を書く。
スコープを絞る： 1つのスキルに複数の関心事を詰め込むと、無関係な作業でもロードされてしまう。「TypeScript規約」と「React規約」は別スキルにする方が、必要なときに必要なものだけがロードされる。
ワークフロー型とガイダンス型の使い分け
本プロジェクトでは .claude/skills/ に統一して配置しているが、用途に応じた使い分けを意識すると設計が明確になる：
- ワークフロー型（
/fix-lint、/debug-build等）：disable-model-invocation: trueを設定し、明示的に呼び出す。スラッシュコマンドに近い使い方 - ガイダンス型（コーディング規約、アーキテクチャルール等）：
disable-model-invocationを設定せず、Claude Codeが作業内容に応じて自動的にロード。スキル本来の使い方
disable-model-invocation: true を設定しているかどうかが、実質的にこの2つの役割を分ける境界線になっている。
まとめ
- 「常に読み込まれるルール」と「必要時だけ呼び出す手順」を分離する — CLAUDE.mdには制約とコマンドだけを残し、ステップバイステップの手順はスキルに移す。この分離がコンテキスト効率の鍵だ。
disable-model-invocation: trueで副作用を制御する — ファイル変更やビルド実行を含むスキルには必ず設定する。設定しないと、Claudeが文脈から判断して勝手にファイルを作成する。- ワークフロー型とガイダンス型を意識して設計する — 明示的に呼び出す手順書と、Claude Codeが自動ロードする知識ベースでは、設計方針が異なる。
disable-model-invocationの有無がこの境界線だ。 - 50行以下を目指す — 「これを削除してもClaudeは正しく動作するか？」を各行に問う。残った行だけがCLAUDE.mdに値する。
もしあなたのCLAUDE.mdが100行を超えているなら、今すぐスキルシステムへの移行を検討してほしい。その効果は劇的だ。
次のステップ
この最適化プロセスをさらに自動化し、継続的に改善したい方は、メタスキルを使った自己改善サイクルの構築も参照してほしい。
シリーズ記事：
