VS Code 指令文件：copilot-instructions.md 与 AGENTS.md
两者都是自动注入会话的 Markdown 指令文件，VS Code 均原生支持；差别在生态范围（Copilot 专属 vs 跨 Agent 通用）与加载开关 / 激活方式，而不是「一个能用、一个不能用」。
一、一句话对比
| 维度 | .github/copilot-instructions.md | AGENTS.md |
|---|---|---|
| 归属生态 | GitHub Copilot 专属 | 跨 Agent 开放格式（Copilot / Codex / Claude / Cursor 等） |
| 位置 | 仓库根 .github/ 目录下 | 仓库根（子目录嵌套为实验特性） |
| VS Code 支持 | 原生自动读取 | 原生自动读取，受 chat.useAgentsMdFile 开关控制 |
| 激活方式 | 工作区全局生效（隐式注入，无 frontmatter） | 同左 |
| 典型用途 | 约定 Copilot 在本仓库的回答风格与代码规范 | 多人 / 多工具协作，共享同一份项目说明书 |
关键：两者是叠加（additive）关系而非覆盖关系——同时存在时会一起注入，内容重复只会白占上下文，内容矛盾则行为不可预期。
二、VS Code 指令文件家族（先分清谁是谁）
| 文件 / 位置 | 作用域 | 激活方式 | 生态 |
|---|---|---|---|
.github/copilot-instructions.md | 工作区全局 | 自动附加，纯 Markdown | Copilot |
AGENTS.md（仓库根） | 工作区全局 | 自动附加，纯 Markdown | 跨 Agent |
.github/instructions/**/*.instructions.md | 按文件匹配 | YAML frontmatter：applyTo / description | Copilot |
CLAUDE.md | 工作区全局 | 自动附加 | Claude |
~/.copilot/copilot-instructions.md | 用户级（跨项目） | 自动附加 | Copilot |
| GitHub 组织级指令 | 组织级 | 组织设置中开启 | Copilot |
- 只有
*.instructions.md需要 YAML frontmatter（可带name/description/applyTo）；copilot-instructions.md与AGENTS.md都是纯 Markdown，没有强制字段。 - 常见误区：认为「
AGENTS.md不被 VS Code 识别，必须靠copilot-instructions.md桥接」——该说法已过时。现版本两者都是官方支持的指令格式，桥接的价值退化为「单一事实来源」，而不是「能不能读到」。
三、格式要求
3.1 通用规范（两者一致）
- 标准 Markdown，无强制 frontmatter；
- 指令短、单句、可执行，一条只讲一件事；
- 优先用
-无序列表 + 加粗关键词，便于注意力定位； - 条件判断写成
当…时，执行…； - 禁止项要显式写「禁止」「必须」并加粗（LLM 对否定句注意力较弱）；
- 需要 AI「参考而非照抄」的输出格式示例，用代码块隔离；
- 控制长度（200 行内）：文件内容计入上下文窗口，过长会导致后段规则被忽略（会话越长越明显）。
3.2 copilot-instructions.md：精炼指令式
它会被静默注入到 system prompt，写法应像命令而不是文档，典型四段：
- 角色与回复风格——语言、语气、禁止的客套话；
- 规则路由——
当…时 → 去读哪份规则； - 分支判别——按输入类型走不同模板；
- 硬性红线速记——只列禁止项，不展开。
3.3 AGENTS.md：结构完备的说明书
给 Agent 与协作者共读，建议四模块：
| 模块 | 内容 |
|---|---|
| Project Overview | 仓库做什么、技术栈与版本、常用命令表 |
| Context Map | 目录树 + 各目录职责 + 关键文件标注 |
| Workflow & Protocols | 各类任务的执行流程与约定（命名、模板、收尾清单） |
| Constraints & Guardrails | 绝对禁止的事项，用 ✅ / ❌ 列表 |
四、协同方案：单一事实来源 + 入口引用
AGENTS.md ← 规则正本（唯一需要维护的地方）
▲
│ 引用
.github/copilot-instructions.md ← 只写「角色 / 风格 / 路由」+ 指向 AGENTS.md
- 全部核心规则写在根目录
AGENTS.md； copilot-instructions.md只保留角色、风格、路由，加一句「严格遵循AGENTS.md」；- 收益：规则只维护一份；入口文件保持短小，不挤占上下文。
注意：桥接的目的是单一事实来源，不是因为 VS Code 读不到
AGENTS.md。
五、易错点
| 现象 | 原因 / 处理 |
|---|---|
| 规则完全不生效 | 先确认当前会话选的 agent / harness；AGENTS.md 受 chat.useAgentsMdFile 控制 |
| 规则记不住、越聊越跑偏 | 指令文件过长或过于发散，改写为单句指令并精简 |
| 两条规则互相冲突 | 各来源是叠加的，没有可靠的优先级，必须在源头删重、消解矛盾 |
子目录 AGENTS.md 无反应 | 嵌套 AGENTS.md 属实验特性，默认关闭（chat.useNestedAgentsMdFiles） |
| 编辑器内联补全不带规则 | 自定义指令不作用于内联建议，只作用于 Chat / Agent 会话 |
| 想确认加载了哪份 | 命令面板 Chat: Open Customizations；加载日志用 Developer: Open Agent Debug Logs |
六、写作技巧速记
- 写为什么：如「用 pnpm，因为仓库已锁定 pnpm-lock.yaml」，AI 在边界情况更会自行判断；
- 给正例 / 反例代码片段，比抽象描述有效；
- 跳过 linter / formatter 已能强制的规则；
- 任务或语言专属的规则拆成多个
*.instructions.md，用applyTo（如**/*.py、**/*.md）精准挂载； - 团队 / 组织级要求保持一致，不要在多个文件里写互相矛盾的副本。
相关
- 技术笔记总览：本站其他技术笔记入口