一、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 处理一个请求时它会合并来自四个层级的指导用户设置VS Code profile为当前任务调用的 prompt 或 agent通过applyTo模式匹配的 instruction filescopilot-instructions.md始终加载你可以把copilot-instructions.md看作是整个配置体系的宪法而agent.md和*.instructions.md是在这个宪法框架下设立的专业子规则。三、两种类型的 InstructionsInstructions 提供两种主要的使用方式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.md4.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.mdGitHub 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 六大核心领域一个完整的指令文件应该覆盖以下六个核心领域项目概述这个项目是做什么的技术栈用了哪些框架、库、工具链编码规范命名约定、格式要求、最佳实践架构目录结构、分层设计工作流构建命令、测试命令、提交规范边界绝对不能做的事情以下是一个完整的示例# 项目概述 这个仓库是社内向け的勤怠管理系统。 ## 技术栈 - 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 处理一个请求时它会按照以下优先级合并指导用户设置VS Code profile——优先级最高prompt 或 agent 中明确指定的指令如/test命令通过applyTo匹配的 instruction filescopilot-instructions.md——作为基线始终被加载 为什么这样设计这种分层设计确保了你可以在最顶层覆盖 Agent 行为的同时保持基线规则的稳定性。5.4 AGENTS.md 作为补充AGENTS.md是一个与copilot-instructions.md类似但应用更广泛的概念。它被60,000 多个开源项目使用目的是为 AI Agent 提供通用的项目上下文指导。概念用途适用对象copilot-instructions.md为 Copilot 在项目中提供通用指导GitHub CopilotAGENTS.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.mdtouch.github/copilot-instructions.md# 创建 instructions 子目录用于路径特定型规则mkdir-p.github/instructionsStep 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使用项目配置的 loggerStep 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 APIResponseT { success: boolean; data?: T; error?: { code: string; message: string }; timestamp: string; }错误处理使用try-catch捕获异步操作错误自定义业务异常继承Error类开发环境返回详细错误堆栈生产环境只返回通用错误消息安全所有用户输入在使用前必须经过验证使用 Zod schemaSQL 查询必须使用参数化形式禁止字符串拼接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 完整的三层配置体系。八、参考资料GitHub Docs: Best practices for GitHub Copilot CLIGitHub Docs: Your first custom instructionsGitHub Docs: Adding repository custom instructions for GitHub Copilot in your IDEGitHub Docs: Adding custom instructions for GitHub Copilot CLIGitHub Blog: 5 tips for writing better custom instructions for CopilotGitHub Blog: Want better AI outputs? Try context engineeringGitHub Repository: Awesome GitHub Copilot Customizations – instructions examplesGitHub Repository: agentsmd/agents.md – AGENTS.md specificationGitHub Discussion: Difference between custom agents, agent skills, and custom instructionsVS Code Docs: Use an AGENTS.md file in VS Code
第二节：让 AI 记住你的项目——instructions.md 文件详解
一、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 处理一个请求时它会合并来自四个层级的指导用户设置VS Code profile为当前任务调用的 prompt 或 agent通过applyTo模式匹配的 instruction filescopilot-instructions.md始终加载你可以把copilot-instructions.md看作是整个配置体系的宪法而agent.md和*.instructions.md是在这个宪法框架下设立的专业子规则。三、两种类型的 InstructionsInstructions 提供两种主要的使用方式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.md4.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.mdGitHub 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 六大核心领域一个完整的指令文件应该覆盖以下六个核心领域项目概述这个项目是做什么的技术栈用了哪些框架、库、工具链编码规范命名约定、格式要求、最佳实践架构目录结构、分层设计工作流构建命令、测试命令、提交规范边界绝对不能做的事情以下是一个完整的示例# 项目概述 这个仓库是社内向け的勤怠管理系统。 ## 技术栈 - 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 处理一个请求时它会按照以下优先级合并指导用户设置VS Code profile——优先级最高prompt 或 agent 中明确指定的指令如/test命令通过applyTo匹配的 instruction filescopilot-instructions.md——作为基线始终被加载 为什么这样设计这种分层设计确保了你可以在最顶层覆盖 Agent 行为的同时保持基线规则的稳定性。5.4 AGENTS.md 作为补充AGENTS.md是一个与copilot-instructions.md类似但应用更广泛的概念。它被60,000 多个开源项目使用目的是为 AI Agent 提供通用的项目上下文指导。概念用途适用对象copilot-instructions.md为 Copilot 在项目中提供通用指导GitHub CopilotAGENTS.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.mdtouch.github/copilot-instructions.md# 创建 instructions 子目录用于路径特定型规则mkdir-p.github/instructionsStep 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使用项目配置的 loggerStep 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 APIResponseT { success: boolean; data?: T; error?: { code: string; message: string }; timestamp: string; }错误处理使用try-catch捕获异步操作错误自定义业务异常继承Error类开发环境返回详细错误堆栈生产环境只返回通用错误消息安全所有用户输入在使用前必须经过验证使用 Zod schemaSQL 查询必须使用参数化形式禁止字符串拼接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 完整的三层配置体系。八、参考资料GitHub Docs: Best practices for GitHub Copilot CLIGitHub Docs: Your first custom instructionsGitHub Docs: Adding repository custom instructions for GitHub Copilot in your IDEGitHub Docs: Adding custom instructions for GitHub Copilot CLIGitHub Blog: 5 tips for writing better custom instructions for CopilotGitHub Blog: Want better AI outputs? Try context engineeringGitHub Repository: Awesome GitHub Copilot Customizations – instructions examplesGitHub Repository: agentsmd/agents.md – AGENTS.md specificationGitHub Discussion: Difference between custom agents, agent skills, and custom instructionsVS Code Docs: Use an AGENTS.md file in VS Code
