一、Custom Instructions 的核心概念：什么是 instructions.md？

你是否有过这样的体验：昨天刚告诉 Copilot “我们项目用的是 Vue 3 Composition API”，今天它又给你写了一段 Vue 2 的 Options API 代码？或者在一个纯粹的 React 项目中，它突然引入了一个 Angular 的服务，因为它通过你的变量名“猜测”你可能需要这个？

这些问题的根源在于：AI 缺乏对项目全局的"持久化记忆"。它的上下文窗口是有限的，它无法时刻记住你两周前说过的那句"我们团队禁止使用 Lombok"。

Custom Instructions 就是 GitHub 给出的官方解法。你在项目根目录下的 .github 文件夹中创建 copilot-instructions.md 文件，Copilot 在进行每一次代码补全或 Chat 对话时，都会强制先阅读这份文档。这就好比给你的 AI 队友发了一份**“员工手册”**——在它开始干活之前，必须先熟读公司的技术栈、编码规范和业务黑话。

Custom instruction files 提供了一种方式，将团队的编码标准、架构决策和项目特定的指南直接嵌入到你的仓库中。当 Copilot Chat 处理一个请求时，它会读取这些文件，并将其内容整合到响应中，从而生成符合你项目惯例的建议，而不需要你在每一个 prompt 中重复相同的上下文。

二、同一套配置体系中的角色定位：agent.md vs. instructions.md

在第一节中，我们介绍了 Custom Agent——那是专业的"员工角色"，可以让你创建多个针对不同任务的 AI 助手（如 @test-agent、@security-agent）。那么 instructions.md 和它是什么关系？

简单来说，我们可以把 Copilot 的配置体系想象成一个"军队编制"：

层级 配置组件 用途比喻
全域规则 copilot-instructions.md 军队的"军事条例"——所有士兵（所有 Agent 和通用 Copilot）都必须遵守的基本准则
专业角色 *.agent.md “特种兵编制”——每个 Agent 是一个经过专门训练和定向的角色，执行特定任务
专业角色的专属规则 .github/instructions/*.instructions.md 特种兵的"作战手册"——给特定类型的士兵看的专门指南

copilot-instructions.md 是整个配置体系的顶层基础。Copilot 在每个交互中都会加载这个文件，使其成为 AI 行为的全局基线。每个 Agent、每个 prompt 和每个 instruction file 都建立在你在此处定义的内容之上。

当 Copilot 处理一个请求时，它会合并来自四个层级的指导：

  1. 用户设置（VS Code profile）
  2. 为当前任务调用的 prompt 或 agent
  3. 通过 applyTo 模式匹配的 instruction files
  4. copilot-instructions.md（始终加载）

你可以把 copilot-instructions.md 看作是整个配置体系的宪法，而 agent.md 和 *.instructions.md 是在这个宪法框架下设立的专业子规则。

三、两种类型的 Instructions

Instructions 提供两种主要的使用方式：

3.1 全局型（Repository-level instructions）

文件位置：.github/copilot-instructions.md（仓库根目录下的 .github 文件夹中）

作用范围：应用于仓库中所有文件的 AI 交互，对所有会话生效。如果你在 VS Code 中打开了多个项目，每个项目可以有自己的 copilot-instructions.md 文件，它们互不干扰。

这是一个简单的示例：

# General Instructions
* Use TypeScript for all new source files.
* Follow the existing module structure under `src/`.
* Prefer named exports over default exports.

一个更完善的示例添加了优先级规则、项目结构指导和操作约束：

# General Instructions

## Priority Rules
* Conventions and styling from the codebase take precedence for all changes.
* Breaking changes are acceptable.
* Tests are created or modified only when explicitly requested.

## Project Structure
This repository contains a Node.js API with the following layout:
* `src/routes/` for HTTP route handlers
* `src/services/` for business logic
* `src/models/` for data models and schemas

## Coding Conventions
* Use `async`/`await` instead of raw promises.
* Variable names use camelCase; constants use UPPER_SNAKE_CASE.
* All public functions include JSDoc comments.

💡 最佳实践：从小的规则集合开始。几条有针对性的规则比一份冗长的文档效果更好。根据在你代码库中观察到的 Copilot 行为，逐步增加指导内容。

3.2 路径特定型（Path-specific instructions）

文件位置：.github/instructions/*.instructions.md

作用范围：只应用于特定的文件或目录，通过 YAML frontmatter 中的 applyTo 字段使用 glob 模式指定匹配规则。

当项目不同的部分需要不同的指导时，可以使用这种方法。例如，一个名为 database.instructions.md 的文件，其 applyTo: "DataAccess/**/*.cs" 可以包含仅适用于 DataAccess 文件夹中 C# 文件的规则，如"数据访问类使用 Repository 模式"或"始终使用参数化查询以防止 SQL 注入"。当 Copilot 处理匹配指定模式的文件时，它会合并仓库级的指令和相关的路径特定指令，生成上下文适当的建议。

四、指令文件的 Frontmatter 字段详解

路径特定型的 instructions 文件使用 YAML frontmatter（用 --- 包裹的头部区域）来定义元数据。支持的字段如下：

4.1 applyTo（必需）

属性 说明
类型 string
用途 指定该指令文件应用于哪些文件，使用 glob 模式匹配
位置 frontmatter 中

applyTo 字段是路径特定型指令的核心，它决定了指令的作用范围。如果 applyTo 缺失，Copilot 将无法匹配任何文件，因此该字段是必需的。

glob 模式示例：

  • "**/*.py"——匹配所有 Python 文件
  • "DataAccess/**/*.cs"——匹配 DataAccess 文件夹及其子文件夹中的所有 C# 文件
  • "src/**/*.ts, src/**/*.tsx"——匹配 TypeScript 和 TSX 文件（多个模式用逗号分隔）

4.2 name（可选）

属性 说明
类型 string
用途 指令文件的显示名称，便于在界面中识别和引用

4.3 description（可选）

属性 说明
类型 string
用途 描述该指令文件的目的和适用范围

一个完整的路径特定型指令文件示例：

---
name: 'C# Backend Standards'
description: 'Coding conventions for C# backend files'
applyTo: 'src/Backend/**/*.cs'
---

# C# backend coding standards

- Use PascalCase for public members and camelCase for private fields.
- Prefix private fields with an underscore (e.g., _orderService).
- Include parameterized queries to prevent SQL injection.
- Use the repository pattern for data access classes.

4.4 嵌套组织与目录结构

为保持可维护性，instructions 文件可以按目录组织。建议的结构如下：

.github/instructions/
├── coding-standards/
│   ├── python-script.instructions.md
│   └── typescript.instructions.md
├── hve-core/
│   ├── markdown.instructions.md
│   └── writing-style.instructions.md
└── shared/
    └── cross-collection.instructions.md

4.5 引用其他指令文件

你可以在一个指令文件中使用 Markdown 的相对链接来引用其他指令文件。例如：

---
applyTo: "**/*.ts,**/*.tsx"
---

# Project coding standards for TypeScript and React

Apply the [general coding guidelines](./general-coding.instructions.md) to all code.

## TypeScript Guidelines
- Use TypeScript for all new code
- Use interfaces for data structures and type definitions
- Prefer immutable data (const, readonly)

## React Guidelines
- Use functional components with hooks
- Use React.FC type for components with children
- Keep components small and focused

📝 注意：当多个指令文件匹配同一个文件时，Copilot 会加载所有匹配的文件并合并其指导内容。

4.6 更高级的分层配置

除了 .github/copilot-instructions.md 和 .github/instructions/*.instructions.md，GitHub Copilot CLI 还支持在其他位置读取说明文件，所有支持的位置（按发现顺序）如下：

位置 作用范围
~/.copilot/copilot-instructions.md 所有会话（全局）
.github/copilot-instructions.md 仓库级
.github/instructions/**/*.instructions.md 仓库级（模块化）
AGENTS.md（在 Git 根或当前工作目录中） 仓库级
Copilot.md、GEMINI.md、CODEX.md 仓库级

⚠️ 优先级原则：仓库级说明始终优先于全局指令。使用这一点来强制实施团队约定。

这对于跨 IDE 协作特别有用：如果你有一个在 VS Code 和 Visual Studio 中同时使用的工作区，可以用同一个 .github/copilot-instructions.md 文件为两个编辑器定义自定义说明。

五、指令内容的编写指南

5.1 自然语言格式

instructions 文件使用自然的 Markdown 格式编写，每个指导可以是一个独立的 bullet point 或段落。指令之间的空格在发送给模型时会被忽略，因此你可以为了可读性自由地格式化文件，而不会影响 Copilot 的处理方式。

5.2 六大核心领域

一个完整的指令文件应该覆盖以下六个核心领域：

  1. 项目概述：这个项目是做什么的？
  2. 技术栈：用了哪些框架、库、工具链？
  3. 编码规范：命名约定、格式要求、最佳实践
  4. 架构：目录结构、分层设计
  5. 工作流：构建命令、测试命令、提交规范
  6. 边界：绝对不能做的事情

以下是一个完整的示例：

# 项目概述
这个仓库是社内向け的勤怠管理系统。

## 技术栈
- Backend: TypeScript + Serverless Express
- Frontend: TypeScript + Next.js
- DB: Aurora Serverless v2 (PostgreSQL 16)
- ORM: Prisma
- Node.js 版本: 22

## 编码规范
- 变量名・函数名使用 camelCase
- 组件使用 PascalCase 命名
- 缩进使用空格 2 个
- 不要省略分号
- 魔术数字定义为常量
- 注释使用中文

## 架构
后端采用分层架构:
- `router/` - 路由定义
- `handler/` - HTTP 请求接收和响应返回
- `service/` - 业务逻辑
- `database/` - 数据库访问和查询执行

## 禁止事项
- 避免使用 `any` 类型
- 不要使用全局变量
- 不要使用 `init()` 函数

5.3 指令文件的优先级

当 Copilot 处理一个请求时，它会按照以下优先级合并指导：

  1. 用户设置（VS Code profile）——优先级最高
  2. prompt 或 agent 中明确指定的指令（如 /test 命令）
  3. 通过 applyTo 匹配的 instruction files
  4. copilot-instructions.md——作为基线，始终被加载

💡 为什么这样设计？ 这种分层设计确保了你可以在最顶层覆盖 Agent 行为的同时，保持基线规则的稳定性。

5.4 AGENTS.md 作为补充

AGENTS.md 是一个与 copilot-instructions.md 类似但应用更广泛的概念。它被 60,000 多个开源项目使用，目的是为 AI Agent 提供通用的项目上下文指导。

概念 用途 适用对象
copilot-instructions.md 为 Copilot 在项目中提供通用指导 GitHub Copilot
AGENTS.md 为 AI Agent 在项目中提供通用指导 Copilot、Claude、Gemini、Cline 等多种 AI Agents

在实践中，为了最大限度的兼容性，你可以在项目根目录同时放置 copilot-instructions.md 和 AGENTS.md。AGENTS.md 通常更侧重项目高层级的概述和协作指南，适合在多种 AI Agents 和人类开发者之间共享。

六、动手实战：完整的 Instructions 配置示例

假设我们正在开发一个 企业级全栈 Web 应用，技术栈为 Next.js 15 + TypeScript + Tailwind CSS + PostgreSQL。以下是完整的 Instructions 配置。

Step 1: 创建基础配置文件

# 创建 .github 目录（如果不存在）
mkdir -p .github
# 创建 copilot-instructions.md
touch .github/copilot-instructions.md
# 创建 instructions 子目录（用于路径特定型规则）
mkdir -p .github/instructions

Step 2: 编写 .github/copilot-instructions.md

---
name: "Corporate HR System"
description: "企业级全栈 Web 应用开发规范"
---

# 项目概况
这是一个企业级的人力资源管理系统，管理员工信息、考勤、薪资和绩效。

## 技术栈 (Tech Stack)
- **全栈框架**: Next.js 15+ (App Router)
- **数据库 ORM**: Prisma
- **样式系统**: Tailwind CSS v4
- **语言**: TypeScript (严格模式)
- **包管理器**: pnpm

## 架构原则 (Architecture Principles)

### 目录结构

src/
├── app/ # Next.js App Router (页面和 API 路由)
├── components/ # React 组件 (可复用 UI)
│ ├── ui/ # 基础 UI 组件
│ └── features/ # 特性相关组件
├── lib/ # 工具函数和共享逻辑
├── server/ # 服务端专用代码
│ ├── db/ # Prisma 客户端和数据库操作
│ └── auth/ # 认证和授权逻辑
└── types/ # TypeScript 类型定义


### 编码规范 (Coding Standards)

#### TypeScript
- 使用 `interface` 定义对象类型，`type` 用于联合类型和工具类型
- 所有函数必须有明确的返回类型标注
- 避免使用 `any`；必要时使用 `unknown` 配合类型守卫

#### React / Next.js
- 组件使用函数声明 + 命名导出：`export function UserProfile() {}`
- Server Components 优先，仅在必要时使用 Client Components
- Server Actions 处理后端逻辑，减少传统 API 路由

#### 命名规范 (命名规则)
- 变量、函数：`camelCase`
- 组件、接口、类型别名：`PascalCase`
- 常量：`UPPER_SNAKE_CASE`
- 私有字段：`_camelCase`

### Git 工作流
- 分支命名：`feature/xxx`、`fix/xxx`、`docs/xxx`
- 提交信息遵循 Conventional Commits 格式（`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`）
- 必须通过 TypeScript 类型检查和 ESLint 后方可提交

## 约束与边界 (Constraints)
- 不要提交包含敏感信息的代码（API 密钥、密码、JWT secret）
- 不要手动修改 Prisma schema 生成的类型文件（`node_modules/.prisma`）
- 不要跳过 TypeScript 检查
- 不要在生产代码中使用 `console.log`（使用项目配置的 logger）

Step 3: 为特定目录创建专属规则

创建 .github/instructions/backend.instructions.md：

---
name: "Backend API Standards"
description: "服务端 API 和数据库层开发规范"
applyTo: "src/server/**/*.ts,src/app/api/**/*.ts"
---

# 后端 API 开发规范

## 数据库操作 (Prisma)
- 始终使用 `prisma.$transaction` 处理需要原子性的多步操作
- 避免在循环中执行数据库查询；使用 `prisma.$queryRaw` 批量处理
- 使用 Prisma 的 `select` 字段限制返回的数据量
- 敏感字段（如 `password_hash`、`refresh_token`）永远不要包含在查询结果中

## API 路由
- API 路由放在 `src/app/api/[resource]/route.ts`
- 使用 `NextRequest` 和 `NextResponse` 处理请求和响应
- 所有 API 响应格式统一：
  ```typescript
  interface APIResponse<T> {
    success: boolean;
    data?: T;
    error?: { code: string; message: string };
    timestamp: string;
  }

错误处理

  • 使用 try-catch 捕获异步操作错误
  • 自定义业务异常继承 Error 类
  • 开发环境返回详细错误堆栈，生产环境只返回通用错误消息

安全

  • 所有用户输入在使用前必须经过验证（使用 Zod schema）
  • SQL 查询必须使用参数化形式，禁止字符串拼接
  • API 接口需要进行认证和授权检查（JWT token 验证）

创建 `.github/instructions/frontend.instructions.md`：

```markdown
---
name: "Frontend UI Standards"
description: "前端 UI 组件和页面开发规范"
applyTo: "src/components/**/*.tsx,src/app/**/*.tsx"
---

# 前端 UI 开发规范

## 组件开发
- 优先使用 Server Components，仅在需要交互时使用 Client Components
- Client Components 必须在文件顶部添加 `'use client'` 指令
- 组件 props 使用 TypeScript 接口定义
- 保持组件单一职责，单个组件不超过 300 行

## 样式 (Tailwind CSS)
- 使用 Tailwind 工具类，避免自定义 CSS
- 可复用的样式组合使用 `@apply` 指令放在 `globals.css` 中
- 暗色模式使用 `dark:` 变体支持
- 响应式设计使用 `sm:`、`md:`、`lg:`、`xl:` 断点

## 状态管理
- 使用 React Context 管理全局 UI 状态（主题、语言等）
- 使用 Zustand 管理应用业务状态
- 表单状态使用 React Hook Form + Zod 验证

## 性能
- 图片使用 Next.js 的 `Image` 组件，配置 `priority` 用于 LCP 图片
- 使用 `React.memo` 优化频繁重渲染的大组件
- 路由使用 `dynamic import` 进行代码分割
- 避免在渲染函数中创建新对象/数组（使用 `useMemo`、`useCallback`）

七、总结

对比项 copilot-instructions.md *.instructions.md
位置 .github/（仓库根目录） .github/instructions/
作用范围 仓库内所有文件 通过 applyTo 指定模式的文件
命名 固定文件名 *.instructions.md（任意名称）
是否需要 frontmatter 否 是（必须有 applyTo）
典型用途 项目整体编码规范和架构原则 特定目录/文件类型的专门规则

下一节，我们将介绍 prompts.md（可重用的提示文件），它可以将日常频繁执行的 AI 任务（如代码审查、创建组件、生成测试用例）转换为可随时调用的标准化提示。届时你将全面掌握 Copilot 完整的三层配置体系。

八、参考资料

# AI作画 # AIGC
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

AtomCode 全新上线万亿代码模型 LongCat-2.0。限时 7 天免费体验！

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区