使用 GitHub Copilot：自定义指令与代理

Source: Dev.to

我最近探索了 Custom Instructions（自定义指令）和 Custom Agents（自定义代理）在 GitHub Copilot 中的使用。虽然这些功能乍看之下很简单，但它们从根本上改变了 Copilot 在真实代码库中的行为——尤其是在有意使用时。

本指南基于我当前的理解和实践经验，全部基于 GitHub Copilot Chat 在 Visual Studio Code 中的使用（除非另有明确说明）。

术语说明

自定义指令 vs. 自定义代理（思维模型）

• 自定义指令 提供 持久的项目上下文。
• 自定义代理 为特定聊天交互提供 专门的行为。

把指令想象成项目的 规则手册，而自定义代理则是你有意调用的 专门审阅者。

Source: …

自定义指令

1. 仓库范围指令

在以下位置创建文件：

.github/copilot-instructions.md

此文件：

• 适用于整个仓库。
• 充当 Copilot 的 持久项目上下文。
• 充当 共享规则手册（而非强制执行机制）。
• VS Code 可以通过分析代码库自动生成此文件。将其视为 起点，而非权威规范——仍需人工审查。

2. 路径特定指令

你可以使用 apply‑to glob 创建 作用域指令文件，例如：

.github/instructions/**/*.instructions.md

这些指令 仅在匹配路径的文件出现在上下文中时加载，因此前端规则不会泄漏到后端代码，反之亦然。

示例

• .github/instructions/csharp-coding-standards.instructions.md → C# 后端文件
• .github/instructions/typescript-coding-standards.instructions.md → TypeScript 前端文件

所有指令——无论是仓库范围的还是路径特定的——都是 指导性建议，而非硬性约束。

示例： “在 TypeScript 中绝不要使用 any。”
Copilot 通常会避免使用 any，但在类型不明确或为了简洁时仍可能插入。仍需人工审查或自定义代理来强制执行。

指令文件中应包含的内容

仅包含 Copilot 无法从代码中推断的信息：

• 技术栈选择 – 例如，“我们使用 Tailwind CSS 进行样式设计，使用 Vitest 进行测试。”
• 命名约定 – 例如，“接口名称始终以 I 为前缀（如 IUser）。”
• 严格限制 – 例如，“在 TypeScript 中绝不要使用 any。”
• 项目上下文 – 例如，“这是一个遗留的单体项目；优先兼容性而非新特性。”
• 避免重复 已经由编译器、linter 或 CI 强制的规则。

Awesome Copilot 仓库

Awesome Copilot 仓库 包含大量社区贡献的提示、指令文件、代理和模板。

• 提示示例： suggest-awesome-github-7_prompt.md – 将其粘贴到 VS Code Copilot Chat 中，可获取与仓库相关的 AI 推荐项目。
• 代理提示示例： github-prompts/suggest-awesome-github-copilot-agents.prompt.md – 建议哪些代理配置可能有用。

个人与组织指令

GitHub Copilot 还支持：

• 个人指令
• 组织指令

这些指令现在可以 通过 Settings Sync 与 VS Code 同步，因此在 GitHub.com 上定义的规则也会在 IDE 中生效。

指令优先级

当存在多个来源时，Copilot 会合并它们，并大致遵循以下优先级（列表越靠前优先级越高）：

1. 个人/用户指令
2. 仓库指令（.github/copilot-instructions.md）
3. 组织指令

冲突的解决是概率性的——行为并非严格确定。

指令文件策略（避免指令膨胀）

与其使用一个庞大的文件，不如按 领域和技术 拆分指令：

.github/
│
├─ copilot-instructions.md          # 全局、不可协商的规则
└─ instructions/
   ├─ frontend.instructions.md
   ├─ backend.instructions.md
   ├─ security-iam.instructions.md
   └─ dotnet-framework-legacy.instructions.md

全局手册（.github/copilot-instructions.md）

仅包含不可协商的内容：

• 架构： 优先组合而非继承。对公共 API 采用零信任原则。
• 安全： 绝不记录 PII、原始令牌或机密信息。
• 性能： 优先 O(n) 或更好；显式标记异步 I/O。
• 文档： 仅为公共契约和复杂逻辑编写文档。

保持此文件 小且稳定。

作用域指令示例

• 前端： 框架约定、响应式模式、类型规则。
• 后端： 命名、错误处理、格式化。
• IAM： 身份验证/授权规则。
• 遗留框架： 在约束范围内安全现代化。

自定义代理

自定义代理将 Copilot 从：

“编写代码的 AI” → “应用特定工程视角的 AI”

定义位置

• 工作区级别: .github/agents（针对特定仓库）
• 用户配置文件级别: 在工作区之间共享

自定义代理 并不比 VS Code 代理模式更强大——它们 更专注且更具主观性。

自定义代理的实际使用

(内容在原指南中继续——保持相同的章节和示例。)

Agents

轻量级团队模式

• VS Code Agent 模式 → 仅实现
• 自定义代理 → 必须的审阅者（由团队约定，而非 Copilot 强制）

将自定义代理的输出视为 PR 审查反馈，而非建议。

示例工作流

推荐： 已在仓库范围和特定路径上配置指令，以提升结果质量。

1. 在 VS Code Copilot 中使用 @plan 模式来概述功能或更改。
2. 使用 VS Code Agent 模式 实现该功能/特性。
3. 运行 @dotnet-security-reviewer → 标记缺少授权策略。
4. 修复该问题。
5. 运行 @typescript-api-contract-reviewer → 标记可空性不匹配。
6. 修复该问题。

为什么不把所有这些都内置到 VS Code 代理模式中？

• 目标冲突（速度 vs. 谨慎）
• 随着约束增多，规则被稀释
• 上下文很重要——大多数检查并不总是相关
• 当人类被减速时，会绕过摩擦
• 大语言模型倾向于取平均；它们不进行裁决
• 完成偏差胜过预防

沉默的违规比明确的审查更糟。

VS Code 代理模式构建。自定义代理进行判断。
这种分离是帮助型 AI 与值得信赖的 AI 之间的区别。

最后说明

• 个人和组织指令现在对大多数用户 与 VS Code 同步。
• 自定义代理可以与工具关联，前提是 Copilot 功能可用且工作区拥有相应权限。

GitHub Copilot Chat 是开源的：

• VS Code Copilot Chat

内置代理（如 Plan 模式）可在此查看：

• Plan‑agent.md

资源

• 在 VS Code 中创建自定义代理
• Awesome Copilot