在 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 提示创建新功能或错误修复的实施计划。生成实施计划是一个迭代过程，可能需要多个轮次的完善才能确保其完整性和准确性。

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

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 以提供特定上下文：实施 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 添加一个客户详细信息页面，用于显示和编辑客户信息

   代理会提出澄清问题以更好地了解需求，然后再创建实施计划，从而减少任何误解。

步骤 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 生成一致的代码。

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

工作流程优化

代理之间的交接：使用 交接 创建引导式过渡，并在规划、实现和审查代理之间实现端到端开发工作流程。

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

使用增量复杂性：逐步构建功能，在添加复杂性之前验证每个步骤。这可以防止错误累积并保持代码可用。

分离关注点：使用不同的代理执行不同的活动（规划与实现与审查），以保持专注且相关的上下文。

版本化您的上下文：使用 git 跟踪上下文工程设置的更改，允许您撤销有问题更改并了解哪些效果最好。

避免的反模式

上下文转储：避免提供过多的、不集中的信息，这些信息不能直接帮助决策。

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

忽略验证：不要假设 AI 正确理解您的上下文。在进行复杂的实现之前，始终测试理解情况。

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

衡量成功

成功的上下文工程设置应该产生

• 减少来回沟通：减少纠正或重定向 AI 响应的需求
• 一致的代码质量：生成的代码遵循既定的模式和约定
• 更快的实现速度：减少花费在解释上下文和需求上的时间
• 更好的架构决策：AI 建议的解决方案与项目目标和约束条件相符

扩展上下文工程

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

对于大型项目：考虑使用 指令文件 创建上下文层次结构，其中包含项目范围、模块特定和功能特定的上下文层。

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

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

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

相关资源

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

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