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

本指南将向您展示如何通过自定义说明、自定义智能体和提示词文件，在 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 来提示创建新功能或错误修复的实施计划。生成实施计划是一个迭代过程，可能需要多轮精炼以确保其完整和准确。

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

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 Issue 以获取上下文，请务必安装 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. 对于较小的任务，您可以直接通过提示 AI 根据实施计划生成代码来实现功能。

   对于较大或复杂的功能，您可以切换到 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 的信息

• 说明文件
• 自定义代理
• 提示文件