Copilot 指令文件全解析:copilot-instructions.md vs AGENTS.md vs .instructions.md
作为常年和 VS Code 打交道的研发,最近在折腾 Copilot Agent 时,发现很多同学被 .github/copilot-instructions.md、AGENTS.md 和 .instructions.md 这三个文件绕晕了。
明明都是给 Copilot 写的'指令',为什么要分三个文件?它们的生效范围有啥区别?什么时候该用哪一个?
带着这些疑问,翻遍官方文档并在 AI Agent 项目中反复实测,终于把这三者的关系理得清清楚楚。本文结合实战配置,帮你彻底搞懂 Copilot 指令文件的使用逻辑。
一、先搞懂核心:三者的定位差异
在讲细节前,先用一个通俗的类比定调,这能帮你快速建立认知:
.github/copilot-instructions.md:项目的'全局家规',管整个仓库的所有 Copilot 基础交互;AGENTS.md:Copilot Agent 的'任务清单',只服务于 Agent 进阶自动化功能;.instructions.md:目录的'局部特例',管特定文件夹的 Copilot 基础交互,优先级最高。
简单来说:前两者是'全局 vs 专属功能'的区别,后两者是'全局 vs 局部'的区别,而 AGENTS.md 则是完全独立的'进阶功能配置'。
二、三者核心辨析(一张表搞定)
为了方便查阅,将三者的关键差异整理成表格:
| 特性 | .github/copilot-instructions.md | AGENTS.md | .instructions.md |
|---|---|---|---|
| 核心定位 | 项目级全局通用指令文件 | Copilot Agent 专属任务配置文件 | 目录 / 文件级细粒度指令文件 |
| 生效范围 | 整个代码仓库(所有文件、目录) | 仅 Copilot Agent 功能(手动触发时生效) | 仅当前文件所在目录及子目录 |
| 作用对象 | Copilot 基础能力(补全、注释、代码解释) | 仅 Copilot Agent 进阶功能(自动化任务) | Copilot 基础能力(同左,仅局部生效) |
| 触发方式 | 被动生效(Copilot 自动读取) | 主动触发(VS Code 中手动点击「Run Agent」) | 被动生效(Copilot 自动读取) |
| 存放路径 | 强制:仓库根目录 /.github/(大小写敏感) | 无强制(建议放 .github/ 或项目根目录) | 无强制(放在需要生效的目标目录下) |
| 内容风格 | 项目规则、技术栈、业务背景描述 | 具体任务步骤、执行目标、输出要求 | 局部特殊规范、目录专属业务逻辑 |
| 优先级 | 高于 Copilot 全局默认,低于 .instructions.md | 独立优先级(不与其他两者冲突) | 最高(覆盖全局规则) |
| 典型场景 | 定义全仓库编码规范、技术栈要求 | 代码重构、批量文档生成、漏洞扫描 | 特定模块的特殊命名规则、依赖限制 |
三、实战配置:手把手教你用对文件
光看理论不够,结合 AI Agent 项目(基于 Python 开发),提供三个可直接复制的配置示例,对应不同的使用场景。
场景 1:项目全局规范 → 用 copilot-instructions.md
示例项目是一个 AI Agent 工具开发仓库,技术栈为 Python 3.11+、FastAPI,需要全仓库统一编码规范。
存放路径:项目根目录/.github/copilot-instructions.md
配置内容:
# Copilot 项目全局指令
## 1. 技术栈与编码规范
- 编程语言:Python 3.11+,严格遵循 PEP 8 规范
- 命名规则:函数用小驼峰,类用大驼峰,常量全大写加下划线,Agent 相关类名必须以「Agent」结尾
- 注释要求:核心函数必须写中文文档字符串(docstring),包含入参、出参、功能描述
## 2. 业务背景说明
本项目是一款轻量级 AI Agent 调度工具,核心模块包括:任务解析、技能调度、结果返回。
- 任务解析模块:负责解析用户输入的自然语言任务
- 技能调度模块:调用 OpenCode、Smithery 等第三方技能
- 结果返回模块:将 Agent 执行结果格式化为 Markdown 输出
## 3. 依赖限制
- 优先使用项目虚拟环境中的依赖,禁止随意引入未在 requirements.txt 中声明的库
- 网络请求统一使用项目封装的 `src/utils/request.py` 中的 Axios 实例
配置完成后,不管在 src/ 还是 tests/ 目录写代码,Copilot 都会自动遵循这些规则,比如定义 Agent 类时,会自动补全「Agent」后缀。
场景 2:Agent 自动化任务 → 用 AGENTS.md
需要让 Copilot Agent 自动完成「项目代码质量检查」的任务,包括类型注解检查、异常处理检测,并生成报告。
存放路径:项目根目录/.github/AGENTS.md(建议和全局指令放一起,方便管理)
配置内容:
# Copilot Agent 任务指令集
## 任务 1:代码质量检查(核心任务)
1. 执行范围:遍历项目 `src/` 目录下所有 `.py` 文件
2. 检查项:
- 所有函数和类方法是否包含完整的类型注解(入参、出参)
- 是否存在未处理的异常(无 try-except 包裹的危险操作)
- 导入语句是否存在未使用的情况
3. 输出要求:
- 以 Markdown 格式生成检查报告,分为「问题清单」和「修复建议」两部分
- 对每个问题,附上具体文件路径、行号和对应的修复代码片段
## 任务 2:API 文档生成
1. 执行范围:`src/api/` 目录下的所有 FastAPI 路由文件
2. 执行要求:提取所有接口的路径、请求方式、入参、出参
3. 输出要求:生成 `API 文档.md`,保存到项目根目录
使用方式:在 VS Code 中打开 Copilot 面板,点击「Run Agent」,选择对应的任务,Copilot 就会按照配置自动执行。
场景 3:局部目录特殊规则 → 用 .instructions.md
项目 src/admin/ 目录是后台管理模块,需要和核心模块区分开,组件命名必须以「Admin」为前缀,且禁止使用 FastAPI 的自动文档功能。
存放路径:项目根目录/src/admin/.instructions.md
配置内容:
# 后台管理模块专属指令
1. 命名规则:所有类、函数、组件命名必须以「Admin」为前缀(如 AdminUserService、admin_get_user_list)
2. 功能限制:禁止使用 FastAPI 的 `docs_url` 和 `redoc_url` 配置,后台接口无需生成自动文档
3. 业务要求:所有后台接口必须包含权限校验逻辑,需调用 `src/utils/auth.py` 中的 `check_admin_permission` 函数
此时,即使全局指令要求遵循 FastAPI 文档规范,Copilot 在 src/admin/ 目录下写代码时,也会优先遵循这个局部规则。
四、优先级与协同使用技巧
在实际开发中,这三个文件往往会同时存在,掌握它们的协同逻辑,能让 Copilot 更贴合你的项目需求:
- 基础能力优先级:
.instructions.md(局部) >.github/copilot-instructions.md(全局) > Copilot 官方默认配置; - 功能隔离原则:
AGENTS.md只作用于 Agent 功能,和另外两个文件没有优先级冲突,即使配置了全局指令,Agent 也只会按AGENTS.md的要求执行任务; - 实战建议:
- 小型项目:只需要配置
.github/copilot-instructions.md,足够覆盖大部分场景; - 中大型项目:全局指令 + 局部指令结合,复杂自动化任务用
AGENTS.md; - 多人协作:把三个文件都纳入 Git 版本管理,确保团队所有人的 Copilot 行为一致。
- 小型项目:只需要配置
五、常见问题排查
最后,整理几个实测时遇到的坑,帮你避坑:
- copilot-instructions.md 不生效:检查路径是否为
.github/目录(不是.vscode/),文件名是否严格匹配(大小写敏感); - Agent 不执行指定任务:确认
AGENTS.md中任务描述是否清晰,是否手动触发了「Run Agent」功能(不是普通的代码补全); - .instructions.md 覆盖范围异常:该文件会作用于当前目录及所有子目录,若想仅作用于单个文件,可将文件放在单独目录,或在指令中明确指定文件名。
总结
其实 Copilot 的这三个指令文件,核心逻辑就是'粒度分层'和'功能隔离':
- 按粒度分:全局(copilot-instructions.md)和局部(.instructions.md);
- 按功能分:基础补全(前两者)和进阶自动化(AGENTS.md)。
搞懂这个逻辑,再结合项目实际需求配置,就能让 Copilot 从'通用助手'变成'专属项目管家',不管是日常编码补全,还是复杂的 Agent 自动化任务,都能精准贴合你的开发习惯。


