在VS Code中建立上下文工程流程

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

上下文工程是一种系统化的方法，旨在为人工智能代理提供有针对性的项目信息，以提升生成代码的质量和准确性。通过定制说明、实施计划和编码指南，精心整理关键项目背景，使AI能够做出更好的决策，提高准确性，并在交互中保持持续的知识。

提示

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

上下文工程工作流程

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

  1. 策划全项目上下文：使用自定义说明，包含相关文档（例如架构、设计、贡献者指南）作为所有代理互动的上下文。
  2. 生成实施计划：通过使用自定义代理和提示创建规划人物，生成详细的功能实施计划。
  3. 生成实现代码：使用自定义指令，根据符合编码指南的实施计划生成代码。

在逐步作的过程中，你可以通过聊天中的后续提示反复迭代和完善输出。

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

示意图展示了 VS Code 中上下文工程工作流程，包含三个主要步骤。

步骤1：策划整个项目的背景

为了让AI代理更了解项目的具体情况，收集关键项目信息，如产品愿景、架构及其他相关文档，并通过自定义指令添加为聊天上下文。通过使用自定义指令，你可以确保客服始终能够访问这些上下文，而不必每次聊天交互都重新学习

为什么这有帮助：代理可以在代码库中找到这些信息，但可能隐藏在注释中或分散在多个文件中。通过提供最重要信息的简明总结，你帮助代理人始终掌握关键的上下文，方便决策。

  1. 在仓库中的 Markdown 文件中描述相关的项目文档，例如创建PRODUCT.md,ARCHITECTURE.md， 和CONTRIBUTING.md文件。

    提示

    如果你已有代码库，可以用AI生成这些项目文档文件。务必审查和完善生成的文档文件，以确保准确性和完整性。

    • 生成一个 ARCHITECTURE.md（最多 2 页）文件，描述项目的整体架构。
    • 生成一个最 PRODUCT.md（最多2页）文件，描述项目的产品功能。
    • 生成一个 CONTRIBUTING.md（最多一页）文件，描述开发者指南和贡献项目的最佳实践。

  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.
提示

从小处开始，保持项目整体背景简洁，聚焦最关键的信息。如果不确定，专注于高级架构，只添加新规则来解决代理反复犯错或错误行为（例如使用错误的shell命令，忽略某些文件）。

第二步：制定实施计划

一旦你有了项目特定的上下文，就可以用 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. 创建一个规划Agent .github/agents/plan.agent.md

    规划代理人定义规划角色，指示代理人不执行实施任务，而专注于制定实施计划。你可以指定切换，在计划完成后切换到实施代理。

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

    如果你想访问GitHub issues获取上下文，务必安装GitHub MCP服务器。

    你可能想配置一下模型元数据属性，使用一个优化推理和深度理解的语言模型。

    如下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. 你现在可以在聊天视图中选择计划自定义代理，并输入实现新功能的任务。它会根据提供的模板生成包含实施计划的响应。

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

    你也可以参考GitHub的一个问题来提供具体的背景：实现#43期中的功能此时代理会获取问题描述和注释以提出需求。

  4. 可选地，创建一个提示文件 .github/prompts/plan.prompt.md该程序调用 Plan Agent，并指示 Agent 根据提供的功能请求创建实施计划。

    如下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 添加客户详情页面，用于显示和编辑客户信息

    代理会提出澄清性问题，以更好地理解需求，然后制定实施计划，减少误解。

提示

使用自定义代理定义遵循多轮流程的工作流程，配合特定工具。可单独使用，或与提示文件结合使用，添加同一工作流程的不同变体和配置。

步骤3：生成实现代码

在生成并完善实施计划后，你现在可以用AI根据实施计划生成代码来实现该功能。

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

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

  2. 你现在可以根据上一步创建的实施计划指示代理实现该功能。

    例如，输入一个聊天提示，比如实现 #<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)
    提示

    由于较小的语言模型擅长遵循显式指令生成代码，实现代理从设置 中受益模型属性映射到语言模型。

提示

换个新的代理视角：创建一个新聊天（⌘N（Windows，Linux Ctrl+N）），让代理根据实施计划审查代码变更。这有助于发现遗漏或不一致。

最佳实践与常见模式

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

情境管理原则

从小做起，逐步迭代：从最小的项目上下文开始，逐渐根据观察到的AI行为添加细节。避免上下文过载，以免稀释重点。

保持上下文新鲜：随着代码库的发展，定期审核和更新项目文档（使用代理）。陈旧的上下文会导致建议过时或错误。

使用渐进式上下文构建：从高层次概念开始，逐步添加细节，而不是一开始就用全面信息淹没AI。

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

文档策略

创建活文档：将你的定制说明、定制代理和模板视为不断发展的资源。根据观察到的AI错误或不足进行优化。

关注决策背景：优先考虑帮助AI做出更好架构和实施决策的信息，而非详尽的技术细节。

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

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

工作流程优化

代理间切换：利用切换创建引导式过渡，并在规划、实施和审核代理之间实现端到端的开发流程。

实施反馈循环：持续验证AI是否正确理解你的上下文。当误解出现时，及时提出澄清问题并纠正方向。

使用增量复杂度：逐步构建功能，每一步验证后再增加复杂度。这防止了错误的叠加，并保持代码的正常运行。

独立关注点：为不同活动（规划、实施和审查）使用不同的代理，以保持聚焦且相关的背景。

版本化你的上下文：使用 git 跟踪上下文工程设置的变更，帮助你还原有问题的更改，了解哪种更合适。

应避免的反模式

背景倾倒：避免提供过多且无重点的信息，这些信息对决策没有直接帮助。

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

忽视验证：不要假设AI能正确理解你的语境。在进行复杂实现前，务必先测试理解。

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

衡量成功

一个成功的上下文工程设置应当实现：

  • 减少来回沟通：减少纠正或引导AI回应的需求
  • 一致性的代码质量：生成的代码遵循既定的模式和惯例
  • 更快的实现：减少解释上下文和需求的时间
  • 更好的架构决策：AI建议符合项目目标和限制的解决方案

扩展上下文工程

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

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

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

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

通过遵循这些实践并不断完善你的方法，你将开发出一个情境工程工作流程，提升AI辅助开发，同时保持代码质量和项目一致性。

相关资源

了解更多关于在VS Code中定制AI的信息：