在 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 的更多信息

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