别再只收藏提示词：VS Code 的 Prompt、Instructions、Agent、MCP 一篇文章讲清楚
别再只收藏提示词：VS Code 的 Prompt、Instructions、Agent、MCP 一篇文章讲清楚
使用 VS Code 的 AI 编程功能一段时间后，很多人都会积累一个越来越长的“提示词收藏夹”：
- 让 AI 按某种代码规范生成代码；
- 让 AI 每次修改后运行测试；
- 让 AI 只审查代码，不要直接改文件；
- 让 AI 查询 GitHub Issue、访问网页或者读取数据库；
- 每次开始新对话，再把相同要求复制一遍。
这些要求当然可以继续写进聊天框，但它们其实属于不同层次的问题。
VS Code 已经提供了四种更稳定的机制：
- Prompt：保存一项可重复执行的任务；
- Instructions：保存项目长期遵守的规则；
- Agent：保存一个专业角色及其权限；
- MCP：给智能体连接外部工具和数据。
它们不是四种名字不同的“高级提示词”。它们控制的是 AI 工作过程中的不同部分。本文会用一个统一的 Python 代码审查场景，把四者的区别、文件位置、配置方法、组合方式和常见误区一次讲清楚。
📚 专栏介绍：《GitHub小白开源成长课》
这是一个面向计算机初学者、大学新生和刚开始接触开源协作的实战专栏。
我们不只介绍工具名称，而是把每一步真正跑通：看懂仓库、配置环境、解决报错、审查 AI 生成代码，并逐渐完成自己的第一次开源贡献。
本文适合已经会打开 VS Code、能够使用 Chat 功能，但经常分不清 Prompt、Instructions、Agent 和 MCP 的读者。
本文依据 Visual Studio Code 官方文档整理，功能与路径核对时间为 2026 年 7 月 28 日。部分功能会受到 VS Code 版本、GitHub Copilot 套餐、组织策略和 Preview 状态影响，请以你的实际界面为准。
一、先记住四句话
如果你暂时不想研究所有配置，只要先记住下面四句话：
- Prompt 决定这一次要做什么。
- Instructions 决定做事时长期遵守什么规则。
- Agent 决定由什么角色来做，以及它可以使用哪些工具。
- MCP 决定这个角色还能连接哪些外部系统。
可以把它们类比成一家软件团队：
| VS Code 概念 | 团队类比 | 解决的问题 |
|---|---|---|
| Prompt | 一张具体工单 | 这一次要完成什么任务？ |
| Instructions | 团队开发规范 | 所有任务都必须遵守什么规则？ |
| Agent | 一名专业同事 | 谁来做？拥有什么权限？ |
| MCP | 同事能使用的外部系统 | 可以访问哪些数据库、网页或平台？ |
最常用的判断方法是：
反复执行同一项任务 → Prompt
反复强调同一条规则 → Instructions
需要固定角色和权限 → Agent
需要访问外部工具或数据 → MCP
二、为什么只收藏提示词不够？
假设你每次审查 Python 代码时都会输入：
请检查这段代码的边界条件、异常处理、类型标注和测试覆盖率。不要直接修改文件。按照严重程度输出问题，并给出对应文件和行号。
第一次输入没有问题，但重复十次后会出现四个麻烦：
1. 容易漏掉要求
今天忘了写“不要修改文件”，明天忘了写“必须检查测试”，结果就会发生变化。
2. 项目规范散落在聊天记录里
代码风格、目录约定和测试命令只存在于某次对话中，换一个窗口就需要重新解释。
3. 权限边界不清楚
嘴上说“只审查”，但当前 Agent 仍然可能拥有文件编辑或终端工具。自然语言要求不等于真正的权限限制。
4. AI 只有知识，没有真实外部能力
普通聊天可以解释 GitHub Issue 是什么，却不一定能读取你仓库里的最新 Issue；可以告诉你浏览器测试的思路，却不能自动打开网页检查页面。
因此，真正稳定的做法不是继续把所有内容塞进一条超长提示词，而是把要求拆到正确的层次。
三、Prompt：把重复任务保存成一个斜杠命令
1. Prompt是什么？
VS Code 中的 Prompt file 是一个以 .prompt.md 结尾的 Markdown 文件。它把一项经常重复的任务保存下来，使用时通过聊天框中的斜杠命令手动调用。
它最适合这类需求：
- 为当前模块生成测试；
- 检查一段 API 的安全问题；
- 根据改动准备 Pull Request 描述；
- 解释当前打开的文件；
- 按固定格式整理报错信息。
Prompt 的关键词是：可重复、按需执行、手动触发。
2. Prompt文件放在哪里？
工作区级 Prompt 默认放在：
.github/prompts/
文件扩展名是：
*.prompt.md
例如：
.github/prompts/review-python.prompt.md
工作区级 Prompt 会跟随仓库，适合团队共享。用户配置中的 Prompt 则可以跨多个项目使用。
3. 创建第一个Prompt文件
在项目中创建：
.github/prompts/review-python.prompt.md
写入下面的内容：
---
name: review-python
description: 审查指定Python文件或目录
argument-hint: 'target=<文件或目录>'
agent: reviewer
---
请审查 `${input:target:src}` 中的Python代码。
重点检查：
1. 可能导致错误的边界条件；
2. 异常处理是否完整；
3. 类型标注是否准确；
4. 测试是否覆盖正常路径和失败路径；
5. 是否出现密钥、令牌或其他敏感信息。
请按“阻断问题、重要问题、改进建议”分组输出。
每个问题都要给出文件位置、原因和最小修复建议。
不要直接修改任何文件。
然后在 VS Code Chat 中输入：
/review-python target=src
这相当于调用了一张预先写好的“代码审查工单”。
4. Prompt可以配置什么？
.prompt.md 的 YAML 头部可以配置：
| 字段 | 作用 |
|---|---|
name |
斜杠命令显示的名称 |
description |
简短说明 |
argument-hint |
提示用户应该输入什么参数 |
agent |
指定内置 Agent 或自定义 Agent |
model |
指定运行该 Prompt 的模型 |
tools |
限制或指定本次可使用的工具 |
如果 Prompt 和它引用的 Agent 都配置了 tools，VS Code 官方文档给出的优先顺序是：
- Prompt 文件中指定的工具；
- Prompt 引用的自定义 Agent 中的工具；
- 当前 Agent 的默认工具。
因此，不要在 Prompt 中随意写一个过大的工具列表。它可能覆盖 Agent 原本设计好的最小权限。
5. Prompt不适合保存什么？
下面这些内容不适合反复写进每个 Prompt：
- 项目统一使用 Python 3.12；
- 所有公共函数必须写类型标注；
- 禁止在日志中记录访问令牌；
- 提交前必须运行某个固定测试命令。
这些是项目长期规则，应该交给 Instructions。
四、Instructions：让项目规则自动进入上下文
1. Instructions是什么？
Instructions 是 AI 在处理任务时需要持续遵守的规则。它们可以对整个项目始终生效，也可以只在处理特定文件时生效。
它最适合保存：
- 编码规范和命名约定；
- 技术栈与推荐库；
- 项目目录和架构边界；
- 错误处理与安全要求；
- 测试命令和文档规范。
Instructions 的关键词是：长期规则、自动应用、项目上下文。
需要注意：官方文档明确说明，自定义 Instructions 用于 Chat 请求，不会影响你输入代码时出现的行内补全建议。
2. 最简单的项目级Instructions
在仓库中创建：
.github/copilot-instructions.md
示例：
# 项目开发规则
- 项目使用 Python 3.12。
- 新增公共函数必须提供类型标注和简短 docstring。
- 测试框架统一使用 pytest。
- 修改业务逻辑时，必须同步增加或更新测试。
- 不要把 API Key、Token、密码写入源码或测试数据。
- 修改前先阅读相关代码，避免无关重构。
- 完成后报告修改文件、验证命令和仍然存在的风险。
这个文件适合存放整个项目都要遵守的规则。
3. 只对Python文件生效的Instructions
如果同一个仓库同时包含前端、后端和文档，可以使用文件级 Instructions。
默认目录是：
.github/instructions/
创建：
.github/instructions/python.instructions.md
内容如下：
---
name: Python Standards
description: Python文件的编码和测试规范
applyTo: '**/*.py'
---
- 遵循 PEP 8。
- 所有函数签名都使用类型标注。
- 优先返回明确的数据类型，不使用含义不清的字典。
- 捕获异常时禁止使用空的 `except:`。
- 测试同时覆盖正常路径、边界值和异常路径。
applyTo 决定它自动匹配哪些文件。处理 .py 文件时，VS Code 才会把这些规则加入上下文。
4. copilot-instructions.md、AGENTS.md怎么选？
目前 VS Code 支持多种项目规则文件：
| 文件 | 适用场景 |
|---|---|
.github/copilot-instructions.md |
VS Code/GitHub Copilot 项目的统一规则 |
.github/instructions/*.instructions.md |
按语言、目录或框架匹配的规则 |
根目录 AGENTS.md |
同一仓库需要被多个 AI 编码工具共同理解 |
CLAUDE.md |
同时使用 Claude Code 生态时复用其规则 |
如果你刚开始使用，建议先创建一个 .github/copilot-instructions.md，不要一上来就建立十几个规则文件。
如果项目同时使用多个 AI 编码智能体，可以考虑把真正通用的仓库规则放入根目录 AGENTS.md。
5. Instructions最常见的错误
错误一：把具体任务写成长期规则
“帮我修复登录页面”不是 Instructions，而是一次任务。
错误二：规则太多、互相冲突
VS Code 会把多个匹配的 Instructions 一起加入上下文，同类文件之间不要依赖“后面的规则覆盖前面的规则”。最安全的做法是消除冲突。
错误三：只写抽象口号
“代码必须优雅”“遵循最佳实践”几乎无法验证。更好的写法是：
新增公共函数必须有类型标注；
异步调用必须显式处理超时；
修改业务逻辑必须增加对应测试。
规则越具体，AI 越容易执行，你也越容易验收。
五、Agent：保存一个角色、工作方式和工具权限
1. Agent是什么？
自定义 Agent 是一个具有明确职责的专业角色。它不仅能保存提示语，还能限定：
- 它扮演什么角色；
- 它如何分析问题；
- 它可以使用哪些工具；
- 它能否编辑文件或运行命令；
- 它完成工作后可以交接给哪个 Agent。
Agent 的关键词是：角色、权限、工作方式。
例如，可以分别创建：
- 只读规划员；
- 代码实现者；
- 测试审查员；
- 安全审查员；
- 文档编写员。
2. Agent文件放在哪里？
工作区级自定义 Agent 默认放在：
.github/agents/
推荐使用：
*.agent.md
例如：
.github/agents/reviewer.agent.md
3. 创建一个只读代码审查Agent
---
name: reviewer
description: 只读审查代码，识别正确性、测试和安全风险
tools: ['search/codebase', 'search/usages']
---
# 角色
你是一名谨慎的代码审查员。
# 工作边界
- 只分析，不修改文件。
- 不运行会改变工作区或外部系统状态的命令。
- 不根据文件名猜测实现，必须先阅读相关代码。
- 无法确认的问题要明确标记为“需要人工核实”。
# 审查重点
1. 正确性和边界条件；
2. 异常处理；
3. 回归风险；
4. 测试缺口；
5. 密钥、权限和输入校验问题。
# 输出格式
按严重程度排序。每个问题包含：
- 文件和位置；
- 问题原因；
- 触发条件；
- 最小修复建议。
这个 Agent 没有文件编辑工具，也没有终端工具。即使 Prompt 要求它直接修改代码，它能够执行的动作仍然受到工具列表限制。
这就是 Agent 与普通角色提示词最重要的区别：权限边界可以配置，而不只是口头约定。
工具名称会随 VS Code 版本、扩展和环境变化。如果某个工具不可用，VS Code 会忽略它。可通过 Chat 的工具选择器或 Customizations 诊断页面确认当前真实工具名称。
4. Agent和模型不是一回事
很多初学者会把 Agent 和大模型混为一谈。
简单理解：
模型：负责理解和推理的大脑
Agent：角色说明 + 可用工具 + 工作边界
同一个 Agent 可以使用不同模型；同一个模型也可以被配置成不同 Agent。
5. Agent为什么要限制工具？
规划任务通常只需要搜索和读取，没必要拥有删除文件或执行任意命令的能力。
权限越多并不一定越强，反而会带来：
- 误修改文件；
- 执行不必要命令；
- 消耗更多上下文和请求；
- 扩大外部工具带来的安全风险。
官方建议对安全敏感的工作遵循最小权限原则：只开放完成任务真正需要的工具。
六、MCP：让Agent连接外部世界
1. MCP是什么？
MCP 全称是 Model Context Protocol。它是一套开放协议，用统一方式把 AI 应用连接到外部工具和数据。
在 VS Code 中，MCP Server 可以提供：
- Tools：执行操作，例如访问网页、查询数据库、调用 API；
- Resources：提供只读上下文，例如文件、表结构或接口结果；
- Prompts：由服务器提供的可复用提示模板；
- MCP Apps：直接在聊天中显示表单、图表等交互界面。
MCP 的关键词是：外部能力、真实数据、标准连接。
2. 没有MCP和有MCP的区别
没有 MCP 时：
你：检查网页上的登录按钮是否正常
AI：我可以告诉你应该检查哪些内容
配置浏览器类 MCP 后：
你：检查网页上的登录按钮是否正常
Agent：打开页面 → 点击按钮 → 读取结果 → 截图 → 汇报问题
MCP 不是让模型“知道更多概念”，而是给 Agent 增加可以实际调用的能力。
3. MCP配置放在哪里？
工作区配置默认位于：
.vscode/mcp.json
用户级配置可以通过命令面板中的 MCP: Open User Configuration 打开，适合跨项目复用。
下面是 VS Code 官方文档给出的远程服务器与本地服务器组合示例：
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp"
},
"playwright": {
"command": "npx",
"args": ["-y", "@microsoft/mcp-server-playwright"]
}
}
}
也可以打开扩展视图，搜索：
@mcp
从 MCP Server Gallery 查看和安装服务器。安装到工作区时，VS Code 会更新 .vscode/mcp.json。
4. MCP一定要注意安全
MCP Server 可能读取数据、访问网络，甚至在本机运行代码。安装前至少检查：
- 发布者和源代码是否可信；
- 服务器究竟提供哪些工具；
- 工具是只读还是会修改外部数据；
- 配置中是否写入了 API Key；
- Agent 是否真的需要全部工具；
- 每次工具调用的参数是否符合预期。
不要把密钥直接写进 mcp.json。应使用输入变量、环境文件或安全的凭据管理方式。
还要特别注意：截至本文核对时，VS Code 官方文档说明，本地 stdio MCP 的沙箱功能暂不支持 Windows。因此 Windows 用户更应该只安装可信服务器，并认真检查每次授权。
七、四者是怎样组合工作的？
四者可以单独使用，但真正稳定的工作流通常会把它们组合起来。
假设任务是：
审查当前仓库的登录模块，结合 GitHub Issue 判断是否满足需求，并检查网页上的登录流程。
四者分别负责：
| 层次 | 在这次任务中的作用 |
|---|---|
| Instructions | 规定项目使用 Python 3.12、pytest 和统一错误格式 |
| Agent | 以“代码审查员”身份工作，并限制可用工具 |
| Prompt | 定义本次审查范围、检查项和输出格式 |
| MCP | 读取 GitHub Issue，并通过浏览器工具验证页面 |
可以把最终请求理解为：
最终任务
= 用户当前输入
+ Prompt中的任务模板
+ Instructions中的项目规则
+ Agent的角色与工具边界
+ MCP提供的外部能力
这也解释了为什么把所有内容都堆进一条提示词效果不稳定：任务、规则、角色和外部能力本来就应该分层管理。
八、一个推荐的项目目录
把前面的配置组合起来，目录可以这样组织：
demo-project/
├─ .github/
│ ├─ copilot-instructions.md
│ ├─ instructions/
│ │ └─ python.instructions.md
│ ├─ prompts/
│ │ └─ review-python.prompt.md
│ └─ agents/
│ └─ reviewer.agent.md
├─ .vscode/
│ └─ mcp.json
├─ src/
│ └─ login.py
└─ tests/
└─ test_login.py
对应关系如下：
| 文件 | 谁来读取 | 什么时候生效 |
|---|---|---|
copilot-instructions.md |
VS Code Chat | 工作区聊天请求中自动生效 |
python.instructions.md |
VS Code Chat | 匹配 Python 文件或相关任务时生效 |
review-python.prompt.md |
用户手动调用 | 输入 /review-python 时生效 |
reviewer.agent.md |
自定义 Agent | 选择或引用该 Agent 时生效 |
mcp.json |
VS Code MCP 客户端 | Server 启动且工具被允许后可用 |
九、到底应该选哪个？看这张图
场景一：每次都要重复输入同一段任务要求
选择 Prompt。
例如：
- 每次都按固定模板生成单元测试；
- 每次都按固定格式准备 PR；
- 每次都检查同一组安全问题。
场景二：AI总是忘记项目规则
选择 Instructions。
例如：
- 项目统一使用某个框架；
- 禁止调用已经废弃的库；
- 所有业务修改必须带测试。
场景三：希望固定角色并限制权限
选择 Agent。
例如：
- 只读审查员；
- 只能制定计划、不能修改代码的规划员；
- 拥有编辑和测试能力的实现者。
场景四：需要读取外部系统或执行真实操作
选择 MCP。
例如：
- 查询 GitHub Issue；
- 打开浏览器验证页面；
- 读取数据库；
- 调用企业内部 API。
场景五：四种需求同时存在
组合使用，但建议按下面的顺序逐步增加：
Instructions → Prompt → Agent → MCP
先把项目规则写清楚，再保存重复任务，然后按需要建立角色，最后才连接外部工具。
十、最常见的七个误区
误区1：Prompt越长越专业
Prompt 的目标是让任务清楚、可执行、可验收，而不是追求字数。能用项目 Instructions 表达的规则，不要在每个 Prompt 中复制。
误区2：Instructions会自动修正所有AI输出
Instructions 只是加入上下文，并不是编译器或强制策略。关键要求仍需要测试、Lint、权限控制和人工审查。
误区3：写了“不要改文件”就等于只读
自然语言只是要求，工具权限才是更可靠的边界。真正的只读 Agent 应避免开放编辑和终端写入工具。
误区4：Agent就是另一个模型
Agent 是模型外部的角色、指令和工具配置。更换 Agent 不一定更换模型。
误区5：MCP是一个新的大模型
MCP 是连接协议，不负责生成答案。模型负责推理，MCP Server 提供工具和数据。
误区6：MCP装得越多越好
工具越多，Agent 的选择空间越大，上下文和权限风险也会增加。只启用与当前任务有关的工具。
误区7：多个Instructions冲突时总有固定覆盖顺序
官方文档说明，多个匹配的规则会被组合进上下文，同类文件之间不应依赖未保证的排列顺序。发现冲突时，应直接整理规则文件。
十一、配置没有生效，怎样排查？
1. Prompt没有出现在斜杠命令中
检查：
- 文件是否位于
.github/prompts/； - 文件名是否以
.prompt.md结尾； - YAML 头部是否完整；
- 是否打开了正确的工作区根目录。
可以在命令面板运行 Chat: Configure Prompt Files 查看 VS Code 实际发现的文件。
2. Instructions没有应用
检查：
.github/copilot-instructions.md是否位于工作区根目录下的.github；*.instructions.md是否位于.github/instructions；applyTo是否匹配当前文件；- 多个规则文件是否互相冲突。
3. 自定义Agent没有出现
检查：
- 文件是否放在
.github/agents/； - 是否使用
.agent.md； name、description和tools的 YAML 格式是否正确；user-invocable是否被设置为false。
4. MCP Server无法启动
在命令面板运行：
MCP: List Servers
然后检查 Server 状态和输出日志。常见原因包括：
- Node.js、Python或对应命令没有安装；
- 命令路径不正确；
- 包下载失败；
- 登录或授权尚未完成；
- 公司策略禁止某类 MCP；
- Server 配置已经更新，但缓存工具列表仍是旧版本。
如果工具定义发生变化，可以使用 MCP: Reset Cached Tools；如果需要重新确认服务器信任，可以使用 MCP: Reset Trust。
5. 不确定VS Code到底加载了哪些配置
在 Chat 视图中打开诊断功能，查看已加载的：
- Agents；
- Prompt files；
- Instruction files；
- Skills；
- 相关错误。
排错时不要只盯着聊天输出，先确认配置文件是否真的被发现。
十二、给初学者的最小实践任务
不建议第一次就同时配置四套复杂系统。可以按下面四步练习：
第一步：只创建Instructions
新建 .github/copilot-instructions.md，写入三条可以验证的项目规则。
第二步：把重复任务变成Prompt
新建 review-python.prompt.md，通过 /review-python 调用两次，确认输出结构稳定。
第三步：创建只读Agent
新建 reviewer.agent.md，只提供搜索和读取类工具，观察它能做什么、不能做什么。
第四步：确有需要时再添加MCP
选择一个可信的 MCP Server，先查看工具列表，只启用一个只读工具完成练习。不要直接在重要项目中开启自动批准。
完成这四步后，你会发现，自己不再是在“寻找神奇提示词”，而是在设计一套可复用、可审查、权限清楚的 AI 工作流。
十三、最后总结
最后用一张表收尾：
| 概念 | 核心问题 | 默认工作区位置 | 激活方式 |
|---|---|---|---|
| Prompt | 这次做什么？ | .github/prompts/*.prompt.md |
用户手动调用 |
| Instructions | 长期遵守什么规则？ | .github/copilot-instructions.md 或 .github/instructions/*.instructions.md |
自动或按文件匹配 |
| Agent | 谁来做、有什么权限？ | .github/agents/*.agent.md |
用户选择、Prompt引用或Agent交接 |
| MCP | 能连接哪些外部能力？ | .vscode/mcp.json 或用户配置 |
Server启动后按需调用 |
再记住一句话：
Prompt写任务，Instructions写规则，
Agent定角色和权限，MCP接工具与数据。
如果只是偶尔问一个问题，直接聊天就够了。
如果一个要求开始重复出现，就应该考虑把它放到正确的配置层。这样不仅可以减少重复输入，更重要的是让 AI 的行为变得稳定、共享、可审查。
🌱 关注专栏，继续完成下一步
下一篇将进行完整实操：10分钟创建一个VS Code只读测试审查Agent，让它只找风险、不乱改文件。
我会提供完整的
.agent.md、.prompt.md、示例缺陷代码和审查结果，继续把“会聊天”升级为“会设计AI工作流”。
参考资料
- Visual Studio Code官方文档：Agent customization总览
- Visual Studio Code官方文档：Prompt files
- Visual Studio Code官方文档：Custom instructions
- Visual Studio Code官方文档：Custom agents
- Visual Studio Code官方文档：Add and manage MCP servers
- Visual Studio Code官方文档：MCP configuration reference
- Model Context Protocol官方介绍
VS Code GitHub Copilot AI编程 Prompt MCP Agent 编程工具 计算机基础
欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！
更多推荐
7
0- 0
已为社区贡献1条内容
所有评论(0)