Appearance
每次向 Copilot 提问时都要重复说明"用 TypeScript、不用 any、测试用 Vitest"吗？自定义指令解决了这个问题。本页介绍 Copilot 的三种指令类型——个人、仓库、组织——以及写出好指令的关键原则。
GitHub Copilot 自定义指令系统：三种方式让 AI 理解你的偏好
为什么需要自定义指令
没有自定义指令时，Copilot 只有通用知识，不了解你的具体偏好和项目规范。每次对话你都要重复说明：
- "用中文回答"
- "这个项目用 Drizzle ORM，不要用 Prisma"
- "测试文件用 Vitest，不用 Jest"
- "错误处理用 Result 模式"
把这些写成自定义指令后，Copilot 在每次对话时会自动参考，不需要手动说明。
三种指令类型
个人指令
适用范围：只影响你自己的 Copilot Chat 对话（在 GitHub.com 上）
配置位置：GitHub.com → Settings → Copilot → Personal instructions
适合放个人偏好：
markdown
用中文回答所有问题。
代码示例优先使用 TypeScript，而不是 JavaScript。
在回答技术问题时，先给结论，再给解释。注意：个人指令目前只在 GitHub.com 的 Copilot Chat 中生效，不影响 IDE Chat。
仓库指令（全局）
适用范围：仓库内所有开发者的 Copilot 对话
文件路径：.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 }`仓库指令（路径级）
文件路径：.github/instructions/*.instructions.md
在文件头部用 applyTo 指定适用范围：
markdown
---
applyTo: "src/routes/**/*.ts"
---
路由文件规范：
- 每个路由文件只负责一个资源（user、post 等）
- 路由方法不包含业务逻辑，统一调用对应 Service
- 参数校验使用 zod schema，禁止手写 if 校验markdown
---
applyTo: "**/*.test.ts,**/*.spec.ts"
---
测试文件规范：
- 使用 describe/it 结构
- 每个 it 块只测一个行为
- 测试名称用中文描述（中文更清晰）组织指令（Enterprise/Business 专属）
适用范围：组织内所有成员的 Copilot 对话
配置位置：组织 Settings → Copilot → Custom instructions
适合由管理员统一设置的团队规范，例如：
markdown
对所有代码审查评论使用中文。
在涉及数据库查询时，始终检查 SQL 注入风险。指令优先级（从高到低）
- 个人指令
- 仓库路径级指令（
.github/instructions/） - 仓库全局指令（
.github/copilot-instructions.md） - 组织指令
如果多条指令有冲突，优先级高的指令生效。
写出好指令的原则
简洁、可执行、不含歧义：
markdown
# 好的写法
用中文回答所有问题。
测试用 Vitest，不用 Jest。
错误处理用 Result 模式（参考 src/types/result.ts）。
# 不好的写法
请始终考虑到项目的整体架构，并在提供建议时确保与现有代码风格保持一致……（太模糊）避免过长：官方建议 100~200 行以内。指令越长，消耗 token 越多，响应略慢，且关键信息容易被稀释。
不要让 Copilot 总是查询外部资源：比如"每次回答前先查官方文档"这类指令效果不可靠。
和 Claude Code CLAUDE.md 的对比
| 特性 | .github/copilot-instructions.md | CLAUDE.md |
|---|---|---|
| 工具 | GitHub Copilot | Claude Code |
| 路径级支持 | ✅ .github/instructions/*.instructions.md | ✅ 子目录 CLAUDE.md |
| 组织级配置 | ✅ 企业/Business | ✅ 通过 settings.json 的 systemPrompt |
| 个人级配置 | ✅ GitHub.com 设置 | ❌ 无个人级，但有全局 ~/.claude/CLAUDE.md |
常见问题
Q: 仓库里写了 copilot-instructions.md，团队其他人的 Copilot 会自动生效吗？
A: 是的。只要团队成员在该仓库里使用 Copilot（无论是 IDE Chat 还是 GitHub.com Chat），都会自动读取这个文件。
Q: 路径级指令的 applyTo 支持什么格式？
A: 支持 glob 语法：**/*.ts（所有 TS 文件）、src/api/**（api 目录下所有文件）、**/*.test.ts,**/*.spec.ts（测试文件，逗号分隔）。
Q: 指令文件会影响 Copilot 代码补全（inline suggestions）吗？
A: 不影响。自定义指令只对 Copilot Chat 生效，不影响 inline suggestions（ghost text）。