コンテキスト汚染を防ぐ4つの衛生習慣 — Claude Code Context Hygiene 実践ガイド – Cloud Steady

はじめに

こんにちは、NewIT部の下谷です。
今回はAIエージェントを使って開発を行う上でいかにコンテキストを効率よく使ってコーディングの精度を上げるかのイロハを紹介したいと思います。

「何を入れないか」で精度を決まる

コンテキスト汚染とは何か？

コンテキスト汚染（Context Contamination）とは、Claude CodeなどのAIコーディングツールが参照するコンテキストウィンドウに、不要・冗長・相互矛盾する情報が蓄積され、モデルの応答精度が低下する現象です。放置すると、AIコーディングの精度が30%以上低下することが実証されています。

CLAUDE.mdに丁寧に詳細な指示を書き込むほど、AIの精度が向上すると思いがちです。しかし実際には逆の結果が起きることがあります。Liu et al.（TACL 2024）の「Lost in the Middle」研究によれば、LLMはコンテキストウィンドウの中間に置かれた情報を、先頭・末尾と比較して30%超の精度低下で処理します。詳細な指示ほど長く、長くなるほど中間に埋もれ、無視されます。

下図は、コンテキスト内の配置位置（先頭・中間・末尾）と情報保持率の関係を示すU字型パフォーマンスカーブです。中間配置で保持率が最も低下します。

この現象を理解した上で実践する設計アプローチが Context Hygiene です。

Context Hygiene とは？

Context Hygieneとは、「コンテキストウィンドウに何を入れ、何を入れないかを意識的に設計する実践」です。「何を書くか」よりも「何を書かないか」に焦点を当てる点が、従来のプロンプトエンジニアリングとの大きな違いです。

本記事では、Context Hygieneを実践するための4つの衛生習慣を解説します。

衛生習慣① 「50行以内の憲法」 — CLAUDE.mdを最小化してベースラインコストを削る
衛生習慣② 「スキル分離」 — 必要なときだけ呼び出す設計でトークンをゼロに保つ
衛生習慣③ 「サブエージェント委譲」 — メインコンテキストをノイズから守る返路設計
衛生習慣④ 「MCP最小化」 — 見えないトークンコストを定量化して管理する

Context Hygiene とは何か — 汚染のメカニズムを理解する

Lost in the Middle — コンテキスト中間の情報は30%超、精度が落ちる

Stanford大学などの研究者によるLiu et al.（TACL 2024）の論文「Lost in the Middle: How Language Models Use Long Contexts」は、LLMのコンテキスト処理に関する重要な事実を実証しました。

実験では、マルチドキュメントQAタスクと複数キーバリュー検索タスクを使用し、正解となる情報をコンテキストの先頭・中間・末尾に配置した場合の精度を比較しました。結果はU字型のパフォーマンスカーブを描きます。

Primacy bias（初頭効果）: コンテキスト先頭の情報は高い保持率で処理される
Recency bias（新近効果）: コンテキスト末尾の情報も比較的高い保持率を維持する
中間劣化: 先頭・末尾以外に配置された情報は30%超の精度低下が観測される

CLAUDE.mdへの設計含意は明確です。最重要の指示（禁止事項、アーキテクチャ制約、コーディング規約の核心）は先頭か末尾に配置し、中間に詳細な説明を詰め込まないことが基本原則になります。

Context Rot と「dumb zone」問題

Context Rotとは、コンテキスト長が増えるにつれて性能が不安定かつ不均一に劣化する現象です。「1Mトークンまで入力できる」ことと「1M全量で同じ精度で動く」ことは別物です。

Claude Code特有の問題としてオートコンパクティングがあります。コンテキスト使用率が約80〜90%に達すると、古い会話を要約圧縮する処理が自動発動します。この際に最も消えやすい情報には優先順位があります。

危険度	消えやすい情報の種類
最高	否定的指示（「〇〇はやらない」「〜は使わない」）
高	変数名・関数名の由来や設計意図
中	セッション序盤のアーキテクチャ制約
低	大まかな技術スタック（比較的残る）

さらに、コンテキストウィンドウの20〜40%の地点でも、容量不足ではなく性能の測定可能な低下が発生します（”dumb zone”問題）。誤った提案への訂正が繰り返されると「trajectory poison（軌跡汚染、コミュニティで使われる概念的表現）」が発生し、モデルが失敗を予期するループに入ります。

Context Rotの症状チェックリスト:

セッションの後半で、序盤に決めた設計方針と矛盾するコードが生成される
「〇〇はやらないで」と伝えたはずの制約が無視される
30分前に確認した変数名やインターフェース定義が別の名前に変わっている
同じエラーの修正を繰り返しているのに改善しない

衛生習慣①「50行以内の憲法」— CLAUDE.md を最小化する

CLAUDE.mdは、Claude Codeがすべてのセッション・すべてのターンで読み込む「憲法」です。1文字も入力する前に、その内容がまるごとコンテキストウィンドウを占有します。5,000トークンのCLAUDE.mdは、会話を始める前から5,000トークンを消費します。

定量的なガイドライン

buildtolaunch.substack.comの計測によれば、CLAUDE.mdを500トークン以内に最適化すると、セッション全体のインプットトークンが約40%削減されます。推奨の上限は500トークン（約50行）、より積極的なアプローチでは200トークン以内です。

「50行以内の憲法」という命名はこの根拠に基づいています。ただし、1行あたりのトークン数はコンテンツによって大きく異なるため、500トークンを優先指標として扱うことが正確です。

CLAUDE.mdに書かないべきコンテンツ

除外すべきコンテンツ	理由	代替手段
完全なスタイルガイド	常に読み込まれる無駄なコスト	スキルファイルに分離
詳細なワークフロー説明	関連しないタスク時も消費する	スキルとして呼び出し型に
包括的なAPIリファレンス	膨大なトークン消費	個別ファイルへのポインタ
プロジェクト全体の歴史・背景	必要時以外は不要	ADRファイルで管理
希望・理想・抱負（aspirational）	行動変化がないなら不要	記載しない

Before/After: CLAUDE.md の最適化例

```markdown

# Before（汚染されたCLAUDE.md — 過剰記述の例）

このプロジェクトはNext.js 14とTypeScript 5.3を使用したEコマースサイトです。

2025年1月に開始し、チームメンバーは5名です。フロントエンドはTailwind CSSを使用し、

バックエンドはPostgreSQLとPrismaを使用しています。以前のバージョンではMySQLを

使用していましたが、パフォーマンスの問題から移行しました...（以下200行続く）

コーディング規約:

- 変数名はcamelCaseを使用すること

- 関数は必ずJSDocコメントを書くこと

- コンポーネントはアトミックデザインパターンに従うこと

...（以下100行）

```

```markdown

# After（Context Hygiene適用後のCLAUDE.md — 50行以内）

## 絶対禁止（最重要 — 先頭配置）

- any型の使用禁止

- console.logの本番コードへのコミット禁止

- APIレイヤーをバイパスした直接DB呼び出しの禁止

## プロジェクト概要

- Next.js 14 + TypeScript + PostgreSQL/Prisma

- コーディング規約: .claude/skills/coding-standards.md 参照

- API設計: .claude/skills/api-design.md 参照

## 重要な制約（末尾にも配置）

- 絶対禁止事項は先頭を参照

```

否定的指示（「〇〇はやらない」）は、オートコンパクティングで最も消えやすいため、先頭か末尾に配置します。詳細なワークフローはスキルファイルへのポインタとして管理することで、必要な時だけ読み込まれる設計になります。

ADRファイルによる長期記憶の代替設計

CLAUDE.mdから除外した「プロジェクト全体の歴史・背景」や「アーキテクチャ制約」は、削除するのではなくADR（Architecture Decision Records）ファイルとして管理します。

ADRは「なぜこの実装にしたか」という意思決定のプロセスをソースコードと共に記録するドキュメントです。CLAUDE.mdで ADRを参照と一行書くだけで、必要な時だけ Claude Code が読み込む「呼び出し型の長期記憶」として機能します。

CLAUDE.md への記載例:

```markdown

## アーキテクチャ決定

重要な設計判断は `.claude/adr/` 以下のADRファイルで管理。

必要に応じて参照すること。

```

ADRへの記載例:

```markdown

# ADR-0042: API レスポンスに camelCase を採用

## ステータス: 承認済み

## コンテキスト: フロントエンドとの整合性が課題だった

## 決定: JSON フィールドは camelCase に統一する

## 結果: 自動変換レイヤーが不要になりコードが簡潔化

```

これにより、CLAUDE.mdをコンパクトに保ちながら、過去の意思決定の文脈を失わずに済みます。

衛生習慣②「スキル分離」— 必要なときだけ呼び出す設計

スキルファイル（.claude/skills/」以下に配置するMarkdownファイル）は、CLAUDE.mdとは異なりオンデマンドでのみ読み込まれます。使用しないスキルのベースラインコストはゼロです。

CLAUDE.mdに全部書く場合との比較

下図は、全ワークフローをCLAUDE.mdに書いた場合（毎ターン全量消費）と、スキル分離した場合（未使用スキルはゼロトークン）のコスト比較です。

1スキル = 1手順の原則

スキルを設計する際には「Single Responsibility」原則を適用します。1つのスキルファイルが1つのワークフロー・1つの責務のみを担当することで、不要な文脈干渉を防ぎます。

スキルファイルには「NOT-DOセクション」の明示も重要です。「このスキルが対象とする範囲外の処理」を宣言することで、スキル呼び出し時の誤解釈を防ぎます。

加えて、スキルファイルの先頭にはYAMLフロントマターで name と description を記載します。description はClaude Codeがスキルを自動選択するための判断材料となります。「どんな状況・どんな依頼語で呼び出すか」を自然文で書くことで、適切なスキルが選ばれるようになります。

```markdown

# スキルファイルの例: .claude/skills/review-pr.md

---

name: review-pr

description: PRのコードレビューを実施するスキル。「PRをレビューして」「コードレビューお願い」「差分を確認して」と依頼されたときに使用する。

--

## 目的

プルリクエストのコードレビューを実施する

## NOT-DO（このスキルが対象としない処理）

- ブランチのマージは行わない

- コードの自動修正は行わない

- テストの実行は別スキル（run-tests.md）を参照

## 手順

1. diffを取得する

2. 正確性・セキュリティ・パフォーマンスの観点でレビューする

3. 指摘事項を箇条書きで返す

```

実例: QuestDBのreview-prスキル

foojay.ioで紹介されているQuestDBの事例では、review-prスキルが8つの並列サブエージェントを起動する設計を採用しています。各サブエージェントは「正確性」「並行性」「パフォーマンス」「セキュリティ」など独立した観点を担当し、文脈干渉がゼロで並列検査を実現しています。

context-mode を活用したスキル設計により、MCP関連トークンを50〜90%削減したという計測値も報告されています（buildtolaunch.substack.com）。

衛生習慣③「サブエージェント委譲」— メインコンテキストを守る返路設計

サブエージェントの分離メカニズム

サブエージェントは独立したコンテキストウィンドウで動作するため、ノイズの多い調査タスクを委譲することでメインセッションを保護できます。ただし、使い方を誤ると汚染を先送りするだけになります。

委譲すべきタスク vs 委譲すべきでないタスク

委譲すべきタスク	委譲すべきでないタスク
大量出力を生む調査タスク	短い照会・確認
ログ・ドキュメントの処理	コアアーキテクチャの決定
テストの実行・解析	設計の意思決定
外部データの取得・検査	直前のコンテキストを参照する作業
独立したコードレビュー	メインの実装フロー

「返路設計」の重要性

サブエージェントを使えば汚染を完全に防げると思われがちですが、半分は誤りです。サブエージェントが終了すると、その「旅の全記録（調査過程のすべての出力）」が親コンテキストに返却されます。複数エージェントの全記録をそのまま連結して返すと、汚染を後続フェーズに先送りするだけになります。

下図は、返路設計なし（サブエージェントの全記録が親コンテキストを汚染）と返路設計あり（要約のみ返却してコンテキストをクリーンに維持）の比較フローです。

対策はサブエージェントの出力を必ず要約して返却することです（foojay.io「output summarization」パターン）。サブエージェントへの指示に「結果は必ず箇条書きで要約して返すこと。詳細な過程は返さないこと」を明記します。

Git worktreeによる物理的分離

2026年の標準パターンとして、Git worktreeを活用した物理的分離があります。同一リポジトリから複数ブランチを同時チェックアウトし、独立した作業ディレクトリを確保することで、ファイルシステムレベルでの干渉も防ぎます。

```bash

# Git worktreeによる並列作業環境の作成

git worktree add ../project-feature-a feature/a

git worktree add ../project-feature-b feature/b

# 各ディレクトリで独立したClaude Codeセッションを起動

# → コンテキストが物理的に分離される

```

衛生習慣④「MCP最小化」— 見えないトークンコストを削る

MCPサーバーのトークンコストは、多くのエンジニアが気づいていない「見えないコスト」です。接続されているMCPサーバーのツール定義は、セッションごとではなく毎メッセージのターンごとに読み込まれます。

MCPサーバー構成別のトークンコスト実測値

構成	追加トークン	コンテキスト占有率
ビルトインツールのみ	10,000〜11,000	約5%
単一MCPサーバー（Playwright等）	+4,000〜8,000	+2〜4%
中程度セットアップ（GSuite等）	+5,000〜10,000	+2.5〜5%
重いセットアップ（5+サーバー）	+55,000〜100,000	27〜50%超

mariogiancini.comでは「会話開始前に66,000トークンが消費された」ケースが実証されています。1ツール定義は100〜500トークン、10ツールを持つサーバーはターンごとに1,500〜3,000トークンを消費します。

接続すべき場合 vs 接続すべきでない場合

接続すべき場合	接続すべきでない場合
永続セッション状態が必要（ブラウザ、DB接続）	CLIスクリプトで代替可能
双方向通信が必要	単一用途ツール
プロジェクト全体で頻繁に使用	稀にしか使わない機能
チーム共通の外部サービス連携	個人的な設定・試験的なツール

2026年1月の改善点（留保付き）

2026年1月以降、Claude Codeにはツール定義がコンテキストウィンドウの10%を超えた場合にMCP Tool Searchを自動有効化する最適化が導入されています。オンデマンドで検索・読み込みを行うこの仕組みにより、セッション開始コストの最大95%削減を報告するユーザーもいます。ただし、この改善はあくまで「重いMCPセットアップの緊急対応策」であり、「必要なものだけ接続する」という設計原則は依然として有効です。

AIコーディング精度を最大化する — Context Hygiene チェックリスト

4つの衛生習慣は独立した施策ではなく、レイヤー構造で相互に強化しあいます。

衛生習慣①（CLAUDE.md最小化）がベースラインコストを削減し、コンテキストウィンドウに余裕を作ります
衛生習慣②（スキル分離）が不要な情報をオンデマンド化し、常時消費をゼロにします
衛生習慣③（サブエージェント委譲）がノイズをメインコンテキストに混入させないよう分離します
衛生習慣④（MCP最小化）が見えないトークンコストを管理します

Context Hygiene 実践チェックリスト

CLAUDE.md（衛生習慣①）

CLAUDE.mdは500トークン（約50行）以内に収まっているか
否定的指示（「〜はやらない」）は先頭か末尾に配置されているか
スタイルガイド・APIリファレンス・詳細ワークフローはスキルファイルに移動済みか
aspirational（希望・理想）な記述は削除されているか

スキル分離（衛生習慣②）

各スキルは1つの責務のみを担当しているか（Single Responsibility）
スキルファイルに「NOT-DOセクション」が記載されているか
CLAUDE.mdからスキルファイルへのポインタ（ファイルパス参照）は3件以内か

サブエージェント委譲（衛生習慣③）

大量出力を生む調査タスクはサブエージェントに委譲しているか
サブエージェントへの指示に「要約して返す」指定が含まれているか
サブエージェントの全記録をそのまま親コンテキストに返していないか

MCP最小化（衛生習慣④）

使用頻度の低いMCPサーバーは切断しているか
CLIスクリプトで代替できるMCPサーバーは整理済みか
接続中のMCPサーバー数は5未満に保たれているか

よくある誤解

「CLAUDE.mdに詳しく書けば書くほど良い」— これは誤りです。詳細すぎるCLAUDE.mdは毎ターンのベースラインコストを増やし、中間に埋もれた指示はLost in the Middleにより無視されます。
「サブエージェントはコンテキスト汚染を完全に防ぐ」— 半分は誤りです。サブエージェントの出力を要約せずに全記録として親コンテキストに返すと、汚染を後続フェーズに先送りするだけです。
「MCPサーバーは接続しておくだけなら問題ない」 — これは誤りです。接続されているMCPサーバーのツール定義は毎メッセージ読み込まれます（2026年1月の最適化以降は改善されていますが、設計原則は変わりません）。
「否定的指示はコンテキストの途中に書いても大丈夫」 — これは誤りです。否定的指示はオートコンパクティングで最も消えやすいため、CLAUDE.mdの先頭か末尾に配置する必要があります。

まとめ

本記事では、Claude Codeのコンテキスト汚染を防ぐ4つの衛生習慣を解説しました。

衛生習慣	主なアクション	期待効果
① 50行以内の憲法	CLAUDE.mdを500トークン以内に最小化	セッション全体で40%トークン削減
② スキル分離	ワークフローをオンデマンドファイルへ移動	未使用スキルのコストをゼロに
③ サブエージェント委譲	返路設計（要約返却）を必ず実施	メインコンテキストをノイズから保護
④ MCP最小化	接続サーバーを必要最小限に絞る	見えないトークンコストを最大90%削減

Context Hygieneの本質は「何を入れないか」という意思決定です。AIコーディングの精度向上は、詳細な指示を追加することではなく、コンテキストウィンドウから不要なものを除去することによって実現されます。

以上となります。

弊社にご興味いただけましたら、お気軽にお問合せいただけますと幸いです

当サイトはパーソルクロステクノロジー㈱より提供しています