Claude Codeが本気を出す設定方法：コンテキスト管理と自動委譲の実践ガイド

Claude Codeが本気を出す設定方法：コンテキスト管理と自動委譲の実践ガイド AI

Claude Codeは、ターミナルから直接AIを活用できる開発ツールです。

単なるコード補完ツールではありません。
プロジェクト全体を理解し、外部ツールと連携しながら開発を支援してくれます。

本記事では、Reddit上で共有されていた実践的なテクニックを紹介します。
コンテキストウィンドウの管理からカスタムエージェントの作成まで、知っておくべきポイントをまとめました。

1. CLAUDE.mdによるプロジェクト設定

Claude Codeは起動時にCLAUDE.mdファイルを読み込みます。

このファイルにプロジェクトのルールや指示を記述しておくと、Claudeがそれを理解して動作してくれます。
つまり、このファイルの設計が品質を大きく左右するわけです。

階層構造を理解する

CLAUDE.mdは複数の階層で管理できます。

グローバル設定は~/.claude/CLAUDE.mdに配置します。
プロジェクト固有の設定は./CLAUDE.mdに記述しましょう。
さらに個人的なオーバーライドが必要な場合は./CLAUDE.local.mdを使用します。

グローバル設定には、GitHubアカウント情報やDockerの認証情報を記載するのが適切です。
これらはどのプロジェクトでも共通して使う情報だからです。
一方、プロジェクト固有のアーキテクチャ方針やコーディング規約は、プロジェクトレベルのCLAUDE.mdに記述します。

セキュリティゲートキーパーとしての役割

セキュリティ研究者の調査によると、Claude Codeは.envファイルを自動的に読み込むことがあります。

明示的な許可なく読み込まれる場合もあるそうです。
この動作は便利な反面、機密情報の漏洩リスクを伴います。

そこで、グローバルのCLAUDE.mdに「絶対にやってはいけないこと」を明記しておきます。

## NEVER EVER DO

これらのルールは絶対に守ること:

### 機密データを公開しない
- パスワード、APIキー、トークンをgit/npm/dockerに公開しない
- コミット前に必ず機密情報が含まれていないか確認する

### .envファイルをコミットしない
- .envをgitにコミットしない
- .gitignoreに.envが含まれているか確認する

このようなルールを設定しておけば、Claude Codeがアクセス権を持っていても機密情報を出力することは避けられます。

チームでの運用方法

Anthropic社内のClaude Codeチームでは、単一のCLAUDE.mdをgitにコミットして共有しているそうです。
チーム全員が週に複数回更新を行っているとのこと。

運用のコツは「ミスをドキュメント化する」ことです。
Claudeが間違いを犯したら、その場で修正します。

そして、二度と起こらないようにCLAUDE.mdにルールを追加します。
この繰り返しで、プロジェクトに最適化された指示書が出来上がっていきます。

2. MCPサーバーによる外部連携

MCP（Model Context Protocol）は、Claude Codeが外部ツールと連携するための仕組みです。
データベース、ブラウザ、クラウドサービスなど、様々なシステムとの統合が可能になります。

基本的な使い方

MCPサーバーの追加はコマンドラインから行います。

claude mcp add <サーバー名> -- <コマンド>
claude mcp list
claude mcp remove <サーバー名>

いつMCPを使うべきか

MCPサーバーはトークンとコンテキストを消費します。
そのため、単純な連携であればCLIツールを直接呼び出す方が効率的な場合もあります。

たとえば、Trelloのタスク取得を一度だけ行うなら、MCP経由よりもtrello-cliを使った方がオーバーヘッドは小さくなります。
シンプルなHTTP呼び出しならcurlで十分でしょう。

一方、セッション内で同じツールを何度も使う場合は、MCPの恩恵を受けられます。
また、後述するMCP Tool Search機能により、このトレードオフは大きく変化しました。

多くのMCPサーバーを接続しても、起動時のコンテキスト消費を抑えられるようになったのです。

開発者向け推奨サーバー

実践的に役立つMCPサーバーをいくつか紹介します。

Context7は、あらゆるライブラリの最新ドキュメントを取得できるサーバーです。
インストールはclaude mcp add context7 — npx -y @upstash/context7-mcp@latestで完了します。

GitHubサーバーを使えば、PRやイシュー、CI/CDの操作をClaude Code内から行えます。
MongoDBやPostgreSQLのサーバーは、データベースとの自然言語によるやり取りを可能にしてくれます。

Playwrightサーバーは、E2Eテストやスクレイピングに便利です。
自分がログインしているChromeをそのまま使いたい場合は、Browser MCPという選択肢もあります。

3. コマンドとスキルの活用

コマンド：個人的なショートカット

コマンドは、プロンプトに展開されるマクロです。
~/.claude/commands/に配置すると、どのプロジェクトでも使えるようになります。

~/.claude/commands/review.mdを作成してみましょう。

---
description: コードレビューを実行
---

このコードをレビューしてください:
1. セキュリティの脆弱性
2. パフォーマンスの問題
3. エラーハンドリングの不足
4. コーディングスタイルの違反

セッション中に/reviewと入力するだけで、このプロンプトが展開されます。
引数を受け取るコマンドも作成可能です。

---
description: チケットを作成
argument-hint: <チケットの説明>
---

以下の内容でチケットを作成してください: $ARGUMENTS

含めるべき項目:
- ユーザーストーリー
- 受け入れ基準
- 技術的な注記

/ticket ダークモード対応を追加のように使えます。

スキル：トリガーされる専門知識

スキルは、必要なときだけ読み込まれる専門知識です。
CLAUDE.mdは常に読み込まれます。

しかし、スキルは特定のキーワードに反応して初めてロードされます。
.claude/skills/code-review/SKILL.mdを作成します。

---
name: Code Review
description: セキュリティ重視の包括的コードレビュー
triggers:
  - review
  - audit
  - check code
---

# コードレビュースキル

コードレビュー時の確認事項:
1. OWASP Top 10に基づくセキュリティ脆弱性
2. N+1クエリやメモリリークなどのパフォーマンス問題
3. エッジケースやnullチェックなどのエラーハンドリング
4. テストカバレッジの評価
5. 命名規則とドキュメントの確認

スキルは段階的に読み込まれます。
起動時には名前と説明だけが読み込まれます（約50トークン）。

そして、トリガーされると完全な内容がロードされる仕組みです。
目安として、会話の20%未満でしか使わない指示はCLAUDE.mdではなくスキルとして定義した方がトークン効率は良くなります。

4. シングルパーパスチャットの原則

複数のトピックを混在させると、精度が大幅に低下します。
研究によると、複数ターンにわたって指示を伝えた場合、平均39%のパフォーマンス低下が見られたそうです。

また、「コンテキスト腐敗」と呼ばれる現象も報告されています。
コンテキストウィンドウ内のトークン数が増えるにつれて、情報を正確に思い出す能力が低下するというものです。

実践的なルール

新しい機能を実装するときは、新しいチャットを開始しましょう。
無関係なバグ修正に取り組む場合は、/clearでコンテキストをリセットしてから作業を始めます。

調査と実装は別のチャットで行うのがベストです。
20ターン以上経過したら、新しいセッションを検討してください。

Anthropicの公式ドキュメントでも、タスク間で頻繁に/clearを使うことが推奨されています。

コンテキストの可視化

現在のコンテキスト使用状況は/contextコマンドで確認できます。
どこでトークンが消費されているか把握することで、効率的なセッション管理が可能になります。

5. フックによる確実な制御

CLAUDE.mdのルールは「提案」です。
コンテキストの圧力下では無視される可能性があります。
一方、フックは「強制」です。常に実行されます。

フックイベントの種類

PreToolUseはツール実行前に発火します。
危険な操作をブロックするのに使えます。

PostToolUseはツール完了後に実行されます。
リンターの実行などに適しています。

StopはClaudeがターンを終了したときに発火します。
品質ゲートとして機能させられます。

新しく追加されたSetupイベントは、初期化やメンテナンス時にトリガーされます。

機密ファイルへのアクセスをブロック

~/.claude/settings.jsonに以下を追加します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "python3 ~/.claude/hooks/block-secrets.py"
        }]
      }
    ]
  }
}

フックスクリプトの内容は以下のとおりです。

#!/usr/bin/env python3
import json, sys
from pathlib import Path

SENSITIVE = {'.env', '.env.local', 'secrets.json', 'id_rsa'}

data = json.load(sys.stdin)
file_path = data.get('tool_input', {}).get('file_path', '')

if Path(file_path).name in SENSITIVE:
    print(f"BLOCKED: Access to {file_path} denied.", file=sys.stderr)
    sys.exit(2)  # 終了コード2 = 操作をブロックし、理由をClaudeに伝える

sys.exit(0)

終了コードの意味は次のとおりです。

0は操作を許可します。
1はエラーをユーザーに表示します。
2は操作をブロックし、その理由をClaudeに伝えます。

6. MCP Tool Search：85%のコンテキスト削減

これはClaude Code 2.1.xで導入された最大の変更点です。

問題の背景

接続しているMCPサーバーごとに、ツール定義がコンテキストに読み込まれていました。
説明、パラメータ、スキーマなどです。

ユーザーの報告によると、最初のプロンプトを入力する前に、200Kのコンテキストウィンドウの50〜70%が消費されていたそうです。

遅延読み込みという解決策

MCP Tool Searchは、ツールをオンデマンドで読み込みます。

起動時にはツールのレジストリ（名前と説明のみ）だけを読み込みます。
そして、Claudeが必要と判断したときに初めて完全なツール定義をロードする仕組みです。

数値で見ると、初期コンテキスト使用量は約77Kトークンから約8.7Kトークンへ削減されました。
85%の削減です。

精度も向上しています。
Opus 4での精度は49%から74%へ向上しました。
Opus 4.5では79.5%から88.1%へ改善したと報告されています。

設定方法

MCP Tool Searchは、ツールがコンテキストの10%以上を消費する場合にデフォルトで有効になります。
特定のサーバーを常に即座に読み込みたい場合は、個別に無効化できます。

{
  "mcpServers": {
    "always-needed": {
      "command": "...",
      "enable_tool_search": false
    }
  }
}

自動有効化の閾値を変更することも可能です。

{
  "mcp": {
    "tool_search": "auto:15"
  }
}

この変更により、数十のMCPサーバーを接続してもペナルティなく運用できるようになりました。

7. カスタムエージェント：自動的な委譲

カスタムエージェントは、Claudeが自動的に呼び出す専門アシスタントです。
ツールを自動選択するのと同じように、タスクに応じて適切なエージェントに委譲します。

なぜカスタムエージェントが必要か

多様なタスクが混在するとコンテキストが汚染されます。
しかし、各エージェントは独立したコンテキストウィンドウを持ちます。

そのため、この問題を回避できるのです。
また、汎用的なアドバイスではなく、専門分野に特化した指示を各エージェントに持たせることで品質も向上します。

エージェントの作成

インタラクティブに作成する場合は/agentsコマンドを使用します。
手動で作成するなら、~/.claude/agents/code-reviewer.mdを配置します。

---
name: code-reviewer
description: セキュリティ、パフォーマンス、ベストプラクティスのコードレビュー
tools: Read, Grep, Glob
model: sonnet
---

あなたはシニアコードレビュアーです。専門分野:
- OWASP Top 10に基づくセキュリティ脆弱性
- パフォーマンスアンチパターン
- エラーハンドリングの不足
- コードの保守性

レビュー時の手順:
1. セキュリティの懸念から始める
2. 次にパフォーマンスの問題
3. スタイルと保守性
4. 具体的な行番号を参照
5. 具体的な修正案を提示

批判的だが建設的に。なぜ問題なのかを説明すること。

自動委譲の仕組み

Claudeは以下の情報を基に委譲先を決定します。

  • リクエストのタスク説明
  • エージェント設定のdescriptionフィールド
  • 現在のコンテキスト
  • 利用可能なツール

「認証モジュールのセキュリティ問題をレビューして」と依頼したとします。
するとClaudeは「これはセキュリティに焦点を当てたコードレビュータスクだ」と判断します。
そして、code-reviewerエージェントに委譲するわけです。

エージェントは独立したコンテキストで実行されます。
結果はメインの会話に返されます。

ベストプラクティス

エージェントは焦点を絞りましょう。
1つのエージェントに1つの専門分野を持たせます。

説明は明確に書いてください。
Claudeはこの説明を基に委譲を判断するからです。

ツールは必要最小限に制限します。
読み取り専用のエージェントにWrite権限は不要です。

最初は3〜4つのエージェントから始めるのがお勧めです。
選択肢が多すぎるとルーティングが混乱する可能性があります。

なお、エージェントファイルの更新は即座に反映されます。
再起動は不要です。

8. セッションテレポーテーションとバックグラウンドタスク

作業の移動

/teleportコマンドで、現在のセッションをclaude.ai/codeに移動できます。
以下のような場面で便利です。

  • ターミナルからビジュアルインターフェースへの切り替え
  • コラボレーターとのセッション共有
  • 別のデバイスでの作業継続

セッションの再開はclaude –continueまたはclaude -cで直近のセッションを継続できます。
特定のセッションはclaude –resume abc123で再開します。

バックグラウンドタスク

Ctrl+Bで現在実行中のエージェントやシェルコマンドをバックグラウンドに移動できます。
これにより、重い処理を実行しながら別の作業を進められます。

/tasksコマンドでバックグラウンドタスクを管理できます。
ステータス確認、完了通知、トランスクリプトへのアクセスが可能です。

9. その他の便利な機能

新しいコマンド

/configに検索機能が追加されました。
設定項目をフィルタリングして素早く見つけられます。

/statsでは「r」キーを押すと表示期間を切り替えられます。
過去7日間、30日間、全期間から選べます。

/keybindingsでカスタムキーボードショートカットを設定できます。
~/.claude/keybindings.jsonに以下のように記述します。

{
  "ctrl+shift+r": "/review",
  "ctrl+shift+d": "/deploy",
  "ctrl+shift+t": "/test",
  "ctrl+shift+c": "/commit"
}

必須のショートカット

覚えておくと便利なショートカットを紹介します。

Ctrl+Cで現在の操作をキャンセルします。
Ctrl+Dで終了します。
Ctrl+Bでバックグラウンド化します。

Escを2回押すと前の状態に巻き戻せます。
Tabでコマンド、ファイル、エージェントを補完できます。
Shift+Enterで送信せずに改行を挿入します。

言語設定

グローバルチーム向けに出力言語を設定できます。

{
  "language": "ja"
}

CLAUDE.mdに「常に日本語で回答してください」と書く方法もあります。

まとめ

Claude Codeを効果的に使うには、いくつかの原則を理解しておく必要があります。

まず、CLAUDE.mdでルールを定義し、フックで確実に強制する。
この二段構えがセキュリティと品質を担保します。

次に、コンテキストは有限なリソースだと意識することです。
シングルパーパスチャットを心がけ、/clearを積極的に使いましょう。

MCP Tool Searchの導入により、多くの外部ツールを接続してもコンテキストの浪費を気にする必要がなくなりました。
カスタムエージェントは、複雑なタスクを専門家に委譲する仕組みを提供してくれます。

これらの機能を組み合わせることで、Claude Codeは単なるコード補完ツールから、プロジェクト全体を支援するパートナーへと変わります。
まずはCLAUDE.mdの設定から始めて、徐々に機能を追加していくのがお勧めです。

タイトルとURLをコピーしました