ECC 調査コンテキスト実践ガイド——リサーチファーストで「行動の前に理解する」Agent モードを組み込む

ECC 調査コンテキスト実践ガイド——リサーチファーストで「行動の前に理解する」Agent モードを組み込む

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本ガイドは、ECC（Everything Claude Code）仓库的contexts/research.md（調査コンテキスト）を主軸に、動的システムプロンプト注入による「調査・探索・学習モード」の設計思想・実装・運用方法を解説する。読者は、AI エージェントに「結論を急がせず、証拠を集めてから動く」調査プロセスを組み込む方法、claude --system-promptによるコンテキスト切り替え、調査プロセスの5ステップ、推奨ツールの使い分け、アウトプット規約（Findings first, recommendations second）を学べる。

はじめに：調査コンテキストとは何か

ECC のリポジトリには、エージェントの行動様式を切り替えるための動的システムプロンプト注入コンテキストが用意されている。contexts ディレクトリには以下の3つのモードが定義されている：

このうち調査コンテキスト（research.md）は、「行動の前に理解する（Understanding before acting）」を核とする、探索・調査・学習専用のモードである。README のディレクトリ構成にもresearch.md # Research/exploration mode context（README.md）として明記されている。

このコンテキストの役割は、コード生成や実装よりも調査そのものを優先させることにある。未知のコードベースに触れるとき、仕様を確定させる必要があるとき、技術選定を行うときなど、結論を出す前に十分な情報収集を行いたい場面で活用する。

調査コンテキストの設計思想：リサーチファースト開発

ECC は README で自らを「research-first development（リサーチファースト開発）」を掲げるシステムと位置づけている（英語版 README.md 冒頭、および docs/de-DE/README.md の "research-first-Entwicklung" という記述にも同様の思想が見られる）。

リサーチファーストとは、コードを書く前に調査・検証を完了させる開発スタイルであり、調査コンテキストはこの思想を実行可能なプロンプトとして具体化したものである。dev.mdが「まずコードを書き、後から説明する（Write code first, explain after）」という対照的なスタンスを取る（contexts/dev.md）のに対し、research.mdは「理解が明確になるまでコードを書かない」という逆方向の規律をエージェントに課す。

この2つのコンテキストを状況に応じて切り替えることで、同一のエージェントを「調査フェーズ」と「実装フェーズ」で最適な振る舞いに遷移させられる。これが ECC の動的システムプロンプト注入アーキテクチャの中核的な価値である。

振る舞い規約：調査モードの4つの行動原則

調査コンテキストが定義する振る舞い（Behavior）は以下の4つである：

1. 結論を出す前に広く読む（Read widely before concluding）：1つのファイルや1つの説明だけを見て判断せず、関連するコード・ドキュメント・履歴を横断的に読む。
2. 明確化のための質問をする（Ask clarifying questions）：要件や疑問点が曖昧な場合、推測で進めずユーザーに確認を取る。
3. 進めながら発見を文書化する（Document findings as you go）：調査中に得た発見を後回しにせず、その場でメモ・文書として記録する。
4. 理解が明確になるまでコードを書かない（Don't write code until understanding is clear）：理解が曖昧なまま実装に進むことを禁止する。

これらの原則は、調査モードが「探索・調査・学習」を目的とし、「実装」を目的としないことを明確にする。特に原則4は、リサーチファースト開発の中核であり、早すぎる実装による手戻りコストを防ぐ効果がある。

調査プロセス：5ステップのループ

調査コンテキストは、調査を以下の5ステップの反復プロセスとして定式化している：

このループの要点は、仮説（ステップ3）が必ず証拠（ステップ4）を通ることにある。推測だけで結論を出さず、実際のコード・設定・テスト結果で裏付けを取ることで、誤った理解に基づく実装を未然に防ぐ。

なお、ECC のリポジトリには調査プロセスをそのまま体現したスクリプト群が存在する。たとえば scripts/consult.js、scripts/session-inspect.js、scripts/discussion-audit.js などは、コードベースやセッション記録の調査・分析を目的としており、調査モードの「読み・検証・文書化」の流れを自動化した実例と見なせる。

推奨ツールの使い分け

調査コンテキストは、調査目的に応じたツールの使い分けを定義している：

この使い分けのポイントは、「読む」と「検索する」と「外部に問い合わせる」の3層を分離していることである。コードの全体像は Read で、パターンやシンボルの所在は Grep/Glob で、外部ライブラリや仕様は WebSearch/WebFetch で、コードベース横断の質問は Explore エージェントへの Task で、という役割分担により、調査の効率と正確性が両立する。

ECC のリポジトリ自体も、Grep/Glob 的な調査ツールを活用できる構成になっている。たとえば scripts/lib には132以上の JS ライブラリが、src/llm には20の Python モジュールが配置されており、未知の機能を調査する際は Read と検索ツールを組み合わせて利用するのが調査モードの典型パターンである。

アウトプット規約：Findings first, recommendations second

調査コンテキストの最終セクションは、アウトプットの順序規約を定義している：

発見を最初に、推奨事項を次に（Findings first, recommendations second）

これは、調査結果を報告する際、まず検証済みの事実（発見）を提示し、その後でアクション（推奨）を提案するという順序を強制するものである。理由は2つある：

1. 読者（ユーザーや下流のエージェント）が、推奨事項の根拠となる事実を先に確認できる。
2. 推奨事項だけを先に述べると、その前提となる理解が共有されていないため誤解を生む。

この規約は、ECC のリポジトリ内の他の文書にも通底する原則である。たとえば調査・分析系のスクリプトやドキュメントは、事実の列挙を先に置き、その後にアクションを提案する構成を取るものが多く、この「証拠→結論」の順序がリサーチファースト開発の要となっている。

実践：調査コンテキストをシステムプロンプトとして組み込む

調査コンテキストは単独のファイルとしても有用だが、ECC の長文ガイド（the-longform-guide.md）で解説されている動的システムプロンプト注入の仕組みを使えば、セッション起動時に調査モードとして組み込める。

システムプロンプトの権限階層

the-longform-guide によれば、システムプロンプトはツール結果やユーザーメッセージよりも上位の権限を持つ（the-longform-guide.md）：

システムプロンプト（最高権限） > ユーザーメッセージ > ツール結果（最低権限）

そのため、--system-promptで調査コンテキストを注入すれば、そのセッション全体で調査モードの振る舞い規約が最も強い拘束力を持つことになる。CLAUDE.mdや.claude/rules/に常設するのではなく、必要なセッションだけに注入する「外科的（surgical）」な運用が推奨される。

CLI による注入コマンド

直接注入する場合：

claude --system-prompt "$(cat ~/.claude/contexts/research.md)"

日本語版を使用する場合：

claude --system-prompt "$(cat ~/.claude/contexts/research.md)" # 英語版 claude --system-prompt "$(cat docs/ja-JP/contexts/research.md)" # 日本語版（リポジトリ内）

alias による常時切り替え

the-longform-guide が示す実践的な設定として、モード別の alias を用意する方法がある（the-longform-guide.md）：

# 日常の開発 alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"' # PR レビューモード alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"' # 調査・探索モード alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

この設定により、claude-researchと打つだけで調査モードのセッションが起動し、claude-devで実装モードに切り替える、という流れで「調査→実装」をシームレスに遷移できる。

セットアップ手順

1. リポジトリのcontexts/ディレクトリ（英語版: contexts/research.md、日本語版: docs/ja-JP/contexts/research.md）をローカルの~/.claude/contexts/にコピーする。
2. 上記の alias 定義を~/.bashrcまたは~/.zshrcに追加する。
3. source ~/.bashrcで反映し、claude-researchを実行して動作確認する。

なお、調査コンテキストは Claude Code の--system-promptだけでなく、システムプロンプトを動的に注入できる他のハーネス（Codex、Opencode、Cursor 等）でも同様のパターンで利用できる。ECC はこれら複数ハーネス対応を方針としており（AGENTS.md）、コンテキストファイルはハーネス非依存のプレーンテキストとして設計されている。

調査モードの運用フロー例

調査コンテキストを実際の開発フローに組み込む例：

1. 要件受領: 未知の機能や既存コードベースへの変更依頼を受け取る。
2. claude-researchで調査セッションを開始: 調査モードの振る舞い規約が有効になる。
3. 5ステップの調査プロセスを実行: 質問の理解 → 関連コードの探索（Read/Grep/Glob）→ 仮説 → 証拠による検証 → 発見のまとめ。
4. Findings first で報告: 検証済みの発見を先に提示し、推奨事項を後に付す。
5. claude-devで実装セッションに切り替え: 調査結果に基づいて実装を開始する。

このフローにより、「調査と実装のモード混在」による質の低下（調査不足のまま書いたコード、実装意図が不明瞭な調査報告）を防げる。

まとめ

調査コンテキスト（contexts/research.md、日本語版docs/ja-JP/contexts/research.md）は、以下の要素で構成されるリサーチファースト開発の基盤である：

• モード定義: 探索・調査・学習モード、フォーカスは「行動の前に理解する」
• 4つの振る舞い規約: 広く読む / 質問する / 文書化する / 理解が明確になるまでコードを書かない
• 5ステップの調査プロセス: 質問理解 → 探索 → 仮説 → 証拠検証 → まとめ
• 推奨ツール: Read / Grep・Glob / WebSearch・WebFetch / Task（Explore エージェント）
• アウトプット規約: 発見を最初に、推奨事項を次に

ECC の動的システムプロンプト注入（claude --system-prompt "$(cat ~/.claude/contexts/research.md)"）と組み合わせれば、エージェントの行動様式をセッション単位で外科的に切り替えられる。調査フェーズと実装フェーズを明確に分離し、「理解してから動く」エージェントを構築したい開発者にとって、このコンテキストは即座に実戦投入できる最小構成のモード切り替え機構である。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC