---
title: "05 · Copilot 的上下文工程"
description: "解释仓库索引、打开文件、选择上下文、Spaces、MCP 和自定义指令如何影响 Copilot 输出质量。"
verifiedAt: "2026-05-06"
---

Copilot 输出差，很多时候不是“模型不行”，而是上下文工程（context engineering）没做好。它看错文件、读到过期规则、没拿到 issue 背景、被冲突 instructions 干扰，结果就会像一个不了解项目的人在猜。

> [!NOTE]
> **本章目标**：你会知道 Copilot 的上下文来自哪里，如何用自定义指令（custom instructions）、提示词文件（prompt files）、Copilot Spaces、MCP 和文件选择来控制输出质量，以及哪些规则不能写进去。

## 1. Copilot 的上下文来源

```mermaid
flowchart TD
  Request["一次 Copilot 请求"] --> Local["本地上下文"]
  Request --> Repo["仓库规则"]
  Request --> GitHub["GitHub 对象"]
  Request --> Custom["定制能力"]
  Request --> Tools["工具和外部系统"]
  Local --> Files["打开文件 / 选区 / diff / terminal"]
  Repo --> Instructions[".github/copilot-instructions.md / AGENTS.md"]
  GitHub --> Objects["issue / PR / branch / checks"]
  Custom --> Prompt["prompt files / Spaces / Memory"]
  Tools --> MCP["MCP servers / agent skills / custom agents"]
  Files --> Answer["Copilot 输出"]
  Instructions --> Answer
  Objects --> Answer
  Prompt --> Answer
  MCP --> Answer
```

上下文工程不是堆信息。目标是让 Copilot 在合适的时刻看见合适的信息，并且不要被无关信息和冲突规则污染。

## 2. 文件上下文：先给它正确现场

IDE 里的 Copilot 会受当前文件、选区、打开的相关文件、工作区、diff、diagnostics 和 terminal output 影响。你要它修登录 bug，却只打开按钮组件，它很可能围绕 UI 猜，而不是去看 auth service、session storage 或 route guard。

实操规则：

- 问局部代码：选中具体函数或打开相邻文件。
- 问项目结构：先让它列入口、路由、配置和测试位置。
- 让 Agent 改代码：明确允许修改的目录和禁止触碰的目录。
- 让它解释错误：贴完整报错、命令、运行环境和最近 diff。
- 让它审 PR：回到 PR diff、checks 和 review comments。

Copilot 不是读心工具。上下文不明确时，先用 Ask 或 Plan，而不是直接让 Agent 写。

## 3. Custom instructions：稳定规则才写进去

GitHub 官方响应定制页列出几类 instructions：

- **Personal instructions**：个人偏好。
- **Repository-wide instructions**：`.github/copilot-instructions.md`。
- **Path-specific instructions**：`.github/instructions/**/*.instructions.md`。
- **Agent instructions**：`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`。
- **Organization instructions**：组织级规则。

官方说明的优先级是：

1. Personal instructions。
2. Path-specific instructions。
3. Repository-wide instructions。
4. Agent instructions。
5. Organization instructions。

这意味着团队不能随便堆规则。优先级不同、作用域不同，冲突会让输出变得不稳定。

适合写进 instructions：

- 项目用途和目录职责。
- 稳定技术栈和版本约束。
- 编码风格、错误处理、测试要求。
- 安全红线，例如不要记录 token。
- 审查和构建命令。

不适合写进去：

- 一次性任务。
- 过期迁移步骤。
- 密钥、账号、客户信息。
- 含糊口号。
- 和已有规则冲突的偏好。

> [!IMPORTANT]
> 官方文档还提示：Copilot code review 只读取每个 custom instruction file 的前 4,000 字符。规则要短、稳定、可审查。

## 4. Prompt files 和 Spaces：复用任务上下文

Prompt file 适合把某类重复任务写成可复用请求，例如"按团队规范写测试""审查 API 兼容性""生成 release note 草稿"。它比 instructions 更适合任务型内容，因为它不是每次都自动注入。

Spaces 更适合把相关资料组织成一个可复用上下文包，例如一个项目、一个功能域、一组设计文档或团队知识。它的价值不是让 Copilot 读更多，而是让多人在同一套上下文里协作。

**新手类比**：把这几样想成"给 Copilot 配工作环境"——

- **Custom instructions** 像贴在工位墙上的便利贴：永远在视线里，每次工作都自动看到（团队代码规范、命名约定）。
- **Prompt files** 像抽屉里的固定流程清单：要做"周报""代码审查"这类重复活时取出来用，平时不打扰你（"按 PR 模板写摘要"的标准 prompt）。
- **Copilot Spaces** 像专题文件夹：把"做好这件事需要的所有材料"装进去（产品需求文档 + 设计稿 + 历史决策 + 代码片段）然后打包给 Copilot。
- **MCP** 像给 Copilot 装电话和钥匙：让它能联系外部系统（查 Jira issue、读数据库 schema、跑监控告警）。
- **Memory** 像 Copilot 的长期记忆笔记：它自己记下"这个仓库的命名规范是 camelCase""错误处理统一抛 BizError"，下次进同一个仓库直接用。

选择规则：

| 内容 | 放哪里 | 一句话场景 |
| --- | --- | --- |
| 长期项目规则 | instructions | "本仓库测试用 vitest，不用 jest" |
| 某类重复任务 | prompt file | 每次写 PR 摘要都要按 5 段格式 |
| 多资料上下文包 | Spaces | 一个新功能要参考 5 篇文档 + 3 个仓库片段 |
| 外部系统和工具 | MCP | 让 Copilot 查 Jira / 数据库 / 监控 |
| 临时 bug 现场 | 当前 prompt / issue | 这次重启服务报这个错 |

## 5. MCP：外部上下文也是权限

MCP server 可以把 Copilot 接到外部工具和数据源。GitHub 官方把 MCP 放进 customization 和 context 扩展体系里，VS Code Agent 工具文档也把 MCP tools 视为 agent 可调用工具的一类。

这会明显提升能力，也会扩大风险：

- 数据库、工单、云平台、日志系统可能包含敏感信息。
- 工具输出会进入模型上下文。
- 有副作用的工具必须经过批准。
- 过多 MCP 会让 agent 探索无关系统。

团队策略应该是按任务开工具，而不是默认全开。

## 6. 一个可执行的上下文模板

```text
任务：
修复登录后刷新页面丢失 session 的问题

上下文：
先看 src/auth、src/routes 和 tests/auth
参考 issue #123 的复现步骤

规则：
遵守 .github/copilot-instructions.md
只改 auth 和 tests/auth
不要修改支付、部署和数据库迁移

验收：
说明改动计划
展示 diff
运行 auth 相关测试
```

这个模板的关键不是格式，而是让 Copilot 同时拿到任务、上下文、边界和验收标准。

## 7. 调试坏上下文

当 Copilot 输出明显跑偏，按这个顺序排查：

1. 它是否看到了正确文件？
2. 是否缺少 issue、PR、报错或终端输出？
3. instructions 是否过期或冲突？
4. path-specific instructions 是否覆盖了当前路径？
5. MCP 是否打开了无关工具？
6. 任务是否应该先 Plan，而不是直接 Agent？

不要用更长 prompt 掩盖坏上下文。先把错误上下文拿掉，再补必要信息。

## 本章自检

你应该能回答：

- 当前 Copilot 请求会读取哪些上下文？
- 哪些规则是自动注入，哪些是本次任务临时提供？
- instructions 是否短、稳定、无冲突、无敏感信息？
- MCP 工具是否按任务最小授权？

通过标准：你能控制 Copilot 看什么、不看什么、能做什么，并把输出回到 diff 和测试验证。

## 官方来源

- [About customizing GitHub Copilot responses](https://docs.github.com/en/copilot/concepts/prompting/response-customization)：官方 custom instructions、prompt files、优先级和写法原则。
- [GitHub Copilot features](https://docs.github.com/en/copilot/get-started/features)：官方 customization 能力清单，包含 Spaces、Memory、MCP、skills 和 custom agents。
- [Tools in VS Code](https://code.visualstudio.com/docs/copilot/concepts/tools)：VS Code 官方工具机制，说明 built-in、MCP、extension tools 和批准边界。
- [About Model Context Protocol](https://docs.github.com/en/copilot/concepts/context/model-context-protocol)：GitHub 官方 MCP 概念页。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先理解 Copilot 从补全到 Agent 和 Cloud Agent 的演进。" href="/docs/github-copilot/understanding/04-from-autocomplete-to-agent" />
  <Card title="下一篇" description="继续进入 VS Code Agent Mode 的真实使用方式。" href="/docs/github-copilot/understanding/06-agent-mode-in-vscode" />
  <Card title="响应定制" description="回到官方重组页深读 custom instructions、优先级和 4000 字符限制。" href="/docs/github-copilot/official/02-code-suggestions-and-chat/response-customization" />
</Cards>
