Copilot CLI 支持多层次的自定义指令配置：全局 ~/.copilot/copilot-instructions.md、仓库级 .github/copilot-instructions.md、路径级 .github/instructions/*.instructions.md。指令自动注入每次请求，无需在每次对话中重复说明项目背景。

GitHub Copilot CLI 自定义指令：让 AI 记住你的项目规范

为什么需要自定义指令

没有自定义指令时，你可能每次都要告诉 Copilot："我们用 TypeScript，不要用 class，错误处理用 Result 模式……" 这很繁琐。

自定义指令解决这个问题：写一次，每次自动注入。Copilot 会在生成回答前先读取这些指令，就像上岗培训一样——你不需要在每条消息里重复说明。

四种指令文件

1. 全局指令（对所有项目生效）

文件路径：~/.copilot/copilot-instructions.md

## 我的偏好
- 代码注释用中文
- 函数命名用 camelCase
- 尽量避免深层嵌套，优先用 early return

2. 仓库级指令（优先级高于全局）

文件路径：项目根目录的 .github/copilot-instructions.md

## 本项目技术栈
- 运行时：Node.js 20 + TypeScript 5
- 框架：Express（不用 Fastify）
- ORM：Prisma
- 测试：Vitest

## 提交前必须运行
bun run lint && bun test && bun run build

3. 路径级指令（精细控制特定文件类型）

在 .github/instructions/ 下创建 *.instructions.md 文件，通过 frontmatter 指定作用范围：

---
applyTo: "src/api/**/*.ts"
---
API 路由必须包含：
- 参数校验（用 zod）
- 错误处理（返回统一格式 {success, data, error}）
- 日志记录（入参 + 出参 + 耗时）

也可以排除特定 Agent：

---
applyTo: "**/*.test.ts"
excludeAgent: "code-review"
---
测试文件规范：一个 it 只测一件事，用 arrange-act-assert 结构

4. AGENTS.md 主指令

根目录的 AGENTS.md 被视为主指令文件（也兼容 CLAUDE.md、Copilot.md 等）。适合把最重要的项目规范集中在这里：

# 项目指令

## 架构原则
模块之间通过接口通信，禁止跨层直接调用

## 代码规范
见 .github/copilot-instructions.md

## 重要路径
- API：src/api/
- 数据模型：src/models/
- 数据库迁移：prisma/migrations/

指令优先级

当多个指令文件都匹配时，优先级从高到低：

1. .github/copilot-instructions.md（仓库级）
2. .github/instructions/*.instructions.md（路径级）
3. AGENTS.md（根目录主指令）
4. ~/.copilot/copilot-instructions.md（全局）

仓库级指令会覆盖全局指令的同类配置。

何时生效

• 保存指令文件后立即对下一次请求生效
• 不需要重启 CLI 或刷新会话

通过环境变量指定额外的指令目录

export COPILOT_CUSTOM_INSTRUCTIONS_DIRS="/path/to/shared/instructions"

适合团队共享一套跨项目指令。

和 IDE Chat 的 Custom Instructions 区别

功能	Copilot CLI	IDE Chat
共享 .github/copilot-instructions.md	✅	✅
全局个人指令	~/.copilot/copilot-instructions.md	IDE 的 User Settings 中配置
路径级 .github/instructions/	✅	✅
环境变量配置额外目录	✅	❌

常见问题

Q: 指令文件写多长合适？

A: 官方建议"简洁、可操作"。一般来说 50~150 行就够了，重点说清楚：技术栈、代码风格、必须遵守的约定、构建/测试命令。太长的指令可能被截断或降低回答质量。

Q: 可以在指令文件里写负面规则（禁止做什么）吗？

A: 可以，而且很有效。比如"禁止使用 any 类型"、"禁止在 API 路由中直接调用数据库，必须通过 Service 层"。Copilot 会把这些规则作为约束。

Q: 我们团队有不同的子项目，每个子项目规范不一样，怎么管理？

A: 在每个子项目目录下分别放 .github/copilot-instructions.md，或者用 .github/instructions/ 下的路径级指令按目录区分。路径级的 applyTo 支持 glob 模式，可以精细匹配到具体的子目录。