Copilot 指令文件全解析：copilot-instructions.md、AGENTS.md 与 .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 更贴合你的项目需求：

1. 基础能力优先级：.instructions.md（局部） > .github/copilot-instructions.md（全局） > Copilot 官方默认配置；
2. 功能隔离原则：AGENTS.md 只作用于 Agent 功能，和另外两个文件没有优先级冲突，即使配置了全局指令，Agent 也只会按 AGENTS.md 的要求执行任务；
3. 实战建议：
   • 小型项目：只需要配置 .github/copilot-instructions.md，足够覆盖大部分场景；
   • 中大型项目：全局指令 + 局部指令结合，复杂自动化任务用 AGENTS.md；
   • 多人协作：把三个文件都纳入 Git 版本管理，确保团队所有人的 Copilot 行为一致。

五、常见问题排查

最后，整理几个实测时遇到的坑，帮你避坑：

1. copilot-instructions.md 不生效：检查路径是否为 .github/ 目录（不是 .vscode/），文件名是否严格匹配（大小写敏感）；
2. Agent 不执行指定任务：确认 AGENTS.md 中任务描述是否清晰，是否手动触发了「Run Agent」功能（不是普通的代码补全）；
3. .instructions.md 覆盖范围异常：该文件会作用于当前目录及所有子目录，若想仅作用于单个文件，可将文件放在单独目录，或在指令中明确指定文件名。

总结

其实 Copilot 的这三个指令文件，核心逻辑就是'粒度分层'和'功能隔离'：

• 按粒度分：全局（copilot-instructions.md）和局部（.instructions.md）；
• 按功能分：基础补全（前两者）和进阶自动化（AGENTS.md）。

搞懂这个逻辑，再结合项目实际需求配置，就能让 Copilot 从'通用助手'变成'专属项目管家'，不管是日常编码补全，还是复杂的 Agent 自动化任务，都能精准贴合你的开发习惯。