05 · Copilot 的上下文工程

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

1. Copilot 的上下文来源

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。
• 审查和构建命令。

不适合写进去：

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

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"，下次进同一个仓库直接用。

选择规则：

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

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

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

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

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

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

任务：
修复登录后刷新页面丢失 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：官方 custom instructions、prompt files、优先级和写法原则。
• GitHub Copilot features：官方 customization 能力清单，包含 Spaces、Memory、MCP、skills 和 custom agents。
• Tools in VS Code：VS Code 官方工具机制，说明 built-in、MCP、extension tools 和批准边界。
• About Model Context Protocol：GitHub 官方 MCP 概念页。

接下来去哪