github-copilot-repo-instructions

github-copilot-repo-instructions

仓库范围的 Copilot 指南。GitHub Copilot 在处理针对仓库的每个请求时，都会读取 .github/ 中的 Markdown 文件。

此技能仅用于编写和审核仓库范围的指令文件。不涵盖个人（针对每位用户）的 Copilot 指令；这类指令适用于单个用户在 github.com 上的 Chat 会话，且位于仓库之外。有关 AGENTS.md 的内容和结构（不包括下表中的文件布局），请使用 agents-md 技能。

---

文件布局

文件	适用范围	Frontmatter	备注
.github/copilot-instructions.md	整个仓库，每个请求	无	单个文件。保持在 2 页以内。
.github/instructions/<name>.instructions.md	路径 glob	必需（applyTo）	可有多个文件。文件名必须以 .instructions.md 结尾。
AGENTS.md	就近优先	无	可放在目录树中的任何位置；离已编辑路径最近的文件优先。
CLAUDE.md	仅仓库根目录	无	根目录中只能有一个文件。
GEMINI.md	仅仓库根目录	无	根目录中只能有一个文件。

当路径匹配时，仓库范围文件和路径专用文件会合并——两组指令都会一并发送给 Copilot。

---

Frontmatter（仅限路径专用文件）

---
applyTo: "**/*.ts, **/*.tsx"
excludeAgent: "code-review"
---

- Prefer `interface` over `type` for object shapes.
- Use named exports.

字段	必需	取值
applyTo	是	Glob 模式或以逗号分隔的多个 glob（*.py、src/**/*.rb、**/subdir/**/*.py）。
excludeAgent	否	"code-review" 或 "cloud-agent"——使此文件不在对应界面中显示。

---

使用场景

Copilot 会在以下场景中读取仓库指令：

• Copilot Chat——github.com/copilot（关联仓库时）和 IDE 聊天。
• Copilot 代码审查——PR 审查。可按仓库切换。读取 PR 的源分支（包含更改的分支），而非目标分支。
• Copilot 编码 Agent（云 Agent）——由 issue 驱动的实现。

github.com 完全支持代码审查和云 Agent 使用路径专用文件（.github/instructions/*.instructions.md）。IDE 对路径专用文件的支持较滞后；若要确保 IDE 能读取，使用仓库范围文件更稳妥。请参阅 references/code-review-knobs.md，了解 2025-09-03 的更改；该更改为 Copilot 代码审查专门增加了路径范围指令支持。

---

优先级

存在多组指令时，所有指令都会合并并发送给 Copilot。声明的优先级顺序（从高到低）：

1. 个人指令（针对每位用户，仅适用于 github.com Chat）。
2. 仓库指令（本技能）。
3. 组织指令。

冲突不会自动解决——Copilot 会看到全部指令。如果质量下降，与其纠缠于指令重叠，不如暂时禁用其中一组。

---

操作流程

添加仓库范围指令

1. mkdir -p .github
2. 编写 .github/copilot-instructions.md。仅使用 Markdown，不加 frontmatter。
3. 保持在 2 页以内。空白字符不计入，因此可多用项目符号。
4. 能发挥作用的内容：技术栈摘要、构建/测试命令、目录结构说明、非显而易见的约定。跳过 Copilot 已经了解的通用建议。
5. 在功能分支上提交并创建 PR。代码审查会读取 PR 的源分支，因此该 PR 的审查会使用新指令。

添加路径专用指令

1. mkdir -p .github/instructions
2. 创建带有 applyTo frontmatter 的 <name>.instructions.md。
3. 每个适用范围创建一个文件（例如 python.instructions.md、frontend.instructions.md）。
4. 使用 excludeAgent，避免仅供审查或仅供编码 Agent 使用的指南泄漏到其他场景。

启用 Copilot 代码审查

仓库 Settings → Code & automation → Copilot → Code review → 切换 “Use custom instructions when reviewing pull requests”。

默认已启用，但请确认——组织有时会将其关闭。

在每个 PR 上启用自动 Copilot 审查

有两种方式，任选其一。两种方式都会创建分支规则集；API 方式可通过脚本执行。

UI — Settings → Rules → Rulesets → New branch ruleset。 在“Branch rules”下，选择 Automatically request Copilot code review。 有两个子选项：Review new pushes（每次推送后重新审查，会消耗高级请求额度）和 Review draft pull requests。

API（gh）— 规则类型为 copilot_code_review。截至撰写本文时，规则集架构页面 尚未列出此类型，但该端点接受它。目标分支的设置方式与其他规则集相同。

gh api repos/<owner>/<repo>/rulesets -X POST --input - <<'JSON'
{
  "name": "copilot-auto-review",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~ALL"], "exclude": [] } },
  "rules": [
    {
      "type": "copilot_code_review",
      "parameters": {
        "review_on_push": false,
        "review_draft_pull_requests": false
      }
    }
  ]
}
JSON

~ALL 会匹配发往每个分支的 PR。使用 ~DEFAULT_BRANCH 仅涵盖目标分支为默认分支的 PR。

所示默认设置较为保守：PR 打开时审查一次，跳过草稿。 将 review_on_push 改为 true，即可在每次推送后重新审查——这对 Agent 工作流很有用，但会消耗大量高级请求额度。

组织需要订阅 Copilot Business/Enterprise，个人仓库则需要 Copilot Pro。即使没有许可证，仍会安装规则集；只是不会触发审查。

如需查看仓库级、组织级和单个 PR 级别的完整设置项——包括 Copilot 审查无法执行的操作（没有“请求更改”模式、没有严重程度阈值、无法通过 API 重新请求审查）、已取消的 4000 字符指令限制，以及按路径指定指令的支持情况——请阅读 references/code-review-knobs.md。

通过 gh api 对规则集端点进行的任何实时更改都会修改仓库设置。发送请求前，请展示渲染后的负载并获得用户明确授权。

验证 Copilot 是否读取了文件

1. 打开 github.com/copilot 并附加仓库。
2. 提出任意 Copilot Chat 问题。
3. 展开响应顶部的 References 列表。
4. 应显示 .github/copilot-instructions.md；点击以确认它是预期版本。提及或附加相关路径时，会显示特定路径的文件。

如需验证 PR 审查，请查看审查评论的元数据，或在涉及与特定路径文件中某个 glob 匹配的文件的 PR 上触发审查。

---

审计清单

当用户说“审计我们的 Copilot 配置”时：

1. 执行 ls -la .github/copilot-instructions.md .github/instructions/ AGENTS.md CLAUDE.md GEMINI.md 2>/dev/null（不显示缺失文件）。
2. 阅读每个存在的文件并检查：
   • 仓库级文件不超过 2 页。
   • 每个特定路径文件都有 applyTo frontmatter。
   • 文件名以 .instructions.md 结尾（仅限特定路径文件）。
   • excludeAgent 值必须恰好为 "code-review" 或 "cloud-agent"。
   • 仓库级文件中没有应限定到特定路径的指令（例如“始终添加类型提示”——这只适用于 Python，应将其移出并限定到对应路径）。
3. 检查当前指令所在的分支。代码审查会读取 PR 的头部分支，因此 PR 会看到自身的指令更改。来自其他分支的 PR，只有在更改合并到基础分支，且这些分支从该分支合并或变基后，才能看到这些更改。
4. 标记与组织级或预期个人指令之间的冲突。

---

规则

• 仓库级文件：不得有 frontmatter。 GitHub 没有说明 .github/copilot-instructions.md 支持 frontmatter。不要在其中添加 applyTo。
• 特定路径文件：必须有 frontmatter。 没有 applyTo 时，该文件会被忽略。
• 两种文件都不要包含特定任务的指令（例如“修复错误 X”“执行重构 Y”）——它们是长期配置，不是工单范围。
• 不要重复组织指令。 如果组织已经要求“使用 Conventional Commits”，不要在仓库级重复添加。
• 代码审查会读取头部分支。 PR 中的指令更改会应用于该 PR 自身的审查，因此你可以在合并前测试。
• 不要包含机密、令牌或内部 URL。 这些文件属于仓库的一部分，任何拥有读取权限的人都能看到。

---

注意事项

• 路径专属文件若 YAML 前置元数据格式错误，会被静默忽略。 提交前请验证前置元数据。
• 如果 glob 的匹配结果不符合预期，请添加 **/ 前缀以涵盖嵌套路径 （**/*.py 可匹配嵌套文件；*.py 可能只匹配根目录，具体取决于 glob 引擎）。
• IDE 可能会缓存指令；编辑后请重新加载窗口。
• AGENTS.md 会递归应用——更深层目录中的 AGENTS.md 会覆盖较高层的文件，对其附近的文件生效。这很有用，但如果用户以为指令会合并，就容易造成困惑。
• Copilot 现在也会读取 CLAUDE.md 和 GEMINI.md，尽管它们最初是为其他厂商的产品编写的。如果你同时维护这两个文件，Copilot 会看到全部三个文件。
• 对于 github.com Chat 上的某个用户，个人指令优先于仓库指南——如果出现“Copilot 不遵循我们对 Alice 的规则，但对其他人正常”的情况，症结可能就在这里。个人指令按用户配置，设置在仓库之外；此技能不会管理这些指令。
• 对仓库级文件唯一有明确记录的大小建议是“不超过 2 页”。请将其视为上限——过长的指令会挤占实际问题的空间。

---

此技能不负责什么

• 不是设置向导——它会提供建议并编辑现有文件，而不是通过访谈生成文件。
• 不是个人指令——个人指令按用户配置，设置在仓库之外，不属于此技能的范围。
• 不是组织级指令——这类指令在 GitHub Enterprise 组织设置中配置，不属于任何仓库。
• 不是编写 AGENTS.md 内容——请使用 agents-md 技能；此技能只会在文件布局表中说明 AGENTS.md 的位置。

---

来源

• 为 GitHub Copilot 添加仓库自定义指令