GitHub Copilot 自定义指令文件的项目作用域

团队把 GitHub Copilot 用进项目后，最容易遇到的不是不会写指令，而是指令放错了作用域：写在个人设置里，别人看不到；只写一份仓库级规则，又无法区分源码和测试目录。更稳妥的做法是把团队共用约定放进项目，再用路径级文件补充目录规则。

官方地址：https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions

先分清三种作用域，避免规则写在错误位置

项目级自定义指令解决的是“这个仓库希望 Copilot 怎样工作”。它应该随着代码一起进入版本控制，让新成员打开同一个项目时得到一致的约束。个人指令解决的是“我习惯怎样提问或表达”，不适合承载团队必须遵守的测试命令。

这里的关键判断是：如果规则需要提交给团队，就放进仓库；如果只服务某一类文件，就放进路径级文件；如果只是个人习惯，才保留在个人设置。不要把三者混成一个“全局提示词”。

创建仓库级 copilot-instructions.md

先在 VS Code 中打开目标项目：选择“文件”>“打开文件夹”，确认资源管理器的根节点就是仓库根目录。然后在资源管理器依次新建文件夹 .github，再在其中新建 copilot-instructions.md。文件名、点号和目录层级都不要改写。

第一份文件只放全仓库都适用的规则，例如项目使用什么命令、提交代码前要运行哪些测试、生成代码时需要遵循什么边界：

# 项目协作约定


- 修改 Go 服务后运行 `go test ./...`。
- 优先复用 `internal/` 中已有的接口，不新增重复的适配层。
- 改动配置时同时说明默认值、失败处理和回滚方式。
- 生成代码前先阅读同目录的现有实现，保持命名和错误返回风格一致。

保存后，这份文件就是项目的基础上下文。它不要求你把每个任务都写成提示词，也不应该塞进某个具体工单的临时要求。规则越稳定、越容易在团队中复用，越适合放在这里。

用 instructions 文件细分目录规则

当源码和测试需要不同约束时，在 .github/instructions 下新建以 .instructions.md 结尾的文件，并在文件头写 applyTo。例如下面的文件只针对 src 目录下的 TypeScript 文件：

---
applyTo: "src/**/*.ts"
---



- 组件输入先定义明确的类型，不用隐式的 `any`。
- 异步请求统一经过项目的请求封装，并处理加载和失败状态。
- 修改公共组件时补充对应的单元测试。

测试目录可以有另一份规则，例如 .github/instructions/tests.instructions.md：

---
applyTo: "tests/**/*.ts"
---



- 测试名称说明行为和预期结果。
- 外部请求使用仓库已有的 mock 工具。
- 每个失败断言都保留能定位输入条件的上下文。

路径模式是这一步的核心。src/**/*.ts 只会覆盖匹配的 TypeScript 文件；如果模式写成了不存在的目录，规则不会因为文件内容正确就自动生效。仓库级文件提供共同基础，命中的路径级文件再补充专属要求，两者可以同时进入当前请求的上下文。

在 Copilot Chat 中确认当前项目确实命中规则

文件写好后，按下面的顺序做一次使用侧确认：

1. 在资源管理器选中一个匹配目标，例如 src/components/Button.ts，确保它属于当前已打开的工作区。
2. 打开 Copilot Chat，先发送一个与项目约定有关的小问题，例如“这个组件应该使用哪条测试命令？”。
3. 展开回答顶部的引用或上下文信息，查看是否出现仓库级指令文件；如果请求命中了路径规则，也检查对应的 *.instructions.md 是否在当前上下文中。
4. 切换到 tests 下的文件重复一次，观察命中的路径规则是否随文件范围变化。

这一步检查的是“当前请求使用了哪些上下文”，不是让 Copilot 机械复述整份文件。若回答没有体现规则，先确认文件已经保存、工作区根目录正确、路径模式能够匹配，再考虑是否需要精简冲突指令。

常见边界：规则不生效时先看位置和匹配范围

当前资料入口也可以直接收藏：https://docs.github.com/en/copilot/reference/custom-instructions-support。不同编辑器对支持范围和界面入口可能略有差异，但文件位置、路径匹配和版本控制这三个判断仍然是排错起点。

相关问题

仓库级文件和路径级文件要二选一吗？

不需要。仓库级文件负责共同约定，路径级文件负责更窄的补充规则；当前请求命中路径时，两者可以一起提供上下文。

个人指令可以替代项目级文件吗？

不适合。个人指令不会自然地随仓库提交，团队成员也未必拥有相同内容。项目构建、测试和代码风格应放进仓库文件。

为什么写了 applyTo 仍然没有命中？

最常见原因是工作区根目录或 glob 模式不对。先从目标文件的实际路径反推模式，再确认文件位于 .github/instructions 且已经保存。