【Copilot配置】—— copilot-instructions.md vs AGENTS.md vs .instructions.md三种指令文件解析与配置

优质文章学习记录

— 8 min read
【Copilot配置】—— copilot-instructions.md vs AGENTS.md vs .instructions.md三种指令文件解析与配置

Copilot 指令文件全解析：copilot-instructions.md vs AGENTS.md vs .instructions.md

作为常年和 VS Code 打交道的研发，最近在折腾 Copilot Agent 时，我发现很多同学和我一样，被 .github/copilot-instructions.md、AGENTS.md 和 .instructions.md 这三个文件绕晕了。

明明都是给 Copilot 写的 “指令”，为什么要分三个文件？它们的生效范围有啥区别？什么时候该用哪一个？

带着这些疑问，我翻遍了官方文档，又在自己的 AI Agent 项目里反复实测，终于把这三者的关系理得清清楚楚。这篇文章就用最直白的语言，结合实战配置，帮你彻底搞懂 Copilot 指令文件的使用逻辑。

一、先搞懂核心：三者的定位差异

在讲细节前，我们先用一个通俗的类比定调，这能帮你快速建立认知：

  • .github/copilot-instructions.md：项目的 “全局家规”，管整个仓库的所有 Copilot 基础交互；
  • AGENTS.md：Copilot Agent 的 “任务清单”，只服务于 Agent 进阶自动化功能；
  • .instructions.md：目录的 “局部特例”，管特定文件夹的 Copilot 基础交互，优先级最高。

简单来说：前两者是 “全局 vs 专属功能” 的区别，后两者是 “全局 vs 局部” 的区别，而 AGENTS.md 则是完全独立的 “进阶功能配置”。

二、三者核心辨析（一张表搞定）

为了方便大家查阅，我把三者的关键差异整理成了表格，这也是我做技术笔记时最常用的形式，一目了然：

表格

特性.github/copilot-instructions.mdAGENTS.md.instructions.md
核心定位项目级全局通用指令文件Copilot Agent 专属任务配置文件目录 / 文件级细粒度指令文件
生效范围整个代码仓库（所有文件、目录）仅 Copilot Agent 功能（手动触发时生效）仅当前文件所在目录及子目录
作用对象Copilot 基础能力（补全、注释、代码解释）仅 Copilot Agent 进阶功能（自动化任务）Copilot 基础能力（同左，仅局部生效）
触发方式被动生效（Copilot 自动读取）主动触发（VS Code 中手动点击「Run Agent」）被动生效（Copilot 自动读取）
存放路径强制：仓库根目录 /.github/（大小写敏感）无强制（建议放 .github/ 或项目根目录）无强制（放在需要生效的目标目录下）
内容风格项目规则、技术栈、业务背景描述具体任务步骤、执行目标、输出要求局部特殊规范、目录专属业务逻辑
优先级高于 Copilot 全局默认，低于 .instructions.md独立优先级（不与其他两者冲突）最高（覆盖全局规则）
典型场景定义全仓库编码规范、技术栈要求代码重构、批量文档生成、漏洞扫描特定模块的特殊命名规则、依赖限制

三、实战配置：手把手教你用对文件

光看理论不够，结合我自己的 AI Agent 项目（基于 Python 开发），给大家写了三个可直接复制的配置示例，对应不同的使用场景。

场景 1：项目全局规范 → 用 copilot-instructions.md

我的项目是一个 AI Agent 工具开发仓库，技术栈为 Python 3.11+、FastAPI，需要全仓库统一编码规范。

存放路径：项目根目录/.github/copilot-instructions.md

配置内容：

markdown

# Copilot 项目全局指令 ## 1. 技术栈与编码规范 - 编程语言：Python 3.11+，严格遵循 PEP 8 规范 - 命名规则：函数用小驼峰，类用大驼峰，常量全大写加下划线，Agent 相关类名必须以「Agent」结尾 - 注释要求：核心函数必须写中文文档字符串（docstring），包含入参、出参、功能描述 ## 2. 业务背景说明 本项目是一款轻量级 AI Agent 调度工具，核心模块包括：任务解析、技能调度、结果返回。 - 任务解析模块：负责解析用户输入的自然语言任务 - 技能调度模块：调用 OpenCode、Smithery 等第三方技能 - 结果返回模块：将 Agent 执行结果格式化为 Markdown 输出 ## 3. 依赖限制 - 优先使用项目虚拟环境中的依赖，禁止随意引入未在 requirements.txt 中声明的库 - 网络请求统一使用项目封装的 `src/utils/request.py` 中的 Axios 实例

配置完成后，不管我在 src/ 还是 tests/ 目录写代码，Copilot 都会自动遵循这些规则，比如定义 Agent 类时，会自动补全「Agent」后缀。

场景 2：Agent 自动化任务 → 用 AGENTS.md

我需要让 Copilot Agent 自动完成「项目代码质量检查」的任务，包括类型注解检查、异常处理检测，并生成报告。

存放路径：项目根目录/.github/AGENTS.md（建议和全局指令放一起，方便管理）

配置内容：

markdown

# Copilot Agent 任务指令集 ## 任务1：代码质量检查（核心任务） 1. 执行范围：遍历项目 `src/` 目录下所有 `.py` 文件 2. 检查项： - 所有函数和类方法是否包含完整的类型注解（入参、出参） - 是否存在未处理的异常（无 try-except 包裹的危险操作） - 导入语句是否存在未使用的情况 3. 输出要求： - 以 Markdown 格式生成检查报告，分为「问题清单」和「修复建议」两部分 - 对每个问题，附上具体文件路径、行号和对应的修复代码片段 ## 任务2：API 文档生成 1. 执行范围：`src/api/` 目录下的所有 FastAPI 路由文件 2. 执行要求：提取所有接口的路径、请求方式、入参、出参 3. 输出要求：生成 `API文档.md`，保存到项目根目录

使用方式：在 VS Code 中打开 Copilot 面板，点击「Run Agent」，选择对应的任务，Copilot 就会按照配置自动执行。

场景 3：局部目录特殊规则 → 用 .instructions.md

我的项目 src/admin/ 目录是后台管理模块，需要和核心模块区分开，组件命名必须以「Admin」为前缀，且禁止使用 FastAPI 的自动文档功能。

存放路径：项目根目录/src/admin/.instructions.md

配置内容：

markdown

# 后台管理模块专属指令 1. 命名规则：所有类、函数、组件命名必须以「Admin」为前缀（如 AdminUserService、admin_get_user_list） 2. 功能限制：禁止使用 FastAPI 的 `docs_url` 和 `redoc_url` 配置，后台接口无需生成自动文档 3. 业务要求：所有后台接口必须包含权限校验逻辑，需调用 `src/utils/auth.py` 中的 `check_admin_permission` 函数

此时，即使全局指令要求遵循 FastAPI 文档规范，Copilot 在 src/admin/ 目录下写代码时，也会优先遵循这个局部规则。

四、优先级与协同使用技巧

在实际开发中，这三个文件往往会同时存在，掌握它们的协同逻辑，能让 Copilot 更贴合你的项目需求：

  1. 基础能力优先级：.instructions.md（局部） > .github/copilot-instructions.md（全局） > Copilot 官方默认配置；
  2. 功能隔离原则：AGENTS.md 只作用于 Agent 功能，和另外两个文件没有优先级冲突，即使你配置了全局指令，Agent 也只会按 AGENTS.md 的要求执行任务；
  3. 实战建议：
    • 小型项目：只需要配置 .github/copilot-instructions.md，足够覆盖大部分场景；
    • 中大型项目：全局指令 + 局部指令结合，复杂自动化任务用 AGENTS.md；
    • 多人协作：把三个文件都纳入 Git 版本管理，确保团队所有人的 Copilot 行为一致。

五、常见问题排查

最后，整理几个我实测时遇到的坑，帮你避坑：

  1. copilot-instructions.md 不生效：检查路径是否为 .github/ 目录（不是 .vscode/），文件名是否严格匹配（大小写敏感）；
  2. Agent 不执行指定任务：确认 AGENTS.md 中任务描述是否清晰，是否手动触发了「Run Agent」功能（不是普通的代码补全）；
  3. .instructions.md 覆盖范围异常：该文件会作用于当前目录及所有子目录，若想仅作用于单个文件，可将文件放在单独目录，或在指令中明确指定文件名。

总结

其实 Copilot 的这三个指令文件，核心逻辑就是 “粒度分层” 和 “功能隔离”：

  • 按粒度分：全局（copilot-instructions.md）和局部（.instructions.md）；
  • 按功能分：基础补全（前两者）和进阶自动化（AGENTS.md）。

搞懂这个逻辑，再结合项目实际需求配置，就能让 Copilot 从 “通用助手” 变成 “专属项目管家”，不管是日常编码补全，还是复杂的 Agent 自动化任务，都能精准贴合你的开发习惯。

后续我会继续分享 Copilot Agent 结合 AI Agent 技术的实战案例，比如用 Agent 自动生成技术博客初稿，感兴趣的同学可以持续关注～

Read more

前端CI/CD流程：自动化部署的正确打开方式

前端CI/CD流程：自动化部署的正确打开方式 毒舌时刻 CI/CD？听起来就像是前端工程师为了显得自己很专业而特意搞的一套复杂流程。你以为配置了CI/CD就能解决所有部署问题？别做梦了！到时候你会发现，CI/CD配置出错的概率比手动部署还高。 你以为随便找个CI/CD工具就能用？别天真了！不同的工具配置方式不同，坑也不同。比如Jenkins的配置文件就像是天书，GitLab CI的YAML语法也能让你崩溃。 为什么你需要这个 1. 自动化部署：CI/CD可以自动完成代码测试、构建和部署，减少手动操作，提高部署效率。 2. 减少人为错误：自动化部署可以避免手动部署时的人为错误，提高部署的可靠性。 3. 快速反馈：CI/CD可以在代码提交后立即进行测试和构建，及时发现问题，提供快速反馈。 4. 持续集成：CI/CD可以确保代码的持续集成，避免代码冲突和集成问题。 5. 环境一致性：CI/CD可以确保不同环境的配置一致，避免环境差异导致的问题。 反面教材
他到底喜欢我吗？赛博塔罗Java+前端实现，一键解答！

他到底喜欢我吗？赛博塔罗Java+前端实现，一键解答！

个人主页-爱因斯晨 文章专栏-赛博算命 原来我们在已往的赛博算命系列文章中的源码已经传到我的Github仓库中，有兴趣的家人们可以自己运行查看。 Github 源码中的一些不足，还恳请业界大佬们批评指正！ 本文章的源码已经打包至资源绑定，仓库中也同步更新。 一、引言 在数字化浪潮席卷全球的当下，传统塔罗牌占卜这一古老智慧也迎来了新的表达形式 ——“赛博塔罗”。本文档旨在深入剖析塔罗牌的核心原理，并详细介绍如何利用 Java 语言实现一个简易的塔罗牌预测程序，展现传统神秘学与现代编程技术的融合。 二、塔罗牌原理 （一）集体潜意识与原型理论 瑞士心理学家卡尔・荣格提出的 “集体潜意识” 理论，为塔罗牌的运作提供了重要的心理学支撑。该理论认为，人类拥有超越个体经验的共同心理结构，其中蕴含着 “原型”—— 即普遍存在的、象征性的模式或形象。 塔罗牌的 22 张大阿尔卡那牌恰好与这些基本原型相对应。例如，“愚人” 代表着天真与新开始的原型，“魔术师” 象征着创造力与潜能的原型，“女祭司” 则体现了智慧与直觉的原型。这些原型是全人类共通的心理元素，这也正是不同文化背景的人都能

Web 可访问性最佳实践：构建人人可用的前端界面

Web 可访问性最佳实践：构建人人可用的前端界面 代码如诗，包容如画。让我们用可访问性的理念，构建出人人都能使用的前端界面。 什么是 Web 可访问性？ Web 可访问性（Web Accessibility）是指网站、工具和技术能够被所有人使用，包括那些有 disabilities 的人。这意味着无论用户的能力如何，他们都应该能够感知、理解、导航和与 Web 内容交互。 为什么 Web 可访问性很重要？ 1. 法律要求：许多国家和地区都有法律法规要求网站必须具有可访问性。 2. 扩大用户群体：约 15% 的世界人口生活有某种形式的 disability，可访问性可以让更多人使用你的网站。 3. SEO 优化：搜索引擎爬虫依赖于可访问性良好的网站结构。 4. 更好的用户体验：可访问性改进通常会使所有用户受益，而不仅仅是那些有 disabilities 的用户。 5. 社会责任：
AI 的提示词专栏：LLM（大语言模型）到底是怎么工作的？

AI 的提示词专栏：LLM（大语言模型）到底是怎么工作的？

AI 的提示词专栏：LLM（大语言模型）到底是怎么工作的？ 本文以通俗语言拆解大语言模型（LLM）工作机制，先阐明其核心是基于概率预测下一个 token，依赖 Transformer 架构的注意力机制理解上下文，通过海量数据训练形成隐性语言知识图谱。接着解析其 “输入处理 — 编码 — 特征提取 — 解码 — 输出” 五大技术模块，详解 “预训练 — 微调 — 对齐” 三阶段训练流程，以 “写智能台灯产品需求文档” 为例拆解完整推理链路。还指出 LLM 存在事实性错误、逻辑推理薄弱等能力边界，对比其与人类智能在学习方式、推理逻辑等方面的本质区别，最后说明理解 LLM 工作原理对优化 Prompt、预判输出、高效用模的价值，助力读者理性认识和使用 LLM。 人工智能专栏介绍     人工智能学习合集专栏是 AI 学习者的实用工具。它像一个全面的 AI 知识库，