在 VS Code 中设置上下文工程化流程

本指南将向您展示如何通过自定义指令、自定义智能体（Agents）和提示词文件，在 VS Code 中建立上下文工程化工作流。

上下文工程化是一种系统性方法，旨在为 AI 智能体提供有针对性的项目信息，从而提高生成代码的质量和准确性。通过自定义指令、实施计划和编码规范来梳理关键的项目上下文，您可以使 AI 做出更好的决策、提高准确性，并在多次交互中保持持久的知识沉淀。

上下文工程化工作流

VS Code 中上下文工程化的高级工作流包含以下步骤

1. 梳理全项目范围的上下文：使用自定义指令将相关的文档（例如架构、设计、贡献者指南）作为上下文包含在所有智能体交互中。
2. 生成实施计划：使用自定义智能体和提示词创建规划角色，以生成详细的功能实施计划。
3. 生成实施代码：使用自定义指令，基于实施计划并遵循您的编码规范来生成代码。

在执行上述步骤的过程中，您可以通过聊天中的后续提示词进行迭代和优化输出。

下图展示了 VS Code 中的上下文工程化工作流

第一步：梳理全项目范围的上下文

为了让 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.
   

第二步：创建实施计划

一旦有了项目特定的上下文，您就可以使用 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

   规划智能体定义了规划角色，并指示智能体不要执行实施任务，而是专注于创建实施计划。您可以指定移交（handoffs），以便在计划完成后切换到实施智能体。

   要创建自定义智能体，请在命令面板中运行 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. 现在，您可以在聊天视图中选择 plan 自定义智能体，并输入实现新功能的任务。它将生成一个包含基于所提供模板的实施计划的响应。

   例如，输入以下提示词来创建新功能的实施计划：添加带有邮箱和密码的用户身份验证功能，包括注册、登录、登出和密码重置功能。

   您也可以引用 GitHub Issue 来提供特定上下文：实现 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 添加一个用于显示和编辑客户信息的客户详情页面

   智能体会提出澄清问题，以便在创建实施计划前更好地理解需求，从而减少误解。

第三步：生成实施代码

在生成并精炼实施计划后，现在可以使用 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。

保持上下文隔离：将不同类型的工作（规划、编码、测试、调试）放在不同的聊天会话中，以防上下文混淆。

注意积分消耗：更多的上下文文件、更大的指令集和复杂的智能体链都会增加 Token 使用量和 AI 积分消耗。从简洁的上下文开始，仅在需要时进行扩展。更多建议，请参阅优化 AI 积分使用。

文档策略

创建动态文档：将自定义指令、自定义智能体和模板视为不断演进的资源。根据观察到的 AI 错误或不足进行精炼。

聚焦决策上下文：优先提供有助于 AI 做出更好的架构和实施决策的信息，而非详尽的技术细节。

使用一致的模式：建立并记录编码规范、命名模式和架构决策，以帮助 AI 生成一致的代码。

参考外部知识：链接到 AI 在生成代码时应考虑的相关外部文档、API 或标准。

工作流优化

智能体间的移交：使用移交（handoffs）来创建引导式转换，并在规划、实施和评审智能体之间实现端到端的开发工作流。

实施反馈闭环：持续验证 AI 是否正确理解了您的上下文。提出澄清问题，并在发现误解时尽早纠正。

使用增量式复杂度：增量地构建功能，在增加复杂度之前验证每一步。这可以防止错误积累，并保持代码处于可用状态。

职责分离：针对不同的活动（规划、实施、评审）使用不同的智能体，以保持上下文的聚焦与相关性。

对上下文进行版本控制：使用 Git 追踪上下文工程化配置的更改，以便回滚有问题的更改并了解什么方式最有效。

验证缓存性能：使用 Agent Debug Logs 检查提示词缓存命中率和 Token 使用情况。良好的缓存性能意味着您的上下文设置结构得当，模型提供商可以重用之前的请求前缀，从而降低延迟和 Token 成本。

应避免的反模式

上下文堆砌：避免提供过多、无重点且对决策没有直接帮助的信息。

指导不一致：确保所有文档都与您选择的架构模式和编码标准保持一致。

忽视验证：不要假设 AI 完全理解您的上下文。在进行复杂实施之前，务必先测试其理解程度。

一刀切：不同的团队成员或项目阶段可能需要不同的上下文配置。在方法上保持灵活性。

过度工程化智能体链：深度嵌套的子智能体工作流和过多的工具调用会成倍增加 Token 使用量和 积分消耗。保持智能体链尽可能浅显，并将工具限制在每个智能体实际需要的范围内。

衡量成功

成功的上下文工程化设置应能带来：

• 减少反复沟通：降低纠正或重定向 AI 响应的需求
• 一致的代码质量：生成的代码遵循既定的模式和规范
• 更快的实施速度：减少解释上下文和需求的时间
• 更好的架构决策：AI 能够建议与项目目标和约束一致的解决方案

扩展上下文工程化

针对团队：通过版本控制共享上下文工程化设置，并建立维护共享上下文的团队规范。

针对大型项目：考虑使用指令文件，创建具有全项目、模块特定和功能特定层级的上下文层次结构。

针对长期项目：建立定期的上下文评审周期，以保持文档更新并删除过时的信息。

针对多个项目：创建可跨不同代码库和领域复用的模板与模式。

通过遵循这些实践并不断完善您的方法，您将建立起一个能够增强 AI 辅助开发，同时保持代码质量和项目一致性的上下文工程化工作流。

相关资源

了解更多关于在 VS Code 中自定义 AI 的信息

• 指令文件
• 自定义代理
• 提示文件