0. TL;DR
この記事は、Claude Code を 6 か月間深く使い、2 つのアカウントで月額 40 ドルを費やして得た教訓から得られたものです。皆さんにとって価値ある情報を提供できればと思います。
最初は ChatBot として使っていましたが、すぐに問題が発生していることに気づきました。コンテキストが乱雑になり、ツールは増えたのに効果は低下し、ルールは長くなる一方で無視されるようになりました。Claude Code 自体を調べてみると、これはプロンプトの問題ではなく、システム設計の問題だとわかりました。
ここでは、Claude Code の内部動作、コンテキストが乱雑になる理由とその管理方法、Skills と Hooks の設計方法、Subagents の正しい使い方、Prompt Caching のアーキテクチャへの影響、そして真に有用な CLAUDE.md の書き方について説明します。
最も直接的な理解方法は、Claude Code を 6 つのレイヤーに分解することです。
1 つのレイヤーだけを強化すると不均衡が生じます。CLAUDE.md が長すぎるとコンテキストを汚染し、ツールが多すぎると混乱を招き、サブエージェントが多すぎると状態が不安定になり、検証をスキップすると問題の原因を特定できなくなります。
1. 内部の仕組み
Claude Code の核心は「応答」ではなく、反復するエージェントループです。
1コンテキスト収集 → アクション実行 → 結果確認 → [終了またはループ]2 ↑ ↓3 CLAUDE.md Hooks / Permissions / Sandbox4 Skills Tools / MCP5 Memory
ボトルネックは、モデルの賢さ不足ではなく、誤ったコンテキストを与えているか、出力が正しいか判断する手段やロールバックする手段がないことにあると気づきました。
注目すべき 5 つのレイヤー
これらのレイヤーを理解すれば、トラブルシューティングが容易になります。結果が不安定？コンテキストの読み込み順を確認。自動化が制御不能？制御レイヤーを確認。長時間セッションで品質が低下？中間成果物がコンテキストを汚染しています。プロンプトを調整するよりも新しいセッションを開始したほうが良いでしょう。
2. 概念の境界: MCP / Plugin / Tools / Skills / Hooks / Subagents
シンプルなルール: 新しいアクションには Tools/MCP を、ワークフローには Skills を、独立した環境には Subagents を、必須の制約/監査には Hooks を、プロジェクト間での配布には Plugins を使用します。
3. コンテキストエンジニアリング: 最も重要なシステム制約
多くの人はコンテキストを「容量の問題」と考えていますが、ボトルネックは通常ノイズです。有用な情報が無関係なコンテンツに埋もれてしまいます。
実際のコンテキストコストの内訳
Claude Code の 200K コンテキストは、全てが利用できるわけではありません。
1200K 総コンテキスト2├── 固定オーバーヘッド (~15-20K)3│ ├── システム指示: ~2K4│ ├── スキル記述子: ~1-5K5│ ├── MCP サーバーツール定義: ~10-20K ← 最大の隠れた原因6│ └── LSP 状態: ~2-5K7│8├── 準固定 (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memory: ~1-2K11│12└── 動的利用可能 (~160-180K)13 ├── チャット履歴14 ├── ファイル内容15 └── ツール結果
典型的な MCP サーバー（GitHub など）には 20～30 のツール定義が含まれ、それぞれ約 200 トークンで、合計 4,000～6,000 トークンになります。5 つのサーバーに接続すると 25,000 トークン (12.5%) を消費します。これは大量のコードを読む場合に重要です。
推奨されるコンテキスト階層化
1常駐 → CLAUDE.md: プロジェクト契約 / ビルドコマンド / 禁止事項2パスベース → rules: 言語 / ディレクトリ / ファイルタイプ別ルール3オンデマンド → Skills: ワークフロー / ドメイン知識4分離 → Subagents: 大規模調査 / 並列リサーチ5コンテキスト外 → Hooks: 決定論的スクリプト / 監査 / ブロッキング
たまにしか使わないものはロードしないでください。
コンテキストのベストプラクティス
- CLAUDE.md は短く、明確で、実行可能に保ちます。Anthropic 自身のものは約 2.5K トークンです。
- 大きなリファレンスドキュメントは Skills のサポートファイルに移動します。
- パス/言語ルールには .claude/rules/ を使用します。
- /context で消費量を監視します。
- タスク切り替えには /clear を、新しいフェーズには /compact を使用します。
- CLAUDE.md にコンパクトな指示を記述して、何が保持されるかを制御します。
ツール出力ノイズ: もう一つの隠れた原因
動的ツール出力（cargo test や git log など）は、容易にコンテキストを埋め尽くします。Claude が全てを見る必要はありません。
RTK (Rust Token Killer) は良いアプローチです。コマンド出力を Claude に渡す前にフィルタリングします。例えば、数千行のテスト出力を 1 つの成功メッセージに要約できます。
圧縮の落とし穴
デフォルトの圧縮は、アーキテクチャ上の決定や制約を削除する可能性があります。
解決策: CLAUDE.md に Compact Instructions を指定して、アーキテクチャ上の決定、変更されたファイル、検証ステータス、TODO を優先的に保持します。
別の予防策: 新しいセッションを開始する前に Claude に HANDOFF.md を書かせて、進捗状況と行き詰まりを説明させます。
Plan Mode の工学的価値
Plan Mode は探索と実行を分離します。
複雑なリファクタリングでは、コードに急ぐよりもこの方法が優れています。高度なヒント: 1 つの Claude に計画を書かせ、別の Claude を「シニアエンジニア」としてレビューさせます。
4. Skills の設計: オンデマンドでロードされるワークフロー
Skills はオンデマンドの知識とワークフローです。
優れた Skill の条件
- 説明は「何をするか」ではなく、「いつ使うか」を記述します。
- 完全なステップ、入力、出力、停止条件を持ちます。
- メイン部分はナビゲーションとコア制約に使用し、詳細はサポートファイルに移動します。
- 副作用のあるスキルには disable-model-invocation: true を設定します。
プログレッシブディスクロージャー
Claude Code は「プログレッシブディスクロージャー」を重視しています。まず索引とナビゲーションを提供し、必要に応じて詳細を取得します。
3 つの典型的な Skill タイプ
- チェックリスト (品質ゲート): 例: release-check
- ワークフロー (標準化オペレーション): 例: ロールバック付き config-migration
- ドメインエキスパート (意思決定フレームワーク): 例: runtime-diagnosis
記述子は短く保ち、コンテキストスペースを節約します。
5. ツール設計: Claude が正しく選択できるようにする
エージェント向けのツールは、機能の完全性よりも、正しく使いやすさに重点を置く必要があります。
良いツールと悪いツール
設計原則: プレフィックス（github_pr_*）を使用し、簡潔なフォーマットをサポートし、役立つエラーメッセージを提供し、細分化されすぎたツールを公開しない。
内部ツールの進化
"AskUserQuestion" ツールの進化は、専用ツールがマークダウン書式や終了パラメータよりも安定していることを示しています。
モデルが強力になるにつれて、Todo ツールは「束縛」になりました。検索ツールは、柔軟性と「プログレッシブディスクロージャー」を向上させるために、RAG から Grep へと進化しました。
6. Hooks: 操作前後の必須ロジック
Hooks は、フォーマット、ファイル保護、通知などのプロセスに対する決定論的な制御を取り戻します。
Hooks に適した用途
保護されたファイルのブロック、編集後の自動フォーマット、動的コンテキスト（Git ブランチ）の注入、通知。
早期エラー検出
7. Subagents: 独立した Claude インスタンス
Subagents は分離を提供します。リポジトリのスキャンやテストの実行などのタスクは大量の出力を生成しますが、メインスレッドを散らかすべきではありません。
明示的な制約
ツールを制限し、適切なモデルを選択し（調査には Haiku、レビューには Opus）、maxTurns を設定します。
8. Prompt Caching: Claude Code アーキテクチャの中核
Claude Code は Prompt Caching を中心に構築されています。高いヒット率はコストを節約し、レート制限を緩和します。
キャッシングのためのプロンプトレイアウト
プレフィックス一致のために順序: システムプロンプト → ツール定義 → チャット履歴 → ユーザー入力。
セッション中のモデル切り替え禁止
モデルを切り替えるとキャッシが壊れます。代わりに Subagents を使用して引き継ぎを行います。
Compaction の実装
Compaction はフォークを使用して履歴を要約します。キャッシュヒットにより、コストは 1/10 になります。
9. 検証ループ: 検証なきエンジニアリングエージェントは無意味
「Claude が完了したと言った」だけでは、検証がなければ無価値です。Prompt、Skill、CLAUDE.md で検証を明示的に定義します。
10. 高頻度コマンド
/context、/clear、/compact、/memory などのコマンドは、コンテキストを積極的に管理するのに役立ちます。
ガバナンスと並列性
便利な隠しコマンド: /simplify（コードレビュー）、/rewind（チェックポインティング）、/btw（サイド質問）、/insight（CLAUDE.md 更新のためのセッション分析）。
11. 良い CLAUDE.md の書き方
それは契約であり、知識ベースではありません。
ビルド/テストコマンド、アーキテクチャの境界、コーディング規約、安全レール、Compact Instructions を含めます。Claude が間違いを修正した後に、CLAUDE.md を更新するよう依頼します。
12. 最近の経験
Kaku（Rust + Lua）の構築からの教訓: 環境の透明性は不可欠（'doctor' コマンドを使用）。Hooks はマルチ言語プロジェクトに最適。
13. アンチパターン
14. ヘルスチェック
npx skills add tw93/claude-health を実行して設定を確認します。
15. 結論
焦点は「機能の使い方」から「制約下でエージェントを実行する方法」に移ります。「完了」を定義できないなら、そのタスクはエージェントに適していません。
