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の説明とコメントを取得して要件を作成します。

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 のようなチャットプロンプトを入力し、実装計画ファイルを参照します。

   ヒント

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

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

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

   ---
   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がコード生成時に考慮すべき、関連する外部ドキュメント、API、標準へのリンクを提供してください。

ワークフローの最適化

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

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

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

関心の分離: 活動ごとに異なるエージェント（計画 vs 実装 vs レビュー）を使用して、焦点を絞った関連性の高いコンテキストを維持してください。

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

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

コンテキストのダンプ（丸投げ）: 意思決定に直接役立たない過剰で焦点の定まっていない情報を与えることは避けてください。

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

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

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

成功の測定

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

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

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

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

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

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

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

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

関連リソース

VS CodeにおけるAIのカスタマイズについてさらに詳しく学ぶ

• インストラクションファイル
• カスタムエージェント
• プロンプト ファイル