コンテキストエンジニアリング ― AIに正しく状況を伝える3層設計術

「Cursorも Claude Codeも導入したのに、出力品質が思ったほど上がらない」 ― 現場でこう悩む開発リーダーは少なくない。原因の多くは、プロンプト設計ではなく、コンテキスト設計の不足にある。プロンプトエンジニアリングが「指示文の設計」だとすれば、コンテキストエンジニアリングは「AIに渡す前提情報の設計」だ。AIDDの上級者ほど、プロンプトよりコンテキストにこだわる。同じ「このバグを直して」でも、コードもエラーログも添えない場合と、該当コード30行＋エラーログ＋関連仕様書＋既存テスト＋直近関連PRを渡した場合で、返ってくる修正案の質は別次元だ。本稿では、コンテキストの3層構造、主要ツールでの設計方法、含めるべき情報・含めない情報、実践テクニック、RAGとの連携、4つの落とし穴、上達5ステップを整理する。

要点：AIの出力品質は、与えるコンテキストの質と量で9割決まる。プロジェクト規約・関連モジュール・直近作業の3層を意識し、「何を渡し、何を渡さないか」の設計が決定打になる。

1. なぜコンテキストが重要か ― 同じ質問でも答えの質が桁違い

コンテキストの重要性は具体例で見ると分かる。「このバグを直して」とコードもエラーログも添えずに依頼すると、AIは推測ベースの曖昧な提案しか返せない。一方で、該当コード30行・エラーログ・関連する仕様書・既存テストコード・直近の関連PRを渡すと、AIは具体的かつ的確な修正案を返してくる。AIの能力差ではなく、提供情報の差が出力品質を決める。プロンプトを磨いても、コンテキストが不足していれば品質は頭打ちになる。「プロンプトより先にコンテキストを整える」が、AIDD上達の王道だ。

💡 ポイント：「プロンプトよりコンテキストが9割」が現場感覚。プロンプト改善より先に、コンテキスト整備に投資するほうが、結果的に出力品質が上がる。

2. コンテキストの3層構造 ― プロジェクト・モジュール・タスク

コンテキストは3層で設計する。L1：プロジェクト全体は規約・設計書・スタックなど常に渡す前提情報。L2：関連モジュールは該当機能のコード・型定義・関連ドキュメント。L3：直近の作業は現在編集中のファイル・エラーログ・直近のコミット差分だ。良いコンテキストは3層を適切に組み合わせて渡すことで作られる。L1だけでは具体性に欠け、L3だけでは設計判断ができない。L1は常時、L2はタスクに応じて、L3は現在進行形を、それぞれ意識的に揃える設計が必要になる。

📊 経営判断のコツ：3層を意識した社内ガイドラインを作るだけで、組織全体のAIDD出力品質が底上げされる。最初に投資すべき領域。

3. 主要ツールにおけるコンテキスト設計 ― Claude Code・Cursor・Copilot

主要ツールごとにコンテキストの渡し方が異なる。Claude CodeはCLAUDE.mdがプロジェクト規約として機能し、ファイルツリーから関連ファイルを自動取得、サブエージェントで作業ごとにコンテキストを切り替える。Cursorは.cursorrulesがプロジェクトルール、@-mentionで関連ファイルを明示的に指定、インデックス機能で全体検索が可能。GitHub Copilotはワークスペース全体を自動的にインデックスし、@workspaceでプロジェクト文脈を呼び出す。ツールごとに「強み・弱み・ベストプラクティス」が違うため、自社の技術スタックと開発スタイルに応じて使い分ける。

⚠️ 注意：複数ツールを併用する組織は、規約ファイルが分散する。CLAUDE.mdと.cursorrulesの内容を同期する仕組み（半月に1回の手動同期、または自動変換スクリプト）を整える。

4. コンテキストに含めるべき情報・含めない情報

コンテキストには「必ず含める」「状況に応じて含める」「含めない方がいい」の3区分がある。必ず含めるのは、プロジェクト規約（言語・FW・ルール）、該当機能の仕様書、関連する既存コード、型定義・APIスキーマ。状況に応じて含めるのは、関連するテストコード、直近のPR・コミット、障害対応ログ、顧客からの問い合わせ。含めない方がいいのは、機密情報（APIキー・個人情報）、無関係な大量のドキュメント、古い・誤った情報、矛盾する複数の仕様書だ。「全部渡せばいい」は誤解で、ノイズの多いコンテキストは出力品質を下げる。

💡 ポイント：「含めない情報」を意識的に決める習慣が、出力品質を底上げする。「全部渡す」より「絞る」方が高度なスキル。

5. テクニック① プロジェクト規約をSource of Truthに

コンテキスト設計の第一歩は、プロジェクト規約をSource of Truth（正本）として整備することだ。CLAUDE.mdまたは.cursorrulesに、技術スタック（言語・FW・DB・テスト）、コーディング規約（命名・APIレスポンス形式・エラーハンドリング）、構造（ディレクトリ・モジュール）を記載する。これがあると、毎回のプロンプトで規約を再記述する必要がなく、出力品質も安定する。規約ファイルは「作って終わり」ではなく、半年に1回更新するサイクルで運用する。新人エンジニアのオンボーディング教材としても活用でき、二重の効果がある。

📊 経営判断のコツ：規約ファイル整備は「技術部門の作業」ではなく「組織能力への投資」。CTOが優先度を上げて旗を振ることで、現場が動く。

6. テクニック② 階層的にコンテキストを渡す

コンテキストは階層的に渡すと品質が上がる。第1層はプロジェクト規約（常時参照）、第2層はモジュール仕様（該当機能のみ）、第3層は具体タスク（現在の指示）。これを毎回意識的に組み立てる。プロジェクト規約をCLAUDE.mdで常時参照させ、モジュール仕様は@-mentionや明示的指定で渡し、具体タスクはプロンプト本文で記述する。この階層化により、AIは適切なレベルの抽象度で思考でき、的外れな出力が減る。「全部一緒くたに渡す」のではなく「層を分けて渡す」が、上級テクニックの第一歩だ。

⚠️ 注意：「階層を意識せず一気に渡す」プロンプトは、AIが優先順位を見失う。文脈を整理してから渡すのが上達の近道。

7. テクニック③④ 不要な情報を削る・差分で渡す

3つ目のテクニックは「不要な情報を削る」こと。トークンには上限があり、ボイラープレートのみのファイル、古いコメント、未使用のテストデータなどはノイズになる。4つ目は「差分でコンテキストを渡す」こと。「直近のコミットで以下を変更：AuthContext を Provider 経由に変更、セッション管理が変わった」のように、変化点を伝える。「全部渡す」のではなく「変化点を伝える」のが上級者だ。これら2テクニックを組み合わせると、コンテキストのトークン効率が劇的に改善し、出力品質も上がる。

💡 ポイント：「コンテキストを削る」スキルは、慣れるほど効果が大きい。「これは本当に必要か」を毎回問う習慣を作る。

8. RAGとコンテキストエンジニアリング ― 動的注入の仕組み

RAG（Retrieval-Augmented Generation）は、外部知識ベースから関連情報を取得してプロンプトに混ぜる手法だ。典型構成は「ユーザー質問 → ベクトル検索（社内Wiki・コードベース）→ 関連情報抽出 → プロンプトに混入 → AIが回答」の流れ。RAGが活きるのは、社内ドキュメントが膨大、規約・仕様が頻繁に更新される、全社共通のナレッジが必要な場面だ。Notion・Confluence・社内GitHubなどをRAG基盤に組み込むと、コンテキスト設計が動的かつスケーラブルになる。手動で「これも添付、あれも添付」を繰り返す必要がなくなる。

📊 経営判断のコツ：RAG基盤の整備は半年〜1年スパンの投資が必要だが、組織全体のコンテキスト効率が桁違いに上がる。中規模以上の組織では検討価値が高い。

9. コンテキスト設計の4つの落とし穴

頻発する落とし穴は4つ。落とし穴1：詰め込みすぎ ― 全ファイルをコンテキストに入れるとトークン上限を超え品質が下がる。関連する5〜10ファイルに絞る。落とし穴2：矛盾する情報 ― 古い仕様書と新しい仕様書を両方渡すとAIが混乱する。Source of Truthを明確にし古いものは削る。落とし穴3：機密の混入 ― APIキー・本番DBの中身を渡すと漏洩リスク。ダミーデータ・モックを使う。落とし穴4：暗黙知の前提 ― チーム内で当然視されている仕様を書かないとAIには伝わらない。全部書く。これら4つの落とし穴を回避するだけで、コンテキスト品質が大きく上がる。

⚠️ 注意：4落とし穴のうち「機密の混入」は最も重大。一度漏洩すると組織信用に直結するため、DLP・利用ガイドラインで対策する。

10. 上達ロードマップと経営観点の論点

上達は5ステップで進める。Step 1はプロジェクト規約ファイル（CLAUDE.md / .cursorrules）を作る。Step 2は関連ファイル選定の基準を作り「何を、なぜ含めるか」を明文化する。Step 3は差分ベースでの渡し方を習得し、変化点だけを伝える練習を積む。Step 4はRAGを部分導入し社内Wikiや過去PRをベクトル検索する。Step 5はチームで運用しナレッジ共有・規約改善のサイクルを回す。経営層が押さえる論点は3つ。第1にプロジェクト規約整備をCTO直轄プロジェクトとして位置づける、第2にRAG基盤投資をIT予算に組み込む、第3にコンテキスト設計を評価制度に反映する。これらが揃うと、組織能力としてコンテキストエンジニアリングが定着する。

💡 ポイント：5ステップは個人ではなく組織として進める設計が重要。CTOが旗を振り、各チームに展開していくことで、組織能力として定着する。

まとめ

コンテキストエンジニアリングはAIDDの隠れた本丸で、出力品質の9割を決める。プロジェクト規約・関連モジュール・直近作業の3層構造を意識し、Source of Truthを整備して矛盾と機密を排除する。階層的にコンテキストを渡し、不要な情報を削り、差分で変化点を伝えるのが上級テクニックだ。RAGで社内ナレッジを動的注入する仕組みを部分導入し、最終的にチームで規約を運用するサイクルを回す。経営層は規約整備・RAG基盤投資・評価制度反映の3点を主導し、コンテキスト設計を組織能力として育てる視点が必要。「プロンプトよりコンテキスト」を組織の合言葉にすることが、AIDD成熟度の決定打になる。

コンテキスト設計チェックリスト

• [ ] CLAUDE.md / .cursorrules が整備されSource of Truthとして機能している
• [ ] 3層構造（規約・モジュール・タスク）を意識した渡し方ができている
• [ ] 関連ファイル選定の基準が明文化されている
• [ ] 機密情報（APIキー・本番DB）はコンテキストに含めない運用が徹底されている
• [ ] 古い・矛盾する情報を排除する仕組みがある
• [ ] 差分でコンテキストを渡す習慣がチームに浸透している
• [ ] RAG基盤（Notion・Confluence等のベクトル検索）が部分導入されている
• [ ] 規約ファイルの更新サイクル（半年に1回）が運用されている
• [ ] 暗黙知を明文化する文化がある
• [ ] コンテキスト設計が評価制度に反映されている

IT COMPASSのAI駆動開発支援

IT COMPASS では、CTO経験者が外部CTO・技術顧問として、コンテキスト設計とナレッジ整備を伴走支援しています。

支援できること

• 🎯 コンテキスト設計とドキュメント整備：CLAUDE.md・.cursorrules・規約整備、3層構造の組織導入
• 🛠 ツール選定とパイロット設計：Claude Code / Cursor / GitHub Copilot 等の評価・PoC設計
• 🔌 RAG・MCP連携設計：社内ナレッジとAIの接続設計、ベクトル検索基盤導入
• 👥 開発組織の再設計：AIエージェントを前提としたチーム編成・役割定義・評価制度
• 🛡 ガバナンス・セキュリティ整備：AI利用ポリシー、権限設計、知財・契約ルール

こんな方におすすめ

• AI出力の品質が安定しないと感じているCTO・開発リーダーの方
• 社内ナレッジをAIに活かす仕組みを作りたい情シス・開発マネジメント層の方
• プロジェクト規約を整備してAIDDの再現性を上げたいテックリードの方

お問い合わせ

スポット相談（1回／契約不要・最短当日）から、月額契約での継続伴走まで、フェーズに応じて柔軟に対応します。

👉 IT COMPASS お問い合わせフォーム

経営と技術の両面から、御社のAI駆動開発を一緒に設計しましょう。

監修者

西脇　靖紘（lanitech合同会社 代表取締役CEO 兼 CTO）

「テクノロジーで人と社会をつなぐ」をミッションに、企業のDX推進・AI導入支援から、デジタル教育・地域共創まで幅広く活動。エンジニアとしての現場経験と経営視点を活かし、外部CTO・AIコンサルティングなどを通じて企業のデジタル変革を支援している。著書はオライリー・ジャパンから複数刊行。

 
lanitech合同会社 webサイト