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/agents/plan.agent.md を作成します。

   計画エージェントは計画担当のペルソナを定義し、エージェントに実装タスクを実行させず、実装計画の作成に集中するように指示します。計画が完了した後に実装エージェントに引き継ぐための ハンドオフ を指定できます。

   カスタムエージェントを作成するには、コマンドパレットで Chat: New Custom Agent コマンドを実行します。

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

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

   以下の plan.agent.md ファイルは、計画カスタムエージェントと TDD 実装エージェントへのハンドオフのための出発点を提供します。

   ---
   description: 'Architect and planner to create detailed implementation plans.'
   tools: ['web/fetch', 'read/problems', 'search/codebase', 'search/usages', 'todo', 'agent', 'github/github-mcp-server/get_issue', 'github/github-mcp-server/get_issue_comments', 'github/github-mcp-server/list_issues']
   handoffs:
   - label: Start Implementation
       agent: tdd
       prompt: Now implement the plan outlined above using TDD principles.
       send: true
   ---
   # Planning Agent
   
   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. Run #tool:agent tool, instructing the agent to work autonomously without pausing for user feedback.
   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 カスタムエージェントを選択し、新しい機能を実装するためのタスクを入力できるようになりました。提供されたテンプレートに基づいた実装計画を含む回答が生成されます。

   例えば、次のプロンプトを入力して、新しい機能の実装計画を作成します: Add user authentication with email and password, including registration, login, logout, and password reset functionality（メールとパスワードによるユーザー認証機能を追加。登録、ログイン、ログアウト、パスワードリセット機能を含む）

   GitHub Issue を参照して具体的なコンテキストを提供することもできます: Implement the feature from issue #43（Issue #43 の機能を実装）。この場合、エージェントは Issue の説明とコメントを取得して要件を導き出します。

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

   以下の plan-qna.prompt.md ファイルは、同じワークフローを使用しつつ明確化のステップを追加した、バリエーションのある計画プロンプトの出発点を提供します。

   ---
   agent: 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 add a customer details page for displaying and editing customer information（顧客情報を表示・編集するための顧客詳細ページを追加）

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

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

実装計画を作成して洗練させた後、実装計画からコードを生成することで、AI を使用して機能を実装できるようになります。

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

   大規模または複雑な機能の場合は、Agent に切り替えて、実装計画をファイル（例: <my-feature>-plan.md）に保存するか、該当する GitHub Issue へのコメントとして追加するように指示します。その後、新しいチャットを開き、プロンプトで実装計画ファイルを参照してチャットコンテキストをリセットできます。

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

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

   ヒント

   Agent は、マルチステップのタスクを実行し、計画とプロジェクトのコンテキストに基づいて目標を最善の方法で達成するように最適化されています。計画ファイルを提供するか、プロンプトで参照するだけで済みます。

3. よりカスタマイズされたワークフローのために、計画に基づいたコードの実装に特化した カスタムエージェント .github/agents/implement.agent.md を作成します。

   以下の tdd.agent.md ファイルは、テスト駆動型実装用カスタムエージェントの出発点を提供します。

   ---
   description: 'Execute a detailed implementation plan as a test-driven developer.'
   ---
   # TDD Implementation Agent
   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 がより良いアーキテクチャや実装の決定を下せるようにするための情報を優先します。

一貫したパターンを使用する: コーディング規則、命名パターン、アーキテクチャ上の決定を確立し、ドキュメント化することで、AI が一貫したコードを生成できるようにします。

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

ワークフローの最適化

エージェント間のハンドオフ: ハンドオフ を使用して、計画、実装、レビューエージェント間でのガイド付きの移行とエンドツーエンドの開発ワークフローを実装します。

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

段階的な複雑性を使用する: 機能を段階的に構築し、複雑さを加える前に各ステップを検証してください。これにより、エラーの累積を防ぎ、動作するコードを維持できます。

懸案事項を分離する: 集中力があり関連性の高いコンテキストを維持するために、アクティビティ（計画対実装対レビュー）ごとに異なるエージェントを使用します。

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

キャッシュパフォーマンスを確認する: エージェントデバッグログ を使用して、プロンプトのキャッシュヒット率とトークン使用量を確認してください。キャッシュパフォーマンスが良いということは、コンテキスト設定がモデルプロバイダーによって以前のリクエストプレフィックスを再利用できるように構造化されていることを意味し、レイテンシとトークンコストを削減します。

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

コンテキストのダンプ: 意思決定に直接役立たない過剰で焦点の定まらない情報の提供は避けてください。

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

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

汎用的な手法: チームメンバーやプロジェクトフェーズによって、必要なコンテキスト設定が異なる場合があります。柔軟に対応してください。

エージェントチェーンの過剰エンジニアリング: 深くネストされたサブエージェントワークフローや過剰なツール呼び出しは、トークン使用量と クレジット消費 を倍増させます。エージェントチェーンは実用的な範囲で浅く保ち、各エージェントが実際に必要とするツールに限定してください。

成功の測定

成功したコンテキストエンジニアリング設定は、以下の結果をもたらすはずです。

• やり取りの削減: AI の回答を修正または再指示する必要性の減少
• 一貫したコード品質: 生成されたコードが確立されたパターンや規則に従っている
• 迅速な実装: コンテキストや要件の説明に費やす時間の短縮
• より良いアーキテクチャの決定: プロジェクトの目標と制約に沿ったソリューションが AI から提案される

コンテキストエンジニアリングの拡大

チームの場合: バージョン管理を通じてコンテキストエンジニアリングの設定を共有し、共有コンテキストを維持するためのチームの慣習を確立します。

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

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

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

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

関連リソース

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

• 指示ファイル
• カスタムエージェント
• プロンプト ファイル