github-copilot-repo-instructions

github-copilot-repo-instructions

仓库范围的 Copilot 指南。GitHub Copilot 每次处理此仓库的请求时都会读取 .github/ 中的 Markdown 文件。

通用且忠实于文档。若要使用融入特定工程原则、带有主观倾向的生成器，请参阅 /copilot 的 setup 模式 — /copilot setup （如果已安装）。

若要使用多模式 Copilot 驱动程序（review / delegate / setup），请参阅 /copilot （如果已安装）— 此技能仅编写和审核指令文件。

---

文件布局

文件	范围	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 审查。可按仓库启用或禁用。读取的是 基础分支，而不是功能分支。
• Copilot 编码 Agent（云端 Agent） — 由 issue 驱动的实现。

路径特定文件（.github/instructions/*.instructions.md）在 github.com 上可供代码审查和云端 Agent 完全使用。IDE 对路径特定文件的支持有所滞后 — 对 IDE 覆盖范围而言，仓库范围文件是更稳妥的选择。

---

优先级

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

1. 个人指令（按用户设置，仅限 github.com Chat）。
2. 仓库指令（本技能）。
3. 组织指令。

冲突不会自动解决 — Copilot 会看到所有指令。如果质量下降， 请暂时禁用其中一组，而不是试图消除重叠。

---

流程

添加仓库范围指令

1. mkdir -p .github
2. 编写 .github/copilot-instructions.md。仅使用 Markdown，不要添加 frontmatter。
3. 保持在 2 页以内。空白会被忽略，因此请灵活使用项目符号。
4. 有实际帮助的内容：技术栈摘要、构建/测试命令、布局图、 不明显的约定。跳过 Copilot 已掌握的通用建议。
5. 提交到基础分支（通常为 main）— 代码审查会读取基础分支的内容。

添加路径特定指令

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

启用 Copilot 代码审查

仓库设置 → 代码与自动化 → Copilot → 代码审查 → 切换 “审查拉取请求时使用自定义指令”。

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

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

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

UI — 设置 → 规则 → 规则集 → 新建分支规则集。 在“分支规则”下，选择 自动请求 Copilot 代码审查。 有两个子选项：审查新的推送（每次推送都重新审查，会消耗高级请求） 和 审查草稿拉取请求。

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": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    {
      "type": "copilot_code_review",
      "parameters": {
        "review_on_push": false,
        "review_draft_pull_requests": false
      }
    }
  ]
}
JSON

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

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

如需查看仓库 / 组织 / 每个 PR 的完整配置项清单——包括 Copilot 审查无法 执行的操作（没有“请求更改”模式、没有严重性阈值、无法通过 API 重新请求）——请阅读 references/code-review-knobs.md。

验证 Copilot 是否读取了该文件

1. 打开 github.com/copilot 并附加仓库。
2. 提出任意 Copilot Chat 问题。
3. 展开回复顶部的 引用列表。
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. 在 git log 中检查基础分支——功能分支上近期对指令的修改，在合并前不会被代码审查读取。
4. 标记与组织级指令或预期的个人指令之间的冲突。

---

规则

• 全仓库文件：不使用 frontmatter。 GitHub 未说明 .github/copilot-instructions.md 支持 frontmatter。不要在其中添加 applyTo。
• 特定路径文件：必须使用 frontmatter。 没有 applyTo 时，该文件会被忽略。
• 不要在任一文件中放入特定任务指令（“修复错误 X”、“重构 Y”）——它们是长期配置，不是工单范围。
• 不要重复组织指令。 如果组织已经规定“使用 Conventional Commits”，就不要在仓库级别重复。
• 代码审查读取基础分支。 仅在 PR 中修改指令，不会影响该 PR 自身的审查。
• 不要包含机密、令牌或内部 URL。 这些文件属于仓库的一部分——任何有读取权限的人都能看到它们。

---

注意事项

• 带有格式错误的 YAML 前置内容的路径专属文件会被静默忽略。 提交前请验证前置内容。
• 如果 glob 的匹配结果不符合预期，请添加 **/ 前缀以覆盖嵌套路径（**/*.py 会匹配嵌套文件；根据 glob 引擎的不同，*.py 可能只匹配根目录）。
• IDE 可能会缓存指令；编辑后请重新加载窗口。
• AGENTS.md 会递归生效——深层嵌套的 AGENTS.md 会覆盖附近文件适用的上级文件。虽然实用，但如果用户预期指令会合并，就容易造成困惑。
• Copilot 现在也会读取 CLAUDE.md 和 GEMINI.md，尽管它们最初是其他厂商的文件。如果同时维护这两个文件，请预期 Copilot 会读取这三个文件。
• 在 github.com Chat 中，对某个用户而言，个人指令的优先级高于仓库指南——表现为“Copilot 忽略了 Alice 的规则，但对其他人有效”。请检查 /github-copilot-personal-instructions。
• 关于仓库级文件，唯一有文档记录的长度建议是“≤ 2 页”。请将其视为上限——过长的指令会挤占实际问题的空间。

---

此技能不是什么

• 不是设置向导——它会提供建议并进行编辑，不会进行访谈。
• 不同于 /copilot setup（如果已安装）——该模式会让 /copilot 驱动程序采用特定风格。
• 不是个人指令——请参阅 /github-copilot-personal-instructions。
• 不是组织级指令——这些指令在 GitHub Enterprise 组织设置中配置，不属于任何仓库。

---

来源

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