在 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 來提示建立新功能或 bug 修復的實施計劃。生成實施計劃是一個迭代過程，可能需要多輪完善才能確保其完整和準確。

透過用於規劃的自定義代理，您可以建立一個具有規劃特定指南和工具的專用個性（例如，對程式碼庫的只讀訪問）。它們還可以捕獲專案的特定工作流，用於頭腦風暴、研究和協作。

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: ['fetch', 'githubRepo', 'problems', 'usages', 'search', 'todos', 'runSubagent', '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:runSubagent 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. 現在，您可以在 Chat 檢視中選擇 **plan** 自定義代理，並輸入一個實現新功能的任務。它將生成一個包含基於提供的模板的實施計劃的響應。

   例如，輸入以下提示以建立新功能的實施計劃：新增使用者身份驗證，支援電子郵件和密碼，包括註冊、登入、登出和密碼重置功能。

   您還可以引用 GitHub issue 以提供特定上下文：Implement the feature from issue #43，在這種情況下，代理將獲取 issue 描述和評論以得出需求。

4. 可選地，建立一個提示檔案 .github/prompts/plan.prompt.md，該檔案呼叫計劃代理並指示代理從提供的功能請求中建立實施計劃。

   以下 plan-qna.prompt.md 檔案為規劃提示提供了多樣化的起點，使用相同的 TDD 工作流，但增加了澄清步驟。

   ---
   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. 在 Chat 檢視中，輸入 /plan-qna 斜槓命令以呼叫澄清規劃提示，並在提示中提供有關您要在專案中實現的功能的詳細資訊。

   例如，輸入以下提示：/plan-qna 新增一個客戶詳細資訊頁面，用於顯示和編輯客戶資訊

   代理將提出澄清問題，以更好地理解需求，然後再建立實施計劃，從而減少任何誤解。

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

工作流最佳化

代理之間的交接：使用交接來建立引導式過渡，並在規劃、實施和審查代理之間實現端到端開發工作流。

實現反饋迴圈：持續驗證 AI 是否正確理解您的上下文。提出澄清性問題，並在發生誤解時儘早糾正。

使用增量複雜性：逐步構建功能，在新增複雜性之前驗證每個步驟。這可以防止複合錯誤並維護可工作的程式碼。

分離關注點：為不同的活動（規劃與實施與審查）使用不同的代理，以保持專注、相關的上下文。

版本化您的上下文：使用 git 來跟蹤上下文工程設定的更改，允許您回滾有問題的更改並瞭解什麼最有效。

要避免的反模式

上下文傾倒：避擴音供過多的、不集中的資訊，這些資訊不能直接幫助決策。

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

忽略驗證：不要假設 AI 正確理解您的上下文。在進行復雜實現之前，務必測試其理解能力。

一刀切：不同的團隊成員或專案階段可能需要不同的上下文配置。在您的方法中保持靈活性。

衡量成功

成功的上下文工程設定應帶來：

• 減少的來回往復：減少糾正或重定向 AI 響應的次數
• 一致的程式碼質量：生成的程式碼遵循既定的模式和約定
• 更快的實施：花在解釋上下文和需求上的時間更少
• 更好的架構決策：AI 提出的解決方案與專案目標和約束一致

擴充套件上下文工程

面向團隊：透過版本控制共享上下文工程設定，並建立團隊約定來維護共享上下文。

面向大型專案：考慮使用指令檔案建立上下文層次結構，包括專案級、模組級和功能級上下文層。

面向長期專案：建立定期的上下文審查週期，以使文件保持最新並刪除過時的資訊。

面向多個專案：建立可在不同程式碼庫和域中採用的可重用模板和模式。

透過遵循這些實踐並不斷完善您的方法，您將開發出一種上下文工程工作流，該工作流可以增強 AI 輔助開發，同時保持程式碼質量和專案一致性。

相關資源

瞭解有關在 VS Code 中自定義 AI 的更多資訊

• 指令檔案
• 自定義代理
• 提示檔案