GitHub Copilot 指令系统完全指南

我开始完整翻译这篇文章。

我已经开始在工作中分享这些内容，所以你在这里看到的是更轻松、便于公众理解且稍微过滤后的版本。我想保持透明！

大家好！感谢你的关注。如果你在美国，祝你有一个愉快的假期周！如果你在美国以外，享受这一周，用你自己的风格庆祝一些有趣的事情！🥳🎇

这是我迄今为止学到的关于 GitHub Copilot 自定义指令（Custom Instructions）的全面汇总——无论是在个人层级、存储库内部，还是整个组织范围内。

如果你曾经希望 Copilot 能"就这个方面变得更好"，Instructions 就是你教它你的那个方式的方法。

这是你告诉 Copilot 在给定的用户、存储库或组织上下文（或这些的组合）需要什么行为的机会。你完全可以自由决定要有多严格或多宽松。

🧭 这些建议适用的范围

本指南假设你使用 VS Code Insiders，其中指令功能最为先进。如果你还没有使用它……好吧，我稍后会尝试说服你 😄

无论使用哪种 IDE，你都应该始终利用存储库级别的指令，这些指令可在任何启用 Copilot 的地方工作——包括 GitHub.com。

📈 我在某个地方看到过一篇帖子说 GitHub 最近开始在 VS Code 之外支持用户级别的指令。不过你得自己去查一下——我从来没试过！100% 正确——GitHub.com 和几乎所有 IDE 目前都支持自定义指令。

✨ Copilot 指令的三层

按优先级顺序（最高优先级获胜，某种程度上——这变得有点复杂）：

• 用户特定指令 ——你个人想从 Copilot 得到的
• 存储库级别指令 ——针对特定代码库的共享期望
• 组织级别指令 ——跨整个组织的全球标准

⚠️ 这些的行为不符合你的预期，而且由于 Copilot 在设计上是非确定性的，它本身也不应该这样做。

📚 这里涉及很多理论（还有很多其他东西），但我会省去具体的细节（除非你问我——那样的话，就开始吧！）

考虑到有百万其他东西以同样的方式处理这种完全相同的优先级驱动标准，如果存在用户指令，那么它们总是优先于任何其他定义的东西，这是有道理的。同样，存储库特定的指令会覆盖组织级别的指令。

剧透：那不是真正发生的事！

最近，GitHub 某种程度上"偷偷"引入了这条新的优先级规则，我碰巧意外地发现了。说实话，这听起来就像他们在尝试，但从个人角度来说？我根本不信任它！

🦄 你有机会自己测试过这个吗？在下面的评论中让我们知道它如何工作！

……回到你原来的编程

真正发生的是，Copilot 拥有的任何上下文都是公平的游戏，包括来自任何来源的自定义指令。没有内置的

instruction.user = fileA;
instruction.repo = fileB;

fileA && fileB;

🐰 有一些高级的事情你可以做来帮助路由这些，使它们仅在相应的 glob 在上下文中时才应用，但那超出了本文的范围。过度简化的术语是 yaml frontmatter，应该足以让你自己找到这个兔子洞 😉

实际上，如果存储库指令告诉 Copilot"用 Python 输出所有示例"，而同一个 Chat 会话包含用户指令要求"仅用 Javascript 输出"，那么 Copilot 就会感到困惑。有时，它可以很好地使用其上下文来选择合适的一个，但它也很可能忽略两者并选择自己的路径（再次强调，这是设计使然）。

最终，确保 Copilot 仅接收它能自信地和重复地作用的指令是你的责任。如果那在任何时刻改变了，那么也更新指令。

👤 用户指令：为你量身定制

既然我们都在同一页面上了解 GitHub Copilot 的指令如何工作，让我们谈论最常见的类型。

个人或用户级别的指令是一个相对较新的概念，在几个月前，在 VS Code 之外访问这些几乎是不可能的。

这是你定义仅适用于你的偏好的地方。例如：

  - Always use Java in code examples
  - Keep responses under 100 characters
  - Only communicate in Hindi

⚠️ Copilot 可以用不同的语言响应，但其主要训练集是英语。一些用户报告了非英语输出的混合结果。

我是单语使用者，所以我不能亲自证实非英语的准确性，但我很想听听你的经历！如果你用其他语言使用过 Copilot，请在下面评论——告诉我们这些说法是否有效。

🌟 用户指令 - 专业技巧：

除非有什么东西让你每次看到 Copilot 都想把它掐死（除了幻觉，我们有时都忍受），否则我建议你完全跳过这些。通过设置这些来暴露自己的潜在冲突真的不值得。

这不是列出你能想到的每一件小事、提交一个 100 行的文件然后忘记它的时候。如果你想这样做，那么看看 Model Playground，甚至把它作为一次性上传附加到 Copilot 的 Chat 上下文。

如果你像我一样可能在小细节上纠缠，这些可能值得为你自己的工作流理智进行权衡。

你可以通过将用户指令限制在仅足以具体定义你的方向的关键词，并且永远不定义超过 3 行来降低风险。

请务必用示例定义你想要的输出，以便最大限度地利用 Copilot 的任何形式！

如果你决定个人指令值得冒风险，从最多 2–3 条高影响规则开始。超过那个数量，Copilot 就开始感到困惑，尤其是在长期运行的聊天中！

🍭 我个人设置中的真实示例：

"github.copilot.chat.codeGeneration.instructions": [
  { "text": "Keep conversations short: when you respond in the chat, limit output to one sentence (unless explicitly asked to explain with details)." },
  { "text": "If a task violates standards or design, STOP IMMEDIATELY and analyze your context methodically to identify the problem. Once the primary concern is identified, list it along with any related bugs and suggestions to improve or remediate completely." },
  { "text": "Include emojis in chat to keep responses fun (never in code, comments, or docs) 😊👍" }
]

🛠️ 存储库级别指令：真正的强大招式

它们在你的存储库的 .github/copilot-instructions.md 文件中有一个永久的家，可以帮助推动 Copilot 对该特定代码库行为的一致性，无论使用哪种 IDE 或用户。

• 功能间的一致性
• 更聪明的代码建议
• 量身定制的代码审查
• 提示文档生成（是的，它可以工作！）

🧚‍♀️ 示例用例

‼️ 这是另一个地方，其中 yaml frontmatter 与指定正确的 glob 模式相结合值得研究投资和花费时间来设置。我没有一个好的测试场所来处理这个场景而不需要从头开始构建它，所以我在这方面帮不了太大的忙。

🎨 代码样式——示例规则

Copilot 在没有明确示例的情况下处理格式规则不好。所以如果你坚持定义代码风格，至少给它两个清晰的"做这个/不要做这个"的模式。

就个人而言，我建议完全跳过样式部分，转而支持可靠的 linter + formatter。花费那段时间在经过测试和可靠的解决方案上。额外的好处——你将消除那些总是出现的 PR，因为在所有 10k+ 行代码上新增/删除逗号，因为某人的偏好妨碍了进展。

与其列出你能想到的每一种风格，然后在上面添加另外 3 倍的行以获得必要的示例来产生差异，这种方法使覆盖风格真的很简单：

## Code Style
Follow rules in `.eslintrc.js`

更好的方法是？用预提交钩子强制执行它。让自动化做繁重的工作，把 Copilot 排除在外。

⚠️ 有一个值得一提的例外：如果 Copilot 开始持续违反你风格指南中的几个东西，即使它都被 linters 和钩子严格强制执行。在这种情况下，在指令文件中定义临时的样式示例是有帮助的。只在 Copilot 的行为自我纠正的足够长时间内保留它们。然后删除它们。

存储库指令示例：

💫 这受到了我一个早期阶段的黑客时间项目的启发——仍然希望很快把它变成现实！ 😜

# GitHub Copilot Instructions for Hack Time Project

## Goals for this app
- This app is an extension for GitHub Copilot that helps users create custom repository-level instructions.
- The instructions should be comprehensive and clear, guiding GitHub Copilot to the best practices for all developers.
- Users should have an interactive experience to generate and refine instructions.
- Instructions should be adaptable to different repositories, scenarios, and user needs.
- You have the flexibility to adjust the content based on the repository in context and the user's requirements.

## Copilot Persona
- You are a helpful assistant that guides users through creating comprehensive repository instructions.
- Provide suggestions based on repository context and user input.
- Ensure generated instructions are clear, concise, and actionable.
- Adapt to user feedback and refine instructions iteratively.
- If the user expresses they are finished in any way, you should IMMEDIATELY use all information to define output instructions and a final assessment of their effectiveness, along with recommendations for future improvements.
- ALWAYS ask the user if there is anything else they would like to add or modify before closing the interaction.

## Technology Stack
- Node.js v24.2.0 (ES6 modules enabled via `"type": "module"`)
- npm v11.3.0
- Express v5.1.0

## Development Guidelines
- Volta manages Node.js and npm versions.
- All code should be written in JavaScript (ES6+).
- Run `npm lint` and `npm format` to check code quality.
- Use `npm test` to run tests.
- Dotenv is used for environment variables, DO NOT TOUCH `.env` files.
- Avoid modifying dotfiles or configuration files unless you have explicit instructions.

## Testing Guidelines
- Use Vitest for unit tests and all mock scenarios.
- Use a TDD approach to ensure all features are tested before implementation.
- Place tests in the `tests` directory, mirroring the `src` structure.
- NEVER skip tests - broken tests should be fixed immediately or removed.
- Code coverage rules are defined in `vitest.config.js` and should be strictly enforced

## Documentation Guidelines
- Use JSDoc for documenting functions and classes.
- Maintain a `README.md` file with project overview and setup instructions.
- Append `Generated by AI as directed by {input:usersFullName} on <date>` to ALL generated documentation
    - DO NOT guess or make up any users' names. Instead, prompt them for it directly.
    - Documentation includes (but not limited to) Jira, Confluence, GitHub and all markdown files in this repo.

## Code Style Guidelines
- Use ESLint and Prettier for all JavaScript/TypeScript code.

## Performance Guidelines
- It is critical to maintain high performance.
- Utilize available profiling tools to identify bottlenecks.
- Optimize algorithms and data structures for efficiency.
- Avoid unnecessary computations and memory usage.

## Application Health
- This is a new hack time project, so the codebase is not yet mature.
- The code is expected to be clean, well-structured, and maintainable.
- Follow best practices for code quality and maintainability.
- NEVER assume backwards compatibility anywhere in the codebase. All refactors should be considered new development.

🏢 组织级别指令（我知道的一点点）

这是 GitHub 组织的一个较新功能——旨在跨所有项目强制实施安全编码指南之类的东西。

我还没有有很多实践经验，但想把它作为潜在冲突的来源指出来。在 Copilot 聊天中查看"References"部分——如果组织级别指令处于活跃状态，你会在那里看到它们。

💻 仅限 VS Code：指令类型

更新：VS Code 过去支持各种定制指令（commits、reviews、tests 等）。现在这些已正式弃用，取而代之的是默认的 .github/copilot-instructions.md 文件，以及更通用的 .github/instructions/*.instructions.md，在 frontmatter 中定义了有效的 applyTo 作为 glob 模式（与你添加到 .gitignore 的方式相同）。

Copilot 不会自己"变得更好"。它无法学到你想要什么（还不能）。但通过一些周密的指令，你可以教它成为更好的开发助手——对你、你的团队和你的代码库。

🙋‍♀️ 构建过？破坏过？借用过？

如果这些东西对你有效、以有趣的方式破坏，或者只是帮你写更好的指令——让我知道！

更好的工作流总是目标——继续分享和相互支持！

🚨 我得到了一些关于高级请求的进一步澄清，但还没有机会验证它。如果你很好奇，看看 VS Code 的最近直播。我认为这是正确的那个，但不确定。他们在最后才保存了任何提及它的内容。

我在这里分享的一切都是我自己的观点——在 AI 工具（GitHub Copilot、ChatGPT 和它们的伙伴）的帮助下创建，但总是有人在循环中。我尽力捕捉意外的偏见和事实检查，但如果你发现任何奇怪的东西，让我知道！AI 不是完美的，我也不是。

TL; DR: AI 帮忙了，但你可以怪我造成的混乱！ 🫠

有关进一步的措施，你可能会考虑屏蔽此人和/或报告滥用行为