Claude Codeが遅い？毎回検索をやめて実行速度を劇的改善

はじめに

ども！Claude CodeのSkillとAgentにナレッジを詰め込んで依存しまくっている龍ちゃんです。

Skills/Agentsを自作し始めると、こんな経験ありませんか？

• サブエージェントの実行時間がやたら長い
• 同じような検索が何度も実行されている
• 並列実行したらすぐにレート制限に引っかかる

私も雑に作ったらトークン数や実行時間が爆増したので、Anthropicの公式ベストプラクティスを参考に改善しました。今回は、その改善内容を紹介します。

ポイント: 何度も参照する情報は、静的ファイルとして保存する。これだけで、トークン節約・高速化・結果の安定化が実現できます。

関連記事

失敗談：subagentで毎回Web検索していた

私の失敗例を紹介します。Taskツールで呼び出すsubagentに「ベストプラクティスに従って実装して」という指示を組み込んでいました。

# 私が書いていたAgent定義（悪い例）

## 実装手順
1. まずベストプラクティスを検索する
   - WebSearch("Claude Code best practices 2026")
   - WebSearch("Python project structure best practices")
2. 検索結果を参考に実装を進める

一見合理的に見えますが、毎回同じ検索が実行されるという問題がありました。

• 実行のたびにWeb検索が走る
• トークンを大量消費（検索結果の読み込み）
• 実行時間が長くなる
• 並列実行でレート制限に到達
• しかも検索結果は毎回ほぼ同じ

変わらない情報を毎回動的に取得している。これが問題の本質でした。

結論：静的情報として保存する

解決策はシンプルです。

何度も参照する情報は、ファイルとして保存しておく。

# 改善後のAgent定義（良い例）

## 実装手順
1. ベストプラクティスを確認する
   - Read("docs/references/claude-code-best-practices.md")
   - Read("docs/references/python-project-structure.md")
2. 参照情報に従って実装を進める

Web検索からファイル読み込みに変えるだけで、以下の効果が得られます。

なぜ有効なのか

Anthropicの公式ベストプラクティスでは、コンテキストウィンドウの管理が最重要とされています。

“Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.”

（ほとんどのベストプラクティスは、1つの制約に基づいています。Claudeのコンテキストウィンドウはすぐに埋まり、埋まるとパフォーマンスが低下します）

静的情報活用が効果的な理由は3つです。

1. コンテキストウィンドウの節約

• Web検索結果は予測不能なサイズになりがち
• 静的ファイルならサイズをコントロール可能
• 公式データ：コンテキスト編集で29%パフォーマンス向上

2. Just-in-Time読み込みとの相性

Claude Codeは「必要なときに取得」するJust-in-Timeパターンを採用しています。

• CLAUDE.mdは起動時にロード
• それ以外の情報はオンデマンドでロード
• 軽量な識別子（ファイルパス）を保持しておけばよい

3. 情報の一貫性と更新容易性

• 静的ファイルなら結果が毎回同じ
• 情報が古くなってもファイル更新のみで対応
• Agent/Skillsの定義変更が不要

実践パターン

静的情報の活用には、大きく2つのパターンがあります。

パターン1：Skills内のProgressive Disclosure（個別利用）

Claude Code SkillsではProgressive Disclosure（段階的開示）という設計原則が推奨されています。

3層構造:

公式ドキュメントでは、この仕組みについて以下のように説明されています。

“Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed.”

“The amount of context that can be bundled into a skill is effectively unbounded.”

（Skillにバンドルできるコンテキスト量は事実上無制限です）

数十のリファレンスファイルがあっても、タスクに必要な1ファイルだけをロードし、不要なファイルは読み込まないため残りはトークン消費ゼロです。

ディレクトリ構造例:

skill-name/
├── SKILL.md           # コア指示（500行以下に抑える）
└── references/
    ├── advanced.md        # 高度なテクニック
    ├── examples.md        # 具体例集
    └── troubleshooting.md # トラブルシューティング

SKILL.mdに含めるべき内容:

• コア概念と概要
• 必須ワークフロー
• クイックリファレンステーブル
• references/へのポインタ（いつ読むべきかを明記）

references/に移動すべき内容:

• 詳細パターンと高度なテクニック
• 包括的なAPIドキュメント
• エッジケースとトラブルシューティング
• 網羅的なサンプル集

ポイント: SKILL.mdから参照を明記しないと、Claudeはreferences/内のファイルの存在を知りません。「いつ読むべきか」を記載することが重要です。

# SKILL.md

## 基本的な使い方
[コアワークフロー]

## 詳細情報
- 高度なパターン: [advanced.md](references/advanced.md) - 複雑なケースで参照
- 具体例: [examples.md](references/examples.md) - 実装に迷ったら参照
- エラー対応: [troubleshooting.md](references/troubleshooting.md) - エラー発生時に参照

パターン2：CLAUDE.md + 参照ファイル + インデックス化（共有利用）

複数のSkills/Agentsで共有する情報は、プロジェクトレベルで管理します。

CLAUDE.mdの原則:

公式ドキュメントでは「短く保つ」ことが強調されています。

“If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.”

（CLAUDE.mdが長すぎると、重要なルールがノイズに埋もれて無視されます）

ディレクトリ構造例:

project/
├── CLAUDE.md                    # コア情報のみ（短く保つ）
└── docs/
    ├── README.md                # ドキュメントのインデックス
    └── references/
        ├── best-practices.md    # ベストプラクティス集
        ├── architecture.md      # アーキテクチャ詳細
        └── coding-standards.md  # コーディング規約

@構文でのファイルインポート:

CLAUDE.mdでは@path/to/file構文で他のファイルをインポートできます。インポートされたファイルは自動的にコンテキストにロードされます。

# CLAUDE.md

## プロジェクト概要
[コアな情報をここに]

## 詳細情報
See @docs/README for documentation index.
See @docs/references/best-practices for coding guidelines.

公式仕様のポイント:

• 相対パス・絶対パスの両方に対応
• 再帰的インポート可能（最大5階層）
• コードブロック内の@は無視される

詳細は公式ドキュメント: Manage Claude’s memoryを参照してください。

インデックス化のメリット:

大量のドキュメントがある場合、インデックス（目次）ファイルを用意することで、Claudeが必要な情報を効率的に見つけられます。

# docs/references/README.md（インデックスの例）

## 参照ドキュメント一覧

| ファイル | 概要 | 最終更新 |
|----------|------|----------|
| best-practices.md | Skills/Agentsの設計指針 | 2026-01-23 |
| architecture.md | プロジェクト構成の詳細 | 2026-01-20 |
| coding-standards.md | コーディング規約 | 2026-01-15 |

インデックスを先に読むことで：

• 全ファイルを読まずに関連ドキュメントを特定できる
• 重複した調査を防げる
• 必要な情報だけを選択的に読み込める

インデックス化の詳細は、AIフレンドリーなドキュメント管理で紹介しています。

応用：GitHub Copilotでの活用

Claude CodeとGitHub Copilotは思想が異なります。Claude Codeはコード生成だけでなく、調査・分析・ドキュメント作成など幅広いタスクに対応しますが、GitHub Copilotはコード補完に特化しています。

GitHub Copilotの課題として、検索機能が相対的に弱い点があります。しかし、静的情報を活用することで、この弱点をカバーできます。

• プロジェクト固有のベストプラクティスをファイルとして用意
• .github/copilot-instructions.mdで参照を指示
• 検索に頼らず、準備した情報を元に出力

静的情報を充実させることで、どのAIコーディングツールでも一定の品質を担保できるようになります。

（Claude CodeとGitHub Copilotの詳細な比較は別記事で取り上げる予定です）

まとめ

何度も参照する情報は静的情報として保存する。

このシンプルな原則を守るだけで、Claude Codeの効率は大きく向上します。

Skills/Agentsを多用するようになった段階で、この設計を見直すことをお勧めします。毎回検索している箇所がないか、ぜひチェックしてみてください。

ここまで読んでいただき、ありがとうございました！

参考リンク

• Claude Code Best Practices – Anthropic Engineering Blog
• Equipping agents for the real world with Agent Skills
• Skills公式ドキュメント
• Manage Claude’s memory – @構文でのファイルインポート
• Effective Context Engineering for AI Agents