VS Code でコンテキストエンジニアリングフローをセットアップする

このガイドでは、カスタム指示、チャットモード、プロンプトファイルを使用して、VS Code でコンテキストエンジニアリングのワークフローをセットアップする方法を説明します。

コンテキストエンジニアリングは、生成されるコードの品質と精度を向上させるために、AI エージェントにターゲットとなるプロジェクト情報を提供する体系的なアプローチです。カスタム指示、実装計画、コーディングガイドラインを通じて不可欠なプロジェクトコンテキストをキュレートすることで、AI はより良い意思決定を行い、精度を向上させ、インタラクション全体で永続的な知識を維持することができます。

コンテキストエンジニアリングのワークフロー

VS Code におけるコンテキストエンジニアリングのハイレベルなワークフローは、以下のステップで構成されます。

1. プロジェクト全体のコンテキストをキュレートする: カスタム指示を使用して、関連するドキュメント (例: アーキテクチャ、設計、貢献者ガイドライン) をすべてのエージェントのインタラクションのコンテキストとして含めます。
2. 実装計画を生成する: カスタムチャットモードとプロンプトを使用して計画ペルソナを作成し、詳細な機能実装計画を生成します。
3. 実装コードを生成する: カスタム指示を使用して、コーディングガイドラインに準拠した実装計画に基づいてコードを生成します。

これらのステップを実行する中で、チャットでのフォローアッププロンプトによって出力を反復的に改善することができます。

次の図は、VS Code におけるコンテキストエンジニアリングのワークフローを示しています。

ステップ 1: プロジェクト全体のコンテキストをキュレートする

AI エージェントをプロジェクトの具体的な内容に慣れさせるために、製品ビジョン、アーキテクチャ、その他の関連ドキュメントなどの主要なプロジェクト情報を収集し、カスタム指示を通じてチャットコンテキストとして追加します。カスタム指示を使用することで、エージェントがこのコンテキストに常にアクセスできるようになり、各チャットインタラクションで再学習する必要がなくなります。

これが役立つ理由: エージェントはこの情報をコードベースで見つけることができますが、コメントの中に埋もれていたり、複数のファイルに散らばっていたりする可能性があります。最も重要な情報の簡潔な要約を提供することで、エージェントが常に意思決定のために重要なコンテキストを利用できるようにします。

1. 関連するプロジェクトドキュメントをリポジトリの Markdown ファイルで記述します。例えば、PRODUCT.md、ARCHITECTURE.md、CONTRIBUTING.md ファイルを作成します。

   ヒント

   既存のコードベースがある場合は、AI を使用してこれらのプロジェクトドキュメントファイルを生成できます。生成されたドキュメントファイルをレビューおよび修正して、正確性と完全性を確認してください。

   • プロジェクト全体のアーキテクチャを記述した ARCHITECTURE.md (最大 2 ページ) ファイルを生成します。
   • プロジェクトの製品機能を記述した PRODUCT.md (最大 2 ページ) ファイルを生成します。
   • プロジェクトへの貢献のための開発者ガイドラインとベストプラクティスを記述した CONTRIBUTING.md (最大 1 ページ) ファイルを生成します。

2. リポジトリのルートに .github/copilot-instructions.md 指示ファイルを作成します。

   このファイル内の指示は、すべてのチャットインタラクションに AI エージェントのコンテキストとして自動的に含まれます。

3. プロジェクトのコンテキストとガイドラインを含む、エージェント向けのハイレベルな概要を提供します。Markdown リンクを使用して、関連する補足ドキュメントファイルを参照します。

   次の .github/copilot-instructions.md ファイルの例は、開始点となります。

   # [Project Name] Guidelines
   
   * [Product Vision and Goals](../PRODUCT.md): Understand the high-level vision and objectives of the product to ensure alignment with business goals.
   * [System Architecture and Design Principles](../ARCHITECTURE.md): Overall system architecture, design patterns, and design principles that guide the development process.
   * [Contributing Guidelines](../CONTRIBUTING.md): Overview of the project's contributing guidelines and collaboration practices.
   
   Suggest to update these documents if you find any incomplete or conflicting information during your work.
   

ステップ 2: 実装計画を作成する

プロジェクト固有のコンテキストが整ったら、AI を使用して新しい機能やバグ修正の実装計画の作成を促すことができます。実装計画の生成は反復的なプロセスであり、完全かつ正確であることを保証するために複数回の修正が必要になる場合があります。

計画用のカスタムチャットモードを使用すると、計画固有のガイドラインとツール (例: コードベースへの読み取り専用アクセス) を持つ専用のペルソナを作成できます。また、プロジェクトやチームのブレインストーミング、調査、コラボレーションのための特定のワークフローをキャプチャすることもできます。

1. 実装計画ドキュメントの構造とセクションを定義する計画ドキュメントテンプレート plan-template.md を作成します。

   テンプレートを使用することで、エージェントが必要なすべての情報を収集し、一貫した形式で提示することを保証します。これにより、計画から生成されるコードの品質も向上します。

   次の plan-template.md ファイルは、実装計画テンプレートのサンプル構造を提供します。

   ---
   title: [Short descriptive title of the feature]
   version: [optional version number]
   date_created: [YYYY-MM-DD]
   last_updated: [YYYY-MM-DD]
   ---
   # Implementation Plan: <feature>
   [Brief description of the requirements and goals of the feature]
   
   ## Architecture and design
   Describe the high-level architecture and design considerations.
   
   ## Tasks
   Break down the implementation into smaller, manageable tasks using a Markdown checklist format.
   
   ## Open questions
   Outline 1-3 open questions or uncertainties that need to be clarified.
   

2. 計画ペルソナを定義する計画チャットモード .github/chatmodes/plan.chatmode.md を作成します。計画モードでは、エージェントは実装タスクを実行せず、実装計画の作成に集中するように指示されます。

   チャットモードを作成するには、コマンドパレットで Chat: Configure Chat Modes > Create New custom chat mode file コマンドを実行します。

   コンテキストのために GitHub Issues にアクセスしたい場合は、GitHub MCP サーバーを必ずインストールしてください。

   model メタデータプロパティを、推論と深い理解に最適化された言語モデルを使用するように構成することをお勧めします。

   次の plan.chatmode.md ファイルは、計画チャットモードの開始点となります。

   ---
   description: 'Architect and planner to create detailed implementation plans.'
   tools: ['fetch', 'githubRepo', 'problems', 'usages', 'search', 'todos', 'github/github-mcp-server/get_issue', 'github/github-mcp-server/get_issue_comments', 'github/github-mcp-server/list_issues']
   ---
   # Planning Mode
   
   You are an architect focused on creating detailed and comprehensive implementation plans for new features and bug fixes. Your goal is to break down complex requirements into clear, actionable tasks that can be easily understood and executed by developers.
   
   ## Workflow
   
   1. Analyze and understand: Gather context from the codebase and any provided documentation to fully understand the requirements and constraints.
   2. Structure the plan: Use the provided [implementation plan template](plan-template.md) to structure the plan.
   3. Pause for review: Based on user feedback or questions, iterate and refine the plan as needed.
   

3. これで、チャットビューで plan チャットモードを選択し、新しい機能の実装タスクを入力できます。提供されたテンプレートに基づいて実装計画を含む応答を生成します。

   例えば、新しい機能の実装計画を作成するために、次のプロンプトを入力します: 登録、ログイン、ログアウト、パスワードリセット機能を含む、メールとパスワードによるユーザー認証を追加する。

   また、特定のコンテキストを提供するために GitHub issue を参照することもできます: issue #43 から機能を実装する。この場合、エージェントは issue の説明とコメントを取得して要件を決定します。

4. オプションで、計画モードを呼び出し、提供された機能要求から実装計画を作成するようにエージェントに指示するプロンプトファイル .github/prompts/plan.prompt.md を作成します。

   次の plan-qna.prompt.md ファイルは、同じワークフローを使用しながら、明確化のステップを追加することで、計画プロンプトの多様な開始点を提供します。

   ---
   mode: plan
   description: Create a detailed implementation plan.
   ---
   Briefly analyze my feature request, then ask me 3 questions to clarify the requirements. Only then start the planning workflow.
   

5. チャットビューで、/plan-qna スラッシュコマンドを入力して、明確化の計画プロンプトを呼び出し、実装したい機能の詳細をプロンプトで提供します。

   例えば、次のプロンプトを入力します: /plan-qna 顧客情報を表示および編集するための顧客詳細ページを追加する

   エージェントは、実装計画を作成する前に要件をよりよく理解するために明確化の質問をし、誤解を減らします。

ステップ 3: 実装コードを生成する

実装計画を生成して修正したら、AI を使用して実装計画からコードを生成することで機能を実装できます。

1. 小規模なタスクの場合、エージェントに実装計画に基づいてコードを生成するように促すことで、機能を直接実装できます。

   大規模または複雑な機能の場合、Agent モードに切り替えて、実装計画をファイル (例: <my-feature>-plan.md) に保存するか、言及された GitHub issue にコメントとして追加するように促すことができます。その後、新しいチャットを開き、プロンプトで実装計画ファイルを参照してチャットコンテキストをリセットできます。

2. これで、前のステップで作成した実装計画に基づいて機能を実装するようにエージェントに指示できます。

   例えば、implement #<my-plan>.md のようなチャットプロンプトを入力し、実装計画ファイルを参照します。

   ヒント

   エージェントモードは、複数ステップのタスクを実行し、計画とプロジェクトのコンテキストに基づいて目標を達成するための最善の方法を把握することに最適化されています。計画ファイルを提供するだけで、またはプロンプトで参照するだけで十分です。

3. よりカスタマイズされたワークフローのために、計画に基づいてコードを実装することに特化したカスタムチャットモード .github/chatmodes/implement.chatmode.md を作成します。

   次の tdd.chatmode.md ファイルは、テスト駆動実装チャットモードの開始点となります。

   ---
   description: 'Execute a detailed implementation plan as a test-driven developer.'
   ---
   # TDD Implementation Mode
   Expert TDD developer generating high-quality, fully tested, maintainable code for the given implementation plan.
   
   ## Test-driven development
   1. Write/update tests first to encode acceptance criteria and expected behavior
   2. Implement minimal code to satisfy test requirements
   3. Run targeted tests immediately after each change
   4. Run full test suite to catch regressions before moving to next task
   5. Refactor while keeping all tests green
   
   ## Core principles
   * Incremental Progress: Small, safe steps keeping system working
   * Test-Driven: Tests guide and validate behavior
   * Quality Focus: Follow existing patterns and conventions
   
   ## Success criteria
   * All planned tasks completed
   * Acceptance criteria satisfied for each task
   * Tests passing (unit, integration, full suite)
   

   ヒント

   小規模な言語モデルは、明示的な指示に従ってコードを生成するのが得意であるため、implement チャットモードは、model プロパティを言語モデルに設定することで恩恵を受けます。

ベストプラクティスと一般的なパターン

これらのベストプラクティスに従うことで、持続可能で効果的なコンテキストエンジニアリングのワークフローを確立できます。

コンテキスト管理の原則

小さく始めて反復する: 最小限のプロジェクトコンテキストから始め、観察された AI の動作に基づいて徐々に詳細を追加します。集中力を薄める可能性のあるコンテキストの過負荷を避けます。

コンテキストを新鮮に保つ: コードベースの進化に合わせて、プロジェクトドキュメントを定期的に監査および更新します (エージェントを使用して)。古いコンテキストは、時代遅れまたは不正確な提案につながります。

漸進的なコンテキスト構築を使用する: ハイレベルな概念から始め、包括的な情報で AI を最初から圧倒するのではなく、徐々に詳細を追加します。

コンテキストの分離を維持する: コンテキストの混同と混乱を防ぐために、異なる種類の作業 (計画、コーディング、テスト、デバッグ) を別々のチャットセッションに保ちます。

ドキュメント戦略

生きているドキュメントを作成する: カスタム指示、チャットモード、テンプレートを進化するリソースとして扱います。観察された AI の間違いや欠点に基づいてそれらを修正します。

意思決定コンテキストに焦点を当てる: 網羅的な技術詳細よりも、AI がより良いアーキテクチャおよび実装の意思決定を行うのに役立つ情報を優先します。

一貫したパターンを使用する: コーディング規約、命名パターン、アーキテクチャの決定を確立および文書化し、AI が一貫したコードを生成するのに役立てます。

外部知識を参照する: AI がコードを生成する際に考慮すべき関連する外部ドキュメント、API、または標準にリンクします。

ワークフローの最適化

フィードバックループを実装する: AI がコンテキストを正しく理解していることを継続的に検証します。明確化の質問をし、誤解が生じた場合は早期に修正します。

漸進的な複雑さを使用する: 各ステップを検証してから複雑さを追加することで、機能を漸進的に構築します。これにより、エラーの複合を防止し、動作するコードを維持します。

懸念を分離する: 異なる活動 (計画 vs 実装 vs レビュー) に異なるチャットモードを使用し、焦点を絞った関連性のあるコンテキストを維持します。

コンテキストをバージョン管理する: git を使用してコンテキストエンジニアリングのセットアップに対する変更を追跡し、問題のある変更を元に戻したり、何が最適に機能するかを理解したりできるようにします。

避けるべきアンチパターン

コンテキストのダンプ: 意思決定に直接役立たない、過剰で焦点の定まらない情報を提供することは避けます。

一貫性のないガイダンス: すべてのドキュメントが選択したアーキテクチャパターンとコーディング標準に沿っていることを確認します。

検証の怠り: AI がコンテキストを正しく理解していると仮定しないでください。複雑な実装に進む前に、常に理解度をテストしてください。

万能なアプローチ: 異なるチームメンバーやプロジェクトフェーズでは、異なるコンテキスト構成が必要になる場合があります。アプローチに柔軟性を持たせてください。

成功の測定

成功したコンテキストエンジニアリングのセットアップは、次のような結果をもたらすはずです。

• やり取りの削減: AI の応答を修正したり、方向を転換したりする必要が減る
• 一貫したコード品質: 生成されたコードは確立されたパターンと規約に従う
• より速い実装: コンテキストと要件の説明に費やす時間が減る
• より良いアーキテクチャ上の決定: AI はプロジェクトの目標と制約に合致するソリューションを提案する

コンテキストエンジニアリングのスケーリング

チーム向け: バージョン管理を通じてコンテキストエンジニアリングのセットアップを共有し、共有コンテキストを維持するためのチーム規約を確立します。

大規模プロジェクト向け: 指示ファイルを使用して、プロジェクト全体、モジュール固有、機能固有のコンテキスト層を持つコンテキスト階層を作成することを検討します。

長期プロジェクト向け: ドキュメントを最新の状態に保ち、古い情報を削除するために、定期的なコンテキストレビューサイクルを確立します。

複数プロジェクト向け: 異なるコードベースやドメイン全体で採用できる再利用可能なテンプレートとパターンを作成します。

これらのプラクティスに従い、アプローチを継続的に改善することで、コード品質とプロジェクトの一貫性を維持しながら、AI 支援開発を強化するコンテキストエンジニアリングのワークフローを開発できます。

関連リソース

VS Code での AI のカスタマイズの詳細

• 指示ファイル
• チャットモード
• プロンプトファイル