Appearance
在仓库根目录创建 .github/copilot-instructions.md，Copilot 就会在该仓库的所有对话中自动遵循这些指令。本页介绍如何编写有效的仓库级自定义指令，以及路径级精细控制的配置方法。
为 GitHub 仓库添加 Copilot 自定义指令：让 AI 理解你的项目规范
为什么需要仓库级自定义指令
没有自定义指令时，Copilot 只知道通用的编程规范，不了解你的项目特点：
- 用了哪个框架和版本
- 测试用什么库、怎么运行
- 代码风格有哪些约定
- 有哪些敏感路径需要特殊处理
把这些写入 .github/copilot-instructions.md 后，Copilot 在这个仓库中的所有对话都会自动参考这些背景，不需要每次手动说明。
三种指令文件
1. 仓库全局指令
文件路径：.github/copilot-instructions.md
适合放：技术栈信息、构建/测试命令、代码风格约定、项目结构说明。
markdown
## 技术栈
- 运行时：Node.js 20 + TypeScript 5.3
- 框架：Hono（不是 Express，API 参考 Hono 文档）
- 数据库：PostgreSQL + Drizzle ORM
- 测试：Vitest + supertest
## 常用命令
- 开发：`bun run dev`
- 测试：`bun test`
- 构建：`bun run build`（构建前必须通过所有测试）
## 代码风格
- 所有函数必须有显式的 TypeScript 类型注解
- 禁止 `any` 类型
- 错误处理统一用 Result 模式（参考 src/types/result.ts）
- API 响应格式：`{success: boolean, data?: T, error?: string}`
## 目录结构
- src/routes/ - 路由定义
- src/services/ - 业务逻辑
- src/db/ - 数据库模型和查询
- src/middleware/ - 中间件2. 路径级精细指令
文件路径：.github/instructions/*.instructions.md
适合对特定文件类型或目录单独定义约定：
markdown
---
applyTo: "src/routes/**/*.ts"
---
路由文件规范：
- 每个路由文件只负责一个资源（user、post 等）
- 路由方法不包含业务逻辑，调用对应的 Service 处理
- 参数校验使用 zod schema，不手写 if 校验markdown
---
applyTo: "**/*.test.ts,**/*.spec.ts"
---
测试文件规范：
- 使用 describe/it 结构
- 每个 it 块只测一个行为
- 测试名称用中文描述（中文更清晰）
- 使用 vitest 的 `vi.mock` 做依赖隔离3. Agent 主指令文件
根目录的 AGENTS.md（也可以是 CLAUDE.md）作为主指令文件，适合放最核心的项目说明。
让 Copilot 帮你生成初始指令
如果不确定怎么写，可以让 Cloud Agent 根据仓库现有代码生成初始版本：
在 GitHub.com 的 Copilot Chat 或 IDE Chat 中：
请阅读这个项目的代码，然后在 .github/copilot-instructions.md 中生成一份
包含技术栈、构建/测试步骤、代码规范和目录结构的初始指令文件生成后审查内容并根据实际情况调整。
代码审查中使用自定义指令
Copilot 代码审查也会读取自定义指令。可以专门为 Code Review 添加规则：
markdown
## 代码审查指令
进行代码审查时，用中文写评论。
重点检查：
- 所有数据库查询是否有 SQL 注入风险
- API 响应是否暴露了不该暴露的字段
- 新增的外部包是否在 package.json 中锁定了版本可以在仓库设置 → Copilot → Code review 中启用/禁用代码审查的自定义指令（默认启用）。
指令优先级
当多个指令文件同时存在时，优先级从高到低：
- 个人级指令（用户账号级别的配置）
- 仓库级
.github/copilot-instructions.md - 路径级
.github/instructions/*.instructions.md - 全局默认
常见问题
Q: 自定义指令文件会影响 Copilot 的响应速度吗？
A: 轻微影响。指令文件会包含在每次请求的 context 中，文件越长，消耗的 token 越多，响应时间可能略有增加。官方建议保持指令简洁（100~200 行以内）。
Q: 路径级指令的 applyTo 支持哪些格式？
A: 支持 glob 语法，例如：**/*.ts（所有 TypeScript 文件）、src/api/**（api 目录下所有文件）、**/*.test.ts,**/*.spec.ts（测试文件，逗号分隔多个 pattern）。
Q: 多个开发者使用同一个仓库，自定义指令对所有人生效吗？
A: 是的，.github/copilot-instructions.md 存储在仓库中，所有有权限的开发者使用 Copilot 时都会自动读取。这样可以确保团队的 AI 使用规范保持一致。