企业官网建设流程全解析

VS Code Copilot Agent Instructions 完整指南：用 AGENTS.md 与 copilot-instructions.md 为整个工作区自动注入 AI 编码规范

【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode

Agent Instructions（代理指令）是 VS Code Copilot 提供的一种"全局常驻"定制能力：只要文件位于约定位置，其中的规则就会自动应用到当前工作区内发起的每一次 Chat 请求，无需在对话中手动附加或输入/命令。本文以 agent-instructions.md 为核心骨架，结合本仓库（VS Code 源码库）中 Copilot Chat 的指令收集、文件发现与解析实现，系统讲解两种指令文件格式的取舍、推荐模板、编写原则、反模式，以及底层是如何把.github/copilot-instructions.md、AGENTS.md等文件扫描并注入到模型上下文的。读完本文，你将能在自己的团队仓库中建立一套可被 VS Code Copilot、GitHub Copilot CLI 以及 Claude Code 等 Agent 生态共同识别的工程规范，并理解配置开关与排障路径。

什么是 Agent Instructions

Agent Instructions 是 VS Code Copilot 文档所称 "custom instructions（自定义指令）"在 agent 上下文中的落地形态。它满足一个核心特征：

Guidelines that automatically apply to all chat requests across your entire workspace. （这些准则会自动应用于跨整个工作区的所有聊天请求。）

与仅在匹配文件类型时生效的 File Instructions（*.instructions.md，靠applyTo的 glob 模式按需触发）不同，Agent Instructions没有条件触发逻辑：只要文件位于被识别的位置，每次 Chat/Agent 请求构建上下文时都会被读取并注入。它们是"Always-on、处处生效"的项目级行为底座，适合表达"无论改哪个文件都应该遵守"的规则。

这一"常驻注入"的定位，在仓库内 agent-customization 技能 的决策表中被描述为：

因此选择指令载体前，请先回答一个问题：这条规则是否适用于绝大多数任务？若是，放进 Agent Instructions；若只服务于特定场景，则应考虑 Skill、Prompt 或 File Instructions。

两种文件格式：只能二选一

官方推荐的工作区级指令文件有两种，它们在目标、位置与生态兼容性上有明确分工。原文档给出如下对照表：

关键约束：只能二选一，不要两个文件同时存在（"Useonly one—not both."）。原因在"反模式"一节会展开。

copilot-instructions.md：面向 Copilot 的工程规范

copilot-instructions.md约定存放在仓库的.github/目录下（如.github/copilot-instructions.md）。它由 Copilot 生态提出，同时在 VS Code 与 GitHub Copilot CLI 中生效，是本仓库文档推荐的"项目级标准"载体。

从实现侧可以确凿地看到 VS Code 对它的发现逻辑。文件名与目录常量定义在 promptFileLocations.ts：

GITHUB_CONFIG_FOLDER = '.github' COPILOT_CONFIG_FOLDER = '.copilot' COPILOT_CUSTOM_INSTRUCTIONS_FILENAME = 'copilot-instructions.md' AGENT_MD_FILENAME = 'AGENTS.md'

在 promptsServiceImpl.ts 的listAgentInstructions()中，文件发现顺序是：

1. 在当前工作区根目录以及"父仓库根"（配置chat.useCustomizationsInParentRepositories后向上寻找含.git的目录）下的.github/子目录中查找copilot-instructions.md；
2. 在用户主目录~/.copilot/下查找用户级copilot-instructions.md（随用户全局生效）；
3. 是否启用该格式由配置项github.copilot.chat.codeGeneration.useInstructionFiles控制。

也就是说，copilot-instructions.md既可以是仓库级的（.github/copilot-instructions.md），也可以是用户级的（~/.copilot/copilot-instructions.md）。

AGENTS.md：面向整个 Agent 生态的开放标准

AGENTS.md是近年来被 VS Code、Claude Code 等工具共同采纳的开放约定，支持放在仓库根目录，也支持放进子文件夹实现 monorepo 分层。相比copilot-instructions.md，它不绑定单一厂商，更容易让不同的编码代理共享同一套规范。

• 根目录AGENTS.md：作用于整个仓库（含 workspace 根目录）；
• 子文件夹嵌套AGENTS.md：作用于对应子树，适用于 monorepo 中不同包/模块有各自约定时；
• 嵌套扫描默认行为与开关chat.useNestedAgentsMdFiles相关。启用后，promptFilesLocator.ts 会用文件搜索服务以**/AGENTS.md模式递归查找工作区里所有的嵌套AGENTS.md；在没有文件搜索提供者的场景下，则退化为基于文件服务的递归目录遍历（文件名大小写不敏感匹配agents.md）；
• 根目录AGENTS.md的读取由chat.useAgentsMdFile控制。

值得一提的是，本仓库（VS Code 自身）正是一个真实样例：仓库根目录的 AGENTS.md 只有短短几行"入口"，其内容指向了更详细的 .github/copilot-instructions.md——这份文件承载了项目分层架构、TypeScript 命名规范、代码风格、测试与校验命令等全部细节。这正是下文"Link, don't embed（链接而非内嵌）"原则的落地方式。请读者注意：原文档建议不要让两份文件重复承载同样的内容；若采用"根AGENTS.md做入口 + 单一详情文件"的组合，应保证信息单点存放，避免copilot-instructions.md与AGENTS.md各自维护一份互相漂移的规范。

推荐模板：只放工作区真正受益的章节

原文档强调："Only include sections the workspace benefits from"——模板里的章节是候选而非必填。官方推荐骨架如下：

# Project Guidelines ## Code Style {Language and formatting preferences—reference key files that exemplify patterns} ## Architecture {Major components, service boundaries, the "why" behind structural decisions} ## Build and Test {Commands to install, build, test—agents will attempt to run these} ## Conventions {Patterns that differ from common practices—include specific examples}

各章节写作要点：

• Code Style（代码风格）：描述语言与格式化偏好，并引用体现这些模式的代表性文件，而不是抽象说教。例如本仓库在.github/copilot-instructions.md中写明了"用 Tab 而非空格""类型名用 PascalCase""方法名用 camelCase""用户可见字符串需用vs/nls本地化"等具体约定。
• Architecture（架构）：说明主要组件、服务边界以及结构决策背后的"为什么"。对本仓库而言，就是src/vs/base（基础工具）、src/vs/platform（平台服务与 DI 基础设施）、src/vs/editor（编辑器内核）、src/vs/workbench（工作台）的分层关系，以及依赖注入、贡献点（Contribution）模型等原则。
• Build and Test（构建与测试）：给出安装、构建、测试所需的命令——Agent 会真的尝试执行这些命令。仓库示例包括npm run typecheck-client、scripts/test.sh --grep <selector>、npm run gulp compile-extensions等，并注明各命令的适用范围与成本（全量类型检查/构建较慢，应优先使用最小的针对性测试）。
• Conventions（约定）：专门记录那些与常见做法不同的约定，并给出具体示例，防止 Agent 按通用惯例写出不合规的代码。

对于大型仓库，应链接到详细文档而非把全部内容内嵌进去。原文档给出的写法是：

Seedocs/TESTING.mdfor test conventions.

何时使用 Agent Instructions

原文档明确划定了适用范围：

• 适用于任何地方的通用编码标准（general coding standards that apply everywhere）；
• 通过版本控制共享的团队偏好（team preferences shared through version control）；
• 项目级要求，如测试、文档等规范（project-wide requirements）。

需要反向判断的是：如果规则只对某类文件、某个子目录或某个特定任务有意义，就不应放进"全局常驻"的 Agent Instructions，否则会持续占用上下文窗口并干扰无关请求——这时应改用带applyTo的 File Instructions，或按需调用的 Prompts / Skills。

四条核心原则

1. Minimal by default（默认最小化）：只放与每一个任务都相关的内容。任何"只对特定模块重要"的条目都不属于这里。
2. Concise and actionable（简洁可执行）：每一行都应能指导行为。空话、套话、模糊的形容词不会改变 Agent 的输出。
3. Link, don't embed（链接，而非内嵌）：优先引用已有文档而不是复制粘贴。建议先搜索仓库里已有的文档（如docs/**/*.md、CONTRIBUTING.md等）并盘点它们各自覆盖了什么；只有那些别处没有记录的、对 Agent 至关重要的坑才值得直接内联。本仓库根目录AGENTS.md只放一句指引并链接到.github/copilot-instructions.md，就是最典型的内嵌与链接权衡。
4. Keep current（保持更新）：当团队的实践发生变化时，同步更新指令文件。过期指令与缺失指令同样有害——Agent 会把它当作最新的权威依据。

四大反模式

原文档列举了最容易踩的四个坑：

• 两个文件同时使用（Using both file types）：既放copilot-instructions.md又放AGENTS.md。两份内容极易漂移，且会让同一请求注入冗余上下文。务必只保留其一。
• 厨房水槽式堆砌（Kitchen sink）：把"所有可能相关的条目"都塞进去，而不是只写最重要的。指令越长，Agent 越难分辨真正的硬性约束。
• 复制文档（Duplicating docs）：把 README 原文拷贝进指令文件，而不使用链接。一旦源文档更新，指令文件就悄悄过时。
• 显而易见的内容（Obvious instructions）：记录那些已被 linter/formatter 强制实施的规则，既浪费 token，又可能在工具链与实际规则冲突时造成误导。

源码视角：指令如何被自动发现与注入

要真正用好 Agent Instructions，需要理解它背后"常驻生效"的机制。结合仓库源码，可梳理出三条实现线索。

1. 位置发现：约定优先于配置

所有候选文件名与目录都是硬编码约定（见 promptFileLocations.ts），运行时通过文件服务在 promptsServiceImpl.ts 中统一收集：

• 每个 workspace 根目录 + 父仓库根（若启用）下的.github/copilot-instructions.md；
• 用户主目录~/.copilot/下的copilot-instructions.md；
• 每个 workspace/父仓库根目录下的AGENTS.md；
• 启用嵌套后，工作区内任意子目录的AGENTS.md。

同一份AgentInstructionFileType枚举（agentsMd、copilotInstructionsMd、claudeMd等）也揭示了这类文件与CLAUDE.md是同一套"自动指令"家族的成员。

2. 常驻更新：文件系统监听自动刷新

指令文件发生增删改后，无需重启窗口即可生效。promptFilesLocator.ts 的createAgentInstructionsUpdatedEvent()会根据配置动态注册文件监听：监听范围由chat.useAgentsMdFile、chat.useClaudeMdFile、github.copilot.chat.codeGeneration.useInstructionFiles以及是否允许父仓库定制共同决定。一旦相关配置变更、workspace 目录增减、信任目录变化或文件系统事件触发，都会重建监听并广播更新事件。

3. 注入链路：进入每次 Chat 请求构建流程

在请求构建侧，computeAutomaticInstructions.ts 的collect()把指令收集分为几个阶段：先按applyTo匹配追加文件级指令（applying instructions），再补充被引用指令（referenced instructions），最后调用_addAgentInstructions()加入本文讨论的 agent 指令（copilot-instructions.md与AGENTS.md）。对应遥测字段agentInstructionsCount专门统计这两类文件注入的数量，可见它们在工程上被归为同一类"自动指令"。

4. 可配置开关速查

仓库内 config.ts 集中定义了全部相关开关，可按需在 VS Code 设置中开关：

这些开关同时决定了文件发现（是否把对应位置列入搜索根）与文件监听（是否注册 watcher）。若指令不生效，可优先检查：文件是否在约定位置、对应开关是否被关闭、子目录嵌套是否未开启、工作区是否处于信任状态。

一份可直接落地的完整示例

综合模板与原则，一个最小但完整的.github/copilot-instructions.md示例（单目录、非 monorepo 场景）：

# Project Guidelines ## Code Style - 使用 2 空格缩进；类型名与枚举值使用 PascalCase，函数/方法/属性与局部变量使用 camelCase。 - 不要导出未跨组件共享的 type 与函数；禁止向全局命名空间引入新类型或值。 - 函数、接口、枚举与类的注释使用 JSDoc 风格。参考 `src/core/format.ts` 的写法。 ## Architecture - 分层：base → platform → editor → workbench，低层不得依赖高层。 - 通过构造函数参数注入依赖；业务组件不得绕行服务定位器。 - 见 `docs/architecture.md` 中的目录职责说明。 ## Build and Test - 安装依赖：`npm install` - 单元测试：`npm test -- --grep <目标用例>` - 本地快速编译：`npm run transpile` - 变更涉及模块分层时运行：`npm run valid-layers-check` ## Conventions - 所有文件必须保留版权头。 - 优先 `async/await`，避免 `Promise.then` 链。 - 资源清理必须即时登记到 DisposableStore，禁止延迟到类销毁时统一处理。 - 此约定与团队默认习惯不同，务必遵守：模块间只允许方法调用与服务交互，不得用事件驱动控制流。

备注：copilot-instructions.md/AGENTS.md为纯 Markdown，无需YAML frontmatter。带---元数据块的是另一类原语（Skill、Prompt、Custom Agent、File Instructions），写作时不要混淆。

创建与验收流程

参照 agent-customization 技能（SKILL.md）的工作流，落地一份 Agent Instructions 只需四步：

1. 确定作用域（Scope）：项目级、团队共享 → 放入.github/（或根目录AGENTS.md）；个人跨工作区使用 → 放入用户级 prompts 目录（*.instructions.md/*.agent.md等，随设置同步漫游）。
2. 选择原语（Primitive）：绝大多数任务都适用 → Agent Instructions；特定任务 → Skill/Prompt；特定文件类型 → File Instructions。不要越级。
3. 创建文件：按上文位置表放到.github/copilot-instructions.md或根目录AGENTS.md，正文遵循模板组织。
4. 校验（Validate）：确认位置正确、只存在一份文件、正文只含"人人受益"的条目、代码/命令示例真实可运行。之后在任意一次 Chat 请求中观察指令是否随系统提示注入，必要时检查配置开关与文件监听是否生效。

与其他原语的边界速查

从 agent-customization 技能中的决策表与边界问题可以进一步廓清 Agent Instructions 的适用范围：

• Instructions vs Skill：适用于"大多数工作"→ Instructions；只针对"特定任务"→ Skill。
• Hooks vs Instructions：Instructions 是引导Agent 行为（非确定性的软约束）；Hooks 是在PreToolUse/PostToolUse等生命周期节点用 shell 命令强制行为（可拦截操作、要求审批、确定性格式化），参见 hooks.md。
• 与 File Instructions 的区别：File Instructions 通过applyTo文件模式精确圈定生效文件，而 Agent Instructions 无差别常驻于每次请求；后者的"最小化"要求远比前者严格。

总体而言，Agent Instructions 是 Copilot Chat 定制体系里"成本最低、覆盖最广"的一档——正因为处处生效，写作时必须对每一行都保持克制，做到"只放每个人都需要的东西"。一份干净、单一、指向明确、随实践持续更新的指令文件，配合本仓库源码展示的自动发现与监听机制，就能让团队规范真正沉淀到 AI 编码工作流的每一次交互中。

【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode