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

本指南将向您展示如何使用自定义指令、自定义代理和提示文件在 VS Code 中设置上下文工程工作流程。

上下文工程是一种系统的方法，通过定制指令、实施计划和编码指南来提供有针对性的项目信息，以提高生成代码的质量和准确性。通过编排必要的项目上下文，您可以使 AI 做出更好的决策、提高准确性，并在互动中保持持久的知识。

小贴士

VS Code chat 提供了一个内置的计划代理，以帮助您在开始复杂的编码任务之前创建详细的实施计划。如果您不想创建自定义的规划工作流程，可以使用计划代理快速生成实施计划。

上下文工程工作流程

在 VS Code 中进行上下文工程的高级工作流程包括以下步骤：

策划项目范围内的上下文：使用自定义说明将相关文档（例如，架构、设计、贡献者指南）作为所有智能体互动的上下文。
生成实施计划：使用自定义代理和提示创建规划角色，以生成详细的特征实施计划。
生成实现代码：使用自定义指令根据实现计划生成代码，该计划遵循您的编码规范。

在您进行这些步骤时，您可以使用聊天中的后续提示来迭代和优化输出。

以下图表说明了 VS Code 中的上下文工程工作流程：

图表显示了 VS Code 中上下文工程工作流程的三个主要步骤。

步骤 1: 编辑项目范围内的上下文

为了将AI代理与项目的具体内容联系起来，收集诸如产品愿景、架构和其他相关文档等关键项目信息，并通过自定义指令将其添加为聊天上下文。通过使用自定义指令，您可以确保代理始终可以访问此上下文，而无需在每次聊天交互中重新学习。

为什么这有帮助： 代理可以在代码库中找到这些信息，但它可能会埋藏在注释中或者分散在多个文件中。通过提供一个简洁的最重要信息总结，您帮助代理始终为决策提供关键背景。

在仓库中使用Markdown文件描述相关项目文档，例如创建产品.md，架构.md，和CONTRIBUTING.md文件。
小贴士
如果您有一个现有的代码库，您可以使用AI生成这些项目文档文件。请确保审查和优化生成的文档文件，以确保其准确性和完整性。
- 生成一个ARCHITECTURE.md（最多2页）文件，描述项目的整体架构。
- 生成一个PRODUCT.md（最多2页）文件，描述项目的产品功能。
- 生成一个 CONTRIBUTING.md（最多1页）文件，该文件描述了贡献项目时的开发者指南和最佳实践。
创建一个.github/copilot-instructions.md 说明文件在你的仓库根目录。

此文件中的说明会自动包含在所有聊天互动中，作为AI代理的上下文。

为Agents提供项目背景和指南的高级概述。使用Markdown链接引用相关的支持文档文件。

以下示例.github/copilot-instructions.md文件提供了一个起点：

# [项目名称] 指南

* [产品愿景和目标](../PRODUCT.md): 理解产品的高级愿景和目标，以确保与业务目标的契合。
* [系统架构和设计原则](../ARCHITECTURE.md): 系统总体架构、设计模式和设计原则，这些原则指导开发过程。
* [贡献指南](../CONTRIBUTING.md): 项目贡献指南和协作实践的概述。

如果在工作中发现任何不完整或矛盾的信息，请建议更新这些文件。

小贴士

从简单开始，保持初始项目范围的上下文简洁，并专注于最关键的信息。如果不确定，专注于高级架构，只在出现重复错误或不正确行为时添加新规则（例如，使用错误的 shell 命令，忽略某些文件）。

步骤 2：制定实施计划

一旦你有了项目特定的上下文，你就可以使用人工智能来提示创建一个新功能或修复错误的实施计划。生成实施计划是一个迭代过程，可能需要多轮完善以确保其完整和准确。

通过自定义代理进行规划，您可以创建一个专门的角色，带有规划特定的指南和工具（例如，对代码库的只读访问）。他们还可以为您的项目和团队捕获特定的工作流程，用于头脑风暴、研究和协作。

小贴士

一旦你创建了自定义代理，就把它们当作活生生的文档。根据你观察到的代理行为中的任何错误或缺点，随着时间的推移进行完善和改进。

创建规划文件模板计划模板.md这定义了实施计划文件的结构和部分。

通过使用模板，您可以确保代理收集所有必要的信息，并以一致的格式呈现。这也帮助提高从计划生成的代码质量。

以下计划模板.md文件提供了一个实施计划模板的示例结构：

---
标题: [功能的简短描述标题]
版本: [可选的版本号]
创建日期: [YYYY-MM-DD]
最后更新日期: [YYYY-MM-DD]
---
# 实施计划: <功能>
[功能的需求和目标的简要描述]

## 建筑和设计
描述高级别的架构和设计考虑因素。

## 任务
将实施过程分解为更小、更易管理的任务，使用Markdown待办事项格式。

## 未解决问题
概述1-3个需要澄清的开放性问题或不确定性。

创建一个规划Agent .github/agents/plan.agent.md

规划代理定义了一个规划角色，并指示代理不要执行实施任务，而是专注于制定实施计划。您可以指定移交，在计划完成后转换为实施代理。

要创建自定义代理，请在命令面板中运行聊天：新建自定义代理命令。

如果你想访问 GitHub 问题以获取上下文，请确保安装 GitHub MCP 服务器。

你可能需要配置模型元数据属性，使用优化用于推理和深度理解的语言模型。

以下计划.代理.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. 分析和理解：从代码库和任何提供的文档中收集上下文，以全面了解需求和限制。运行#tool:runSubagent工具，指示代理自主工作，不暂停以获取用户反馈。
2. 构建计划：使用提供的[实施计划模板](计划模板.md)来构建计划。
3. 暂停以进行审查：根据用户反馈或问题，迭代并完善计划。

现在您可以在聊天视图中选择计划自定义代理，并输入一个任务来实现一个新功能。它将根据提供的模板生成一个包含实现计划的响应。

例如，输入以下提示以创建新功能的实施计划：添加用户认证，使用电子邮件和密码，包括注册、登录、登出和密码重置功能。输入：.

您还可以参考 GitHub 问题以提供具体背景：实现#43中的功能在这种情况下，代理将获取问题描述和评论以制定需求。
可选地，创建一个提示文件 .github/prompts/计划提示.md调用计划代理并指示代理根据提供的功能请求创建实施计划。

以下计划-Q&A.提示.md文件为规划提示提供了一个多样的起点，使用相同的流程但增加了澄清步骤。
```
---
Agent：计划
描述：制定详细的实施计划。
---
简要分析我的功能请求，然后问我3个问题以澄清需求。只有在完成这些步骤后才开始规划工作流程。
```
在聊天视图中，输入/计划-Q&A斜线命令来调用澄清规划提示，并在提示中提供您希望实现的功能的详细信息。

例如，输入以下提示：/plan-qna 添加一个客户详细信息页面，用于显示和编辑客户信息

Agents在制定实施计划之前会问一些澄清问题，以更好地理解需求，从而减少任何误解。

小贴士

使用自定义代理来定义使用特定工具的多轮对话工作流程。单独使用它们或与提示文件结合使用，以添加相同工作流程的不同变体和配置。

步骤 3：生成实现代码

在您生成并优化了实施计划之后，您现在可以使用AI通过从实施计划生成代码来实现该功能。

对于较小的任务，您可以直接通过提示代理根据实施计划生成代码来实现功能。

对于较大或复杂的功能，您可以切换到Agent并提示它将实施计划保存到文件中（例如，<我的功能>-计划.md) 或者将其作为评论添加到提到的 GitHub 问题中。然后，您可以打开一个新聊天，并在您的提示中引用实施计划文件以重置聊天上下文。
现在你可以指示代理根据你在上一步创建的实施计划来实现该功能。

例如，输入一个聊天提示，例如实施 #<我的计划>.md，引用了实施计划文件。

小贴士
Agent 优化用于执行多步骤任务，并根据计划和您的项目上下文来确定如何最好地实现目标。您只需提供计划文件或在提示中引用它。

为了更定制化的流程，请创建一个自定义代理 .github/agents/implement.agent.md专门根据计划实施代码。

以下tdd.agent.md文件提供了一个用于测试驱动实现自定义代理的起点。

---
描述：'根据测试驱动开发方法执行详细的实施计划。' 
---
# TDD 实施代理
专家级 TDD 开发人员，为给定的实施计划生成高质量、完全测试、可维护的代码。

## 测试驱动开发
1. 先写/更新测试，以编码接受标准和预期行为
2. 实现最小代码以满足测试要求
3. 每次更改后立即运行有针对性的测试
4. 运行完整的测试套件，以在转到下一个任务之前捕获回归
5. 重构时保持所有测试通过

## 核心原则
* 逐步进展：小而安全的步骤使系统保持运行
* 测试驱动：测试指导和验证行为
* 质量重点：遵循现有的模式和约定

## 成功标准
* 所有计划任务完成
* 每个任务的验收标准已满足
* 测试通过（单元测试、集成测试、完整套件）

小贴士

较小的语言模型在遵循明确的指示生成代码方面非常出色，因此实施Agents的利益来自设置模型将属性分配给语言模型。

小贴士

获得全新的代理视角：创建一个新的聊天 (⌘N (Windows, Linux Ctrl+N)) 并要求代理根据实施计划审查代码变更。这有助于识别任何未满足的要求或不一致性。

最佳实践和常见模式

遵循这些最佳实践有助于您建立一个可持续且有效的上下文工程工作流程。

上下文管理原则

从小处着手并进行迭代：从最小的项目上下手，根据观察到的AI行为逐渐添加细节。避免过多的上下文信息导致注意力分散。

保持上下文新鲜：随着代码库的演变，定期审核和更新你的项目文档（使用代理）。过时的上下文会导致过时或不正确的建议。

使用渐进式上下文构建：从高级概念开始，逐步添加细节，而不是一开始就向AI提供全面的信息，以免其感到困惑。

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

文档策略

创建动态文档：将您的自定义指令、自定义代理和模板视为不断发展的资源。根据观察到的 AI 错误或不足进行改进。

专注于决策环境：优先考虑有助于人工智能做出更好的架构和实施决策的信息，而不是详尽的技术细节。

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

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

工作流程优化

智能体之间的移交：使用移交来创建指导性过渡，并在规划、实施和审查智能体之间实现端到端开发工作流程。

实施反馈循环：持续验证AI是否正确理解你的上下文。在出现误解时，提出澄清问题并早期调整。

使用增量复杂度：增量地构建功能，在添加复杂度之前验证每一步。这可以防止错误累积并保持代码的正常运行。

分离关注点：为不同的活动使用不同的代理（规划、实施和审查），以保持专注和相关的上下文。

版本化你的上下文：使用git来跟踪你上下文工程设置的变化，这样你就可以撤销有问题的更改，并了解什么是最好的。

避免的反模式

上下文倾销：避免提供过多的、不聚焦的信息，这些信息如果不直接有助于决策则应避免。

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

忽视验证：不要假定AI正确理解了你的上下文。在进行复杂的实现之前，始终测试理解。

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

衡量成功

一个成功的上下文工程设置应导致：

减少来回往复：减少需要纠正或引导AI回应
一致的代码质量：生成的代码遵循既定的模式和约定
更快的实施：减少解释上下文和需求的时间
更好的建筑决策：AI建议的解决方案符合项目目标和限制

扩展上下文工程

对于团队：通过版本控制共享上下文工程设置，并建立团队约定以维护共享上下文。

对于大型项目：考虑使用指令文件创建项目级、模块级和功能级的上下文层次结构。

对于长期项目：建立定期上下文审查周期，以保持文档的最新和删除过时的信息。

对于多个项目：创建可复用的模板和模式，可以在不同的代码库和领域中采用。

通过遵循这些实践并不断优化您的方法，您将开发出一种上下文工程工作流程，该工作流程在提高人工智能辅助开发能力的同时，保持代码质量和项目的一致性。