在 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 問題作為情境，請務必安裝 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 問題來提供特定情境：Implement the feature from issue #43，在這種情況下，代理將獲取問題描述和註解以提出需求。

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 問題。然後您可以開啟一個新的聊天，並在您的提示中引用實作計畫檔案以重置聊天情境。

2. 您現在可以指示代理根據您在上一步中建立的實作計畫來實作該功能。

   例如，輸入一個聊天提示，例如 implement #<my-plan>.md，它引用了實作計畫檔案。

   提示

   代理經過優化，可用於執行多步驟任務，並根據計畫和您的專案情境找出實現目標的最佳方式。您只需要提供計畫檔案或在您的提示中引用它。

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 在產生程式碼時應考慮的相關外部文件、API 或標準。

工作流程優化

代理之間的交接：使用 交接 來建立引導式轉換，並在規劃、實作和審查代理之間實作端對端開發工作流程。

實作回饋循環：持續驗證 AI 是否正確理解您的情境。提出澄清問題並在出現誤解時及早糾正。

使用增量複雜度：增量地建置功能，在增加複雜度之前驗證每個步驟。這可以防止複合錯誤並維持運作中的程式碼。

分離關注點：對不同活動（規劃、實作、審查）使用不同的代理，以維持專注且相關的情境。

情境版本控制：使用 git 追蹤情境工程設定的變更，讓您可以回復有問題的變更並了解什麼最有效。

應避免的反模式

情境傾瀉：避免提供過多、不集中的資訊，這些資訊對決策沒有直接幫助。

不一致的指導：確保所有文件都符合您選擇的架構模式和編碼標準。

忽略驗證：不要假設 AI 正確理解您的情境。在進行複雜的實作之前，務必測試其理解。

一體適用：不同的團隊成員或專案階段可能需要不同的情境配置。在您的方法中保持靈活。

衡量成功

成功的情境工程設定應帶來以下結果：

• 減少來回修正：減少校正或重新導向 AI 回應的需求
• 一致的程式碼品質：產生的程式碼遵循既定的模式和慣例
• 更快的實作：減少解釋情境和需求的時間
• 更好的架構決策：AI 建議的解決方案符合專案目標和限制

情境工程的規模化

對於團隊：透過版本控制共享情境工程設定，並建立團隊慣例以維護共享情境。

對於大型專案：考慮使用 指示檔案 建立情境層次結構，包含專案範圍、模組特定和功能特定的情境層。

對於長期專案：建立定期情境審查週期，以保持文件最新並移除過時資訊。

對於多個專案：建立可在不同程式碼庫和領域中採用的可重複使用範本和模式。

透過遵循這些實務並持續精煉您的方法，您將開發出一個情境工程工作流程，在維持程式碼品質和專案一致性的同時，增強 AI 輔助開發。

相關資源

深入了解如何在 VS Code 中自訂 AI

• 指示檔案
• 自定義代理人
• 提示詞檔案