Appearance
GitHub Copilot custom instructions（自定义指令）让你把项目规范、编码风格、技术栈偏好写进 Markdown 文件，Copilot 每次生成代码时都会参考这些上下文。对于团队开发，这是统一 AI 输出风格的关键工具，类似 Claude Code 中的 CLAUDE.md。
GitHub Copilot 自定义指令：用 .github/copilot-instructions.md 控制 AI 行为
什么是 custom instructions
custom instructions 是存放在仓库里的 Markdown 文件，Copilot 在处理你的请求时会自动读取并参考它们。你不需要每次手动粘贴背景信息——这些指令会静默附加到每次对话中。
和 Claude Code 的 CLAUDE.md、Kiro 的 steering 文件功能类似，是 AI 编程工具的通用"项目规范注入"机制。
三种指令文件类型
1. 仓库全局指令（最常用）
文件位置：.github/copilot-instructions.md
对整个仓库的所有请求生效。适合写：
- 项目架构说明
- 技术栈和版本约束
- 命名规范、代码风格
- 测试框架和规范
示例内容：
markdown
# 项目规范
## 技术栈
- 前端：React 18 + TypeScript 5
- 后端：Node.js 20 + Fastify
- 数据库：PostgreSQL 15，使用 Drizzle ORM
## 编码规范
- 所有函数必须有 JSDoc 注释
- 使用函数式组件，禁止 class 组件
- 错误处理使用 Result 模式，不抛出裸 Error
## 测试
- 使用 Vitest，覆盖率要求 80%+
- 所有 API 端点必须有集成测试2. 路径级指令（VS Code 支持）
文件位置：.github/instructions/NAME.instructions.md
通过 frontmatter 的 applyTo 字段指定适用范围：
markdown
---
applyTo: "**/*.ts,**/*.tsx"
---
TypeScript 文件使用严格模式，所有参数和返回值必须有类型注解。
禁止使用 `any`，用 `unknown` + 类型守卫代替。markdown
---
applyTo: "**/*.test.ts"
---
测试文件遵循 AAA 模式：Arrange（准备）、Act（执行）、Assert（断言）。
describe 块用中文描述功能，it/test 块用中文描述预期行为。3. Agent 指令文件
文件名：仓库任意位置的 AGENTS.md
专门为 AI Agent 模式提供上下文，适合描述构建流程、部署环境、危险操作清单等。
如果不想让某个特定 Agent 读取这个文件：
markdown
---
applyTo: "**"
excludeAgent: "code-review"
---Prompt 文件（可复用的对话模板）
Prompt 文件是 .github/prompts/ 目录下的 .prompt.md 文件，可以把常用的对话模板保存起来重复使用。
markdown
# generate-component.prompt.md
创建一个新的 React 组件，遵循以下规范：
- 使用 TypeScript
- 使用 CSS Modules 样式
- 包含 Storybook Story
- 参考 #file:src/components/Button/Button.tsx 的结构在 VS Code 中，通过 Chat 附件图标或 Attach context 按钮引用 Prompt 文件。在 JetBrains 中，输入 /generate-component（文件名去掉 .prompt.md）即可调用。
验证指令是否生效
在 Copilot Chat 的回答下方有 References（引用）展开区，如果看到 .github/copilot-instructions.md 出现在列表中，说明指令已被 Copilot 读取。
全局指令（跨仓库生效）
JetBrains 的全局指令文件位置：
- macOS：
/Users/你的用户名/.config/github-copilot/intellij/global-copilot-instructions.md - Windows：
C:\Users\你的用户名\AppData\Local\github-copilot\intellij\global-copilot-instructions.md
VS Code 也支持通过设置 UI 配置个人级别的 custom instructions（不在仓库文件中，存在用户设置里）。
写指令的几个建议
- 具体优于宽泛：
使用 Vitest 写测试比遵循测试最佳实践有用得多 - 描述为什么，不只是说什么：
禁止使用 any（原因：我们的 runtime 校验层依赖类型推断） - 保持简短：指令太长会稀释关键信息，优先写最影响 Copilot 输出质量的规范
- 团队共享：提交进 git，所有团队成员自动获得一致的 AI 行为
常见问题
Q: 仓库指令和个人指令哪个优先级更高？
A: 两者都会被 Copilot 读取并综合考虑，不存在严格的覆盖关系。如果有冲突，Copilot 会尽量调和，但建议避免写相互矛盾的内容。
Q: 自定义指令对 inline suggestions（内联补全）也生效吗？
A: 主要对 Copilot Chat 生效。内联建议也会参考仓库上下文，但自定义指令对内联建议的影响相对有限。
Q: 这和 Claude Code 的 CLAUDE.md 有什么区别？
A: 功能上非常类似，都是向 AI 注入项目规范。格式也都是 Markdown。主要区别在于作用范围：CLAUDE.md 是 Claude Code CLI 读取的，copilot-instructions.md 是 GitHub Copilot 读取的。如果你同时使用两个工具，需要分别维护。