在 VS Code 中建立情境工程流程

本指南將說明如何透過自訂指令、自訂代理程式（Custom Agents）及提示詞檔案，在 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

   規劃代理程式會定義一個規劃角色，並指示代理程式不要執行實作任務，而是專注於建立實作計畫。您可以指定交接 (handoffs)，以便在計畫完成後轉交給實作代理程式。

   若要建立自訂代理程式，請在指令面板 (Command Palette) 執行 Chat: New Custom Agent 指令。

   如果您想存取 GitHub Issues 作為情境，請務必安裝 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. 現在您可以在 Chat 視窗中選取 **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. 在 Chat 視窗中，輸入 /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 中。接著，您可以開啟新的 Chat 視窗，並在提示詞中參照該實作計畫檔案，以重設聊天情境。

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

   例如，輸入類似 implement #<my-plan>.md 的聊天提示詞，該提示詞會參照實作計畫檔案。

   提示

   Agent 經過優化，擅長執行多步驟任務，並能根據計畫與您的專案情境，找出達成目標的最佳方式。您只需提供計畫檔案或在提示詞中參照它即可。

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 不知所措。

維持情境隔離：將不同類型的作業（規劃、編碼、測試、除錯）保持在不同的聊天對話中，以防止情境混淆。

留意點數消耗：更多的情境檔案、更龐大的指令集以及複雜的代理程式鏈，都會增加 Token 使用量與 AI 點數消耗。請以精簡的情境開始，僅在必要時擴充。更多技巧請參閱優化 AI 點數使用量。

文件策略

建立動態文件：將自訂指令、自訂代理程式及範本視為持續演進的資源。根據觀察到的 AI 錯誤或缺陷進行精煉。

聚焦於決策情境：優先提供能協助 AI 做出更佳架構與實作決策的資訊，而非鉅細靡遺的技術細節。

使用一致的模式：建立並記錄編碼規範、命名模式以及架構決策，以協助 AI 產出一致的程式碼。

參考外部知識：連結至 AI 在產生程式碼時應考慮的相關外部文件、API 或標準。

工作流程優化

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

實作回饋循環：持續驗證 AI 是否正確理解您的情境。在發現誤解時，提問並儘早修正方向。

增加增量複雜度：以增量方式建構功能，並在增加複雜度前驗證每個步驟。這能防止錯誤累積並維持程式碼的可運作狀態。

關注點分離：針對不同活動使用不同的代理程式（規劃 vs. 實作 vs. 審查），以維持聚焦且相關的情境。

對情境進行版本控制：使用 git 來追蹤情境工程設定的變更，讓您可以還原問題變更，並理解什麼方法最有效。

驗證快取效能：使用代理程式除錯記錄 (Agent Debug Logs) 來檢查提示詞快取的命中率與 Token 使用量。良好的快取效能代表您的情境設定結構良好，讓模型提供者可以重複使用先前的請求前綴，進而降低延遲與 Token 成本。

應避免的反模式 (Anti-patterns)

情境傾倒 (Context dumping)：避免提供過多、失焦且對決策沒有直接幫助的資訊。

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

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

一體適用 (One-size-fits-all)：不同的團隊成員或專案階段可能需要不同的情境配置。請在方法上保持靈活性。

過度工程化代理程式鏈：深度巢狀的子代理程式工作流程與過多的工具呼叫會成倍增加 Token 使用量與點數消耗。請盡可能保持代理程式鏈簡潔，並將工具限制在該代理程式真正需要的範圍內。

衡量成功

成功的的情境工程設定應能達到以下成果：

• 減少往返溝通：降低修正或引導 AI 回應的需求。
• 程式碼品質一致：產出的程式碼遵循既定的模式與慣例。
• 實作速度更快：花費在解釋情境與需求的時間減少。
• 更佳的架構決策：AI 建議的解決方案與專案目標及限制更加契合。

擴展情境工程

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

針對大型專案：考慮利用指令檔案建立情境階層，區分為全專案、模組特定及功能特定的情境層級。

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

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

透過遵循這些實踐並持續優化您的方法，您將能發展出一套有效的情境工程工作流程，在維持程式碼品質與專案一致性的同時，提升 AI 輔助開發的成效。

相關資源

深入了解在 VS Code 中自訂 AI

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