1. 项目概述：Copilot规则库的诞生与价值

在代码开发的日常工作中，我们越来越多地依赖AI编程助手，比如GitHub Copilot。它就像一位不知疲倦的搭档，能根据上下文快速生成代码片段，极大地提升了开发效率。然而，任何强大的工具都有其两面性。你是否遇到过Copilot生成的代码风格与团队规范不符？或者它反复建议一些你早已弃用的老旧API？又或者，在特定敏感目录下，你根本不希望它弹出任何建议，以免干扰或泄露信息？这些问题，正是 eumiguellllllllll/copilot-rules 这个项目试图系统化解决的。

简单来说，这是一个专注于为GitHub Copilot定义和管理“行为规则”的开源仓库。它不是一个插件，也不是一个客户端，而是一套基于 .github/copilot-instructions.md 文件和目录级 .copilotignore 文件的规则集合与最佳实践指南。你可以把它理解为一本为你的Copilot“私人助理”量身定制的《工作手册》和《行为守则》。通过编写清晰的指令，你可以告诉Copilot：“在我们团队的项目里，请使用双引号而不是单引号”、“请不要在这个存放密钥的 config/ 文件夹里给我任何建议”、“生成函数时请优先考虑异步模式并添加JSDoc注释”。

这个项目的核心价值在于 将AI辅助的随机性，转变为符合项目规范与开发者习惯的确定性输出 。它降低了因AI建议引入代码风格混乱、安全风险或技术债的可能性，让Copilot从一个“聪明的代码补全工具”，进化成为真正理解并融入你开发生态系统的“智能协作者”。无论你是独立开发者，还是大型团队的Tech Lead，管理好Copilot的行为，都是提升代码质量与团队协作效率的关键一步。

2. 核心机制与文件结构解析

要理解如何使用这个规则库，首先得摸清GitHub Copilot读取开发者指令的机制。Copilot主要依据两个位置的文件来调整其行为：项目根目录下的 .github/copilot-instructions.md ，以及任何目录下的 .copilotignore 文件。 eumiguellllllllll/copilot-rules 项目正是围绕如何高效编写和维护这些文件而组织的。

2.1 指令文件： .github/copilot-instructions.md

这是项目的“总指挥部”。Copilot会优先读取这个文件中的内容，并将其作为生成代码时的全局约束和偏好。这个Markdown文件的内容就是直接给Copilot的“自然语言指令”。

文件位置与命名是固定的 ：它必须位于项目根目录的 .github 文件夹内，且必须命名为 copilot-instructions.md 。这是GitHub官方约定的路径，Copilot客户端会主动去查找并解析它。

指令的编写逻辑 ：指令不是编程代码，而是用英语（目前Copilot对英文指令理解最佳）描述的规则。你可以把它想象成在给一位新入职的、能力很强但不太了解你们团队细节的工程师写工作说明。指令需要 具体、明确、无歧义 。

一个基础的指令结构通常包括：

  1. 代码风格规范 ：例如缩进、引号、分号、命名约定（camelCase, snake_case等）。
  2. 框架与库的特定约定 ：例如在React项目中优先使用函数组件和Hooks，在Vue 3中优先使用 <script setup> 语法。
  3. 项目架构偏好 ：例如“始终将工具函数放在 src/utils/ 目录下”，“服务层接口应以 Service 后缀结尾”。
  4. 禁用或鼓励的模式 ：例如“避免使用 var ，一律使用 const 或 let ”，“生成异步函数时请使用 async/await 而非Promise链”。

注意 ：指令的生效是概率性的，并非绝对强制。Copilot基于这些指令调整其生成模型的权重，使其输出更倾向于你的要求。指令写得越清晰、场景越具体，其影响力就越大。

2.2 忽略文件： .copilotignore

这是项目的“禁区地图”。它的作用类似于 .gitignore ，但对象是Copilot的代码建议。你可以在任何目录下放置一个 .copilotignore 文件，Copilot在该目录及其子目录下将 完全停止提供任何代码建议 。

典型使用场景 ：

  • 敏感目录 ：如存放环境变量、API密钥、配置凭据的 config/ , secrets/ 目录。
  • 生成代码或依赖目录 ：如 node_modules/ , dist/ , build/ , generated/ 等，这些目录下的代码不需要也不应该被补全。
  • 文档或资源目录 ：如 docs/ , assets/ ，在这些地方编辑文本文件时，代码建议纯属干扰。
  • 测试数据或Fixture目录 ：防止Copilot“学习”到测试用的假数据并错误地应用到生产代码中。

文件格式 ：非常简单，每一行是一个忽略模式，支持通配符。例如：

# 忽略所有密钥文件
*.key
*.pem
.env

# 忽略构建输出
/dist
/build

# 忽略某个特定目录下的所有内容
src/test/fixtures/

优先级 ：目录级的 .copilotignore 只影响该目录及其子目录。它和全局的 copilot-instructions.md 是协作关系，而非覆盖。一个在 /src/secrets/ 目录下的文件，即使全局指令要求生成某种格式的代码，也会因为本地 .copilotignore 的存在而收不到任何建议。

eumiguellllllllll/copilot-rules 仓库的核心内容，就是提供了针对不同编程语言、不同框架、不同场景的、经过验证的 copilot-instructions.md 模板和 .copilotignore 配置示例，开发者可以直接引用或基于此进行定制，避免了从零开始摸索的麻烦。

3. 规则编写实战：从通用到精细

掌握了核心文件后，我们来深入实战，看看如何编写真正有效的Copilot规则。规则的质量直接决定了Copilot“驯化”的程度。我们可以将规则分为几个层次：通用规范、语言/框架特定规则、以及项目级自定义规则。

3.1 通用编码规范指令

这部分规则适用于几乎所有项目，目标是建立基础的代码卫生习惯。在你的 copilot-instructions.md 文件开头，就可以放置这些内容。

# Global Coding Standards for This Project

## Style & Formatting
- **Indentation**: Use 2 spaces for indentation, never tabs.
- **Quotes**: Use single quotes (') for strings in JavaScript/TypeScript, unless the string contains a single quote. Use double quotes (") for JSX attributes and JSON.
- **Semicolons**: Always include semicolons at the end of statements in JavaScript/TypeScript.
- **Line Length**: Try to keep lines under 100 characters. Break long lines logically.
- **Trailing Commas**: Use trailing commas in multi-line object literals, arrays, and function parameter lists for cleaner diffs.

## Naming Conventions
- **Variables & Functions**: Use `camelCase`.
- **Classes & Constructors**: Use `PascalCase`.
- **Constants**: Use `UPPER_SNAKE_CASE` for true constants (values that never change).
- **Private Members**: Prefix private class properties or methods with an underscore `_` (e.g., `_internalMethod()`).

## Code Quality & Patterns
- **Avoid `var`**: Always use `const` for values that won't be reassigned, and `let` for those that will. Never use `var`.
- **Async/Await Preference**: When generating asynchronous code, prefer `async/await` syntax over raw Promises or callback hell.
- **Error Handling**: Always include error handling for async operations and file I/O. Suggest using `try...catch` blocks.
- **Commenting**: For complex functions or business logic, generate JSDoc-style comments (`/** ... */`) above the function definition, describing parameters and return values.

为什么这样写？ 这些指令非常具体，减少了Copilot的猜测空间。“使用2个空格”比“保持一致的缩进”更好。“优先使用async/await”比“写出优雅的异步代码”更明确。明确的指令能更可靠地塑造Copilot的输出。

3.2 语言与框架特定规则

这是规则库的精华所在。不同的技术栈有迥异的习惯。 eumiguellllllllll/copilot-rules 仓库的一个重大贡献就是收集了这些特定场景的规则。

以React (with TypeScript) 项目为例： 

# React & TypeScript Specific Rules

## Component Design
- **Component Type**: Always generate functional components using the `const` keyword and arrow function syntax (e.g., `const MyComponent: React.FC<Props> = ({ ... }) => { ... }`).
- **Hooks**: Prefer React Hooks (`useState`, `useEffect`, `useContext`, etc.) over class component patterns.
- **Props Interface**: Define a TypeScript interface or type for component props, named `[ComponentName]Props`.
- **Event Handlers**: Name event handler functions with the `handle` prefix (e.g., `handleClick`, `handleInputChange`).

## State & Effects
- **State Initialization**: When using `useState`, provide an explicit type parameter if the initial value doesn't fully infer the type (e.g., `useState<string>('')`).
- **Dependency Arrays**: In `useEffect`, `useCallback`, and `useMemo`, always include a comprehensive dependency array. If there are no dependencies, use an empty array `[]`.
- **Cleanup Functions**: If an effect requires cleanup (like subscriptions or timers), always generate a cleanup function returned from the `useEffect` callback.

## Styling & Structure
- **CSS-in-JS**: If the project uses styled-components or Emotion, generate styled components following the existing pattern (e.g., `const StyledButton = styled.button`...`).
- **File Structure**: For new components, suggest creating a dedicated directory with an `index.tsx` file and separate files for styles, types, or tests if the project uses that structure.

以Python (FastAPI) 项目为例： 

# Python FastAPI Project Rules

## Imports & Structure
- **Import Order**: Follow standard Python import order: standard library, third-party packages, local modules. Generate `import` statements accordingly.
- **Type Hints**: Always use type hints for function parameters and return values (e.g., `def get_item(item_id: int) -> Item:`).
- **Pydantic Models**: For request/response bodies, generate Pydantic `BaseModel` classes. Use descriptive field names and appropriate field types with validations (e.g., `name: str = Field(..., min_length=1)`).

## API Endpoints
- **Decorators**: Use the correct HTTP method decorators (`@app.get`, `@app.post`, etc.). Include the path as the first argument.
- **Dependency Injection**: For shared logic (like database sessions or authentication), suggest using FastAPI's `Depends`.
- **Status Codes**: Specify appropriate HTTP status codes in responses, like `status_code=status.HTTP_201_CREATED` for creation endpoints.
- **Error Responses**: When generating error handling, raise `HTTPException` with specific status codes and detail messages.

## Async & Database
- **Async Functions**: Mark endpoint functions as `async` if they perform I/O operations.
- **Database Sessions**: When interacting with a database (e.g., SQLAlchemy), suggest getting a session from a dependency and using `await` for async calls.

通过引入这些框架特定的规则，Copilot生成的代码将不再是通用的模板，而是高度契合你技术选型的、符合社区最佳实践的代码片段，大大减少了后续调整的时间。

3.3 项目级自定义与高级技巧

除了通用和框架规则，每个项目都有其独特的业务逻辑和架构约定。这是体现规则库价值的更深层次。

1. 领域特定语言 (DSL) 与模式： 如果你的项目内部有一套特定的抽象或模式，可以明确告知Copilot。

## Domain-Specific Patterns
- **Data Query Pattern**: When fetching data, always use the `useQuery` hook from our custom `@lib/data-fetching` package, not direct `fetch` calls. The pattern is `const { data, isLoading } = useQuery(['key'], fetcherFn)`.
- **Notification System**: To show a success message, use the `notify.success()` function from `src/utils/notifications`. It accepts a string message.
- **Entity CRUD Operations**: For operations on `User` entities, always go through the `UserService` class. Generate calls like `UserService.create(payload)` or `await UserService.findById(id)`.

2. 禁用过时或危险的模式： 主动阻止Copilot建议你不想看到的代码。

## Patterns to Avoid
- **Legacy API**: Do not suggest using the deprecated `ComponentWillMount` lifecycle method in React. Suggest `useEffect` instead.
- **Security Risks**: Never suggest code that concatenates user input directly into SQL strings. Always suggest using parameterized queries or an ORM method.
- **Performance Antipatterns**: Avoid suggesting `inline-style` objects in React for non-dynamic styles. Suggest using CSS classes or styled-components.

3. 利用上下文进行条件指令： 指令可以写得更加智能。例如，你可以根据文件路径给出不同指令（虽然Copilot指令文件本身不支持复杂逻辑，但你可以通过注释描述）。

## Context-Aware Suggestions
- **In `src/components/ui/`**: These are reusable UI components. Prioritize accessibility (ARIA attributes), forward refs using `React.forwardRef`, and keep them as pure/presentational as possible.
- **In `src/api/`**: These are API service modules. Always include error handling, request/response type definitions, and use the centralized `axiosInstance` for HTTP calls.
- **In `*.test.js` or `*.spec.ts` files**: When writing tests, prefer the Arrange-Act-Assert pattern. Use `describe` and `it` blocks. Mock external dependencies using `jest.mock()`.

编写高级规则的关键在于， 将你作为资深开发者在Review代码时最常指出的问题，转化为预防性的生成指令 。这相当于将代码审查的部分工作前置到了代码生成阶段。

4. 规则库的集成、管理与团队协作

创建了完善的规则文件后，如何将其有效地集成到开发流程中，并确保团队所有成员都能一致使用，是下一个挑战。 eumiguellllllllll/copilot-rules 项目本身作为一个开源仓库，也暗示了这方面的最佳实践。

4.1 项目初始化与集成流程

将Copilot规则作为项目脚手架的一部分，是确保其被使用的关键。

  1. 克隆或引用规则模板 ：你可以直接fork eumiguellllllllll/copilot-rules 仓库，或者将其中的模板文件复制到你的新项目中。更优雅的方式是，将你团队定制的 copilot-instructions.md 和 .copilotignore 样例放在公司内部的“工程样板”仓库里。

  2. 放置在正确位置 ：在项目根目录创建 .github/copilot-instructions.md 文件。根据项目需要，在敏感目录（如 /config , /secrets ）下创建 .copilotignore 文件。

  3. 版本控制 ：务必将这些文件加入Git版本控制（ .copilotignore 本身通常也需要被提交）。这是团队共享配置的基础。一个常见的 .gitignore 条目是“忽略除特定文件外的所有.copilotignore”，但实际上，你应该提交你主动创建的 .copilotignore 文件，就像提交 .eslintrc.js 一样。

  4. 文档化 ：在项目的 README.md 或 CONTRIBUTING.md 中，添加一个小节说明Copilot规则的存在和目的。告诉新成员：“本项目配置了Copilot指令以统一代码风格，请确保你的编辑器已启用Copilot并拉取了最新代码，规则详情见 .github/copilot-instructions.md 。”

4.2 团队协作与规则演进

规则不是一成不变的，随着项目发展和技术栈更新，规则也需要迭代。

  1. 设立规则负责人 ：在团队中，可以指定一人（或轮流）作为“Copilot规则维护者”，负责收集反馈、更新指令。这通常由对项目编码规范最熟悉的高级工程师或Tech Lead兼任。

  2. 建立反馈渠道 ：鼓励团队成员在遇到Copilot给出糟糕建议或优秀建议时提出反馈。可以在PR描述中、团队聊天频道里，或创建一个简单的GitHub Issue模板来收集。反馈内容可以是：“在编写X功能时，Copilot一直建议使用Y模式，但我们标准是Z，是否需要在指令中加强？”

  3. 通过Pull Request更新规则 ：对 copilot-instructions.md 的修改应该像修改源代码一样，通过Pull Request进行。在PR中详细说明修改原因（例如：“新增对Vue 3 <script setup> 语法的偏好指令”），并邀请团队成员Review。这确保了规则变更经过共识。

  4. 定期回顾 ：在团队技术会议或复盘会上，可以花几分钟讨论Copilot规则的有效性。是否有新的反模式出现？某个指令是否过于严格导致有用的建议被抑制？定期回顾能保持规则的活力与实用性。

4.3 处理规则冲突与优先级

当规则越来越多，可能会遇到指令之间看似矛盾的情况。Copilot如何处理呢？实际上，Copilot的指令模型是综合性的，它会尝试理解所有指令的上下文并找到一个平衡点。但我们可以通过编写技巧来管理优先级：

  • 具体优于笼统 ：“在 Button.tsx 组件中，所有 onClick 处理器必须被 useCallback 包裹”这条指令，会比“优化性能”这样的笼统指令拥有更高的权重。
  • 位置暗示重要性 ：虽然没有官方说明，但将最重要的、最基础的规则放在 copilot-instructions.md 文件的开头部分，是一个好习惯。
  • 避免直接冲突 ：尽量不要写逻辑上直接矛盾的指令，如一边说“使用单引号”，另一边又说“使用双引号”。如果因不同文件类型需要不同规则（如 .js 和 .json ），应通过更精确的描述来区分，例如：“在JavaScript/TypeScript文件中使用单引号，在JSON配置文件中使用双引号”。

实操心得 ：规则库的维护初期可能会觉得增加了开销，但一旦形成习惯，它带来的收益是巨大的。它相当于为团队引入了一位永远在线、且严格遵循规范的“初级代码审查员”，能将许多风格和模式问题扼杀在编码阶段，从而让团队成员在Code Review时能更专注于算法逻辑、架构设计和业务实现等更深层次的问题。

5. 效果评估、调试与高级场景

部署了Copilot规则后，如何知道它是否在正常工作？遇到问题如何调试？以及，除了基础规则，还能玩出什么花样？

5.1 验证规则是否生效

Copilot本身没有提供一个“规则调试面板”，但我们可以通过一些方法来验证：

  1. 观察性测试 ：在目标文件中，开始输入一个常见的代码模式。例如，在一个配置了React规则的JSX文件里，输入 function MyC ，观察Copilot的自动补全建议。它是否建议了 const MyComponent: React.FC ？如果是，说明全局指令可能生效了。

  2. 针对性测试 ：创建一个简单的测试。在项目中，打开一个应受规则影响的文件，尝试触发一个你明确写过指令的场景。比如，在Python文件中输入 def get_ ，看它是否建议了带类型提示的函数签名。

  3. 检查 .copilotignore ：在配置了 .copilotignore 的目录下新建一个文件，输入代码。如果Copilot完全不提供任何建议（连单行补全都没有），那么忽略规则就在生效。有时需要重启IDE或等待索引更新。

  4. 查看IDE状态 ：一些IDE的Copilot插件可能会在状态栏有提示，但通常不显示具体加载了哪些指令。最可靠的方式还是通过输入输出行为来判断。

5.2 常见问题与排查技巧

即使规则写得很好，也可能遇到不生效或效果不符合预期的情况。以下是一个快速排查指南：

问题现象 可能原因 排查步骤与解决方案
Copilot完全不提供建议 1. 未安装或未登录Copilot。
2. 当前文件/目录被 .copilotignore 忽略。
3. 网络或授权问题。		 1. 检查IDE插件状态，确保Copilot已激活。
2. 检查当前文件所在目录及父目录是否存在 .copilotignore 。
3. 尝试在项目根目录的明显位置（如 main.js ）输入，看是否有建议。
建议不符合编写的规则 1. 指令文件路径或名称错误。
2. 指令描述过于模糊或矛盾。
3. Copilot模型未加载最新指令（缓存问题）。
4. 指令与当前代码上下文冲突。		 1. 确认 copilot-instructions.md 位于 .github/ 下且拼写正确。
2. 重写指令，使其更具体、无歧义。例如，将“写好注释”改为“为每个公共函数生成JSDoc注释”。
3. 尝试重启IDE，或打开/关闭一下指令文件，强制重新读取。
4. Copilot会综合所有上下文，有时强上下文会压倒指令。尝试在更“干净”的新文件中测试。
部分规则生效，部分不生效 1. 某些指令的优先级或特异性不够。
2. 指令间存在隐含冲突。
3. Copilot对该特定模式的学习权重较低。		 1. 将重要的指令移到文件前面，并用更肯定的语气（如“Always use...”）。
2. 审查指令，确保没有逻辑冲突。对于框架特定规则，确保文件扩展名或项目上下文符合条件。
3. 对于某些非常小众的库或模式，Copilot可能本身知识有限，需要提供更详细的代码示例作为注释上下文来引导。
在团队中，成员A生效，成员B不生效 1. 成员B的本地项目未拉取最新的规则文件。
2. 成员B的IDE/Copilot版本或配置不同。
3. 成员B在个人Copilot设置中覆盖了某些行为（此功能若存在）。		 1. 确保所有成员都在同一代码分支上，并且规则文件已提交并推送。
2. 统一团队推荐的IDE和Copilot插件版本。
3. 目前Copilot暂无项目级设置覆盖个人设置的功能，此情况较少，但可检查IDE是否有相关设置。

一个高级调试技巧 ：如果怀疑指令未被读取，可以尝试在 copilot-instructions.md 文件中加入一条非常独特且容易观察的指令，例如：“ 在所有生成的数组字面量末尾，添加一个注释 // generated by copilot rules ”。然后在一个新文件中输入 const arr = [ ，看补全的数组是否包含该注释。这是一个明确的“信号”，可以验证指令加载状态。

5.3 超越基础：高级场景探索

当你熟练掌握了基础规则编写后，可以探索一些更高级的用法，让Copilot成为更强大的专属助手。

1. 引导生成复杂代码块与算法： 你可以用指令引导Copilot生成特定算法或复杂逻辑的模板。例如：

## Algorithm Patterns
- **Debounce Function**: When I type "debounce", suggest a standard debounce function implementation using `setTimeout` and `clearTimeout`, with leading/trailing option support.
- **Binary Search**: When I start implementing a search in a sorted array, suggest the binary search algorithm template with `left`, `right`, and `mid` pointers.
- **API Error Boundary**: For React projects, when I create an error boundary component, generate a class component that extends `React.Component` with `getDerivedStateFromError` and `componentDidCatch` lifecycle methods.

这相当于为你常用的代码模式创建了“快捷短语”。

2. 结合注释生成特定代码（注释驱动开发）： Copilot对紧邻的代码注释有极强的响应能力。你可以在指令中培养这种模式。

## Comment-Driven Development
- When I write a comment starting with `// TODO:`, generate the skeleton code for that task based on the comment description.
- For a comment like `// Fetches user data from API and caches it`, suggest an async function with `fetch`, error handling, and caching logic.

然后，在实际编码时，你只需写下注释 // TODO: create a utility to format date as YYYY-MM-DD ，Copilot就可能直接生成对应的函数。

3. 管理技术债与迁移路径： 在大型项目重构或迁移期间（如从JavaScript迁移到TypeScript，从React类组件迁移到函数组件），规则可以成为平滑过渡的桥梁。

## Migration Guidance (Vue 2 -> Vue 3)
- In `.vue` files, when generating a component, prefer the Composition API (`setup()` function) over Options API.
- For state management, suggest using `ref` and `reactive` from `vue` instead of `data()`.
- For lifecycle hooks, suggest `onMounted`, `onUpdated` instead of `mounted`, `updated`.

这样的指令能确保所有新代码都符合新的技术标准，逐步淘汰旧模式。

4. 编码安全与合规性检查（初级）： 虽然不能替代专业的SAST工具，但可以加入一些基础的安全提示。

## Security Reminders
- When generating code that involves constructing file paths with user input, suggest using `path.join()` (Node.js) or similar safe methods to prevent path traversal.
- When writing database queries, never suggest string concatenation for user input. Always suggest using parameterized queries or ORM methods.
- For environment variables, suggest reading from `process.env` and checking if they exist before use.

这能在编码阶段就植入一些安全意识。

管理Copilot规则库，本质上是在管理团队的“编码共识”和“知识资产”。它从被动的代码规范文档，转变为主动的、嵌入到开发流程中的智能引导系统。随着AI编程助手能力的进化，这类规则的定义与管理，必将成为现代软件工程实践中一项越来越重要的技能。

# 代码规范
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区