自定义指令¶

本文你会学到：

• 🤔 自定义指令解决什么问题（为什么要用它）
• 📋 四种指令类型各自的适用场景
• ✍️ 如何编写高质量的指令内容
• 🎯 路径特定指令的匹配规则

打个比方：自定义指令就像给新入职的同事写一份入职手册——告诉他项目用什么技术栈、编码有什么规范、测试怎么跑。有了这份手册，他不用每次都来问你同样的问题。

🤔 为什么要用自定义指令？¶

没有自定义指令时，Copilot 只能根据你的 prompt 和当前文件来工作。这意味着： - 它不知道你的项目用什么编码规范（camelCase 还是 snake_case？） - 它不知道测试该用什么框架（JUnit 5 还是 TestNG？） - 它不知道提交信息该用什么格式

每次都要在 prompt 中重复这些信息，既低效又不稳定。自定义指令让这些信息始终生效，Copilot 每次响应时都会参考。

📋 指令类型总览¶

📁 仓库级指令¶

适用于在仓库上下文中发起的所有请求，是最常用的指令类型。

位置：仓库根目录下 .github/copilot-instructions.md

在 Monorepo 项目中，自定义指令、MCP 服务器、Skills 和 Agents 会在从工作目录到 git 根目录的每个层级被发现（1.0.11 新增），子目录的指令会叠加到父目录指令之上。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 项目约定

## 技术栈
- Python 3.12 + FastAPI
- PostgreSQL + SQLAlchemy
- pytest 用于测试

## 编码规范
- 使用 type hints
- 函数文档使用 Google 风格的 docstring
- 变量命名使用 snake_case

## 项目结构
- `src/api/` - API 路由层
- `src/services/` - 业务逻辑层
- `src/models/` - 数据模型层
- `tests/` - 测试，镜像 src 结构

🎯 路径特定指令¶

有时候不同目录的代码需要不同的规范——比如 tests/ 目录下的代码和 src/ 目录的代码风格可能不同。路径特定指令就是为此设计的：当 prompt 涉及与指定路径匹配的文件时，对应的指令会自动加载。

位置：.github/instructions/ 目录下，文件名必须以 .instructions.md 结尾。

applyTo 匹配规则¶

文件开头使用 YAML frontmatter 的 applyTo 关键字指定作用范围：

1
2
3
4
5
6
7
8
9

---
applyTo: "**/*.ts,**/*.tsx"
---
# TypeScript 编码规范

- 优先使用 interface 而非 type alias
- 使用 ESLint + Prettier 格式化
- 组件 props 使用独立的 interface 定义
- 避免使用 any，必要时使用 unknown

applyTo 支持 glob 模式，多个模式用逗号分隔。同时接受字符串和数组两种写法（1.0.6 新增）：

1
2
3
4
5
6
7

# 字符串写法
applyTo: "**/*.ts,**/*.tsx"

# 数组写法
applyTo:
  - "**/*.ts"
  - "**/*.tsx"

excludeAgent 排除规则¶

可选的 excludeAgent 字段排除特定 Agent 使用这些指令：

1
2
3
4
5
6
7
8
9

---
applyTo: "tests/**/*.py"
excludeAgent: "code-review"
---
# 测试编写规范

- 使用 pytest 框架
- 每个测试函数以 test_ 开头
- 使用 @pytest.fixture 管理测试数据

🤖 Agent 指令（AGENTS.md）¶

AGENTS.md 是一种跨平台标准，被 Copilot CLI、Claude Code、Gemini 等多种 AI Agent 共同支持。可以把它理解为"AI Agent 通用语言"——写一份，所有 AI 工具都能读懂。

查找位置（按优先级）¶

1. 仓库根目录 AGENTS.md
2. 当前工作目录 AGENTS.md
3. COPILOT_CUSTOM_INSTRUCTIONS_DIRS 环境变量指定目录中的 AGENTS.md

分层放置¶

大型项目可以在子目录中放置 AGENTS.md，当 Copilot 操作对应目录的文件时，会自动加载该目录的指令：

1
2
3
4
5
6

project-root/
├── AGENTS.md                # 全局规范
├── frontend/
│   └── AGENTS.md            # 前端特有规范
└── backend/
    └── AGENTS.md            # 后端特有规范

🏠 本地指令¶

本地指令适合存放个人偏好和本地环境特有信息——比如你习惯用中文回答、本地数据库的端口是 19002 而非默认的 3306。这些信息不适合提交到 Git（每个人的环境不同），所以放在本地配置中。

位置：$HOME/.copilot/copilot-instructions.md

1
2
3
4
5
6

# 个人偏好

- 使用简体中文回答
- 代码注释使用中文
- 优先使用函数式编程风格
- 日志使用 loguru 而非 logging

⚙️ 配置文件补充¶

除了指令文件，Copilot CLI 还会读取 .claude/settings.json 和 .claude/settings.local.json 作为额外的仓库配置源（1.0.12 新增），可以在其中定义 Hook、权限规则等。settings.local.json 用于本地覆盖，不应提交到 Git。

配置键名在 1.0.15 版本统一为 camelCase 格式（如 askUser、autoUpdate、skillDirectories、disabledSkills），snake_case 格式仍向后兼容。

customize 模式（1.0.7 新增）支持分区级 System Prompt 覆盖，让管理员在不修改全局 system message 的前提下，为特定分区自定义 system prompt 行为。

🔍 扩展指令搜索路径¶

设置 COPILOT_CUSTOM_INSTRUCTIONS_DIRS 环境变量可以让 Copilot 在额外的目录中查找指令文件：

1

export COPILOT_CUSTOM_INSTRUCTIONS_DIRS="/path/to/team-instructions,/path/to/org-instructions"

1

$env:COPILOT_CUSTOM_INSTRUCTIONS_DIRS = "C:\team-instructions;C:\org-instructions"

Copilot CLI 会在这些目录中查找 AGENTS.md 和 .github/instructions/**/*.instructions.md 文件。

✨ /init 命令¶

/init 命令让 Copilot 自动分析当前项目并生成指令文件：

用法¶

1
2

# 在项目根目录运行
/init

也可以通过编程式调用：

1
2

# 非交互模式调用
copilot -p "/init"

生成内容¶

Copilot 会扫描项目结构、依赖文件、已有配置等，然后提议创建或更新：

• .github/copilot-instructions.md
• AGENTS.md
• 其他建议的指令文件

生成的内容通常涵盖以下几个方面：

生成后调整¶

/init 生成的初始内容是一个**起点**，建议根据实际情况手动编辑：

• 补充项目特有的业务规则和约定
• 添加团队统一的编码规范细节
• 修正 Copilot 误判的技术栈信息
• 增加敏感信息的安全提醒（如"不要将 API Key 写入代码"）

📝 指令编写最佳实践¶

内容建议¶

• 简洁具体：明确说明规则和偏好，避免模糊描述。"使用 camelCase 命名" 比 "命名要规范" 有效得多
• 结构化：使用标题和列表组织内容，方便 Copilot 解析
• 包含示例：展示正确和错误的做法
• 列出命令：包含构建、测试、部署等常用命令——Copilot 可以直接调用它们

常见误区¶