为Github Copilot创建自定义指令/说明/注意事项
GitHub Copilot 是一个强大的 AI 编程助手，通过合理配置自定义指令，可以让它更好地理解和遵循项目特定的编码规范，省的每次提问时输入重复提示语。
目录
方法一：项目级别指令文件（推荐）
1. 创建 .github/.copilot-instructions.md 文件
官方文档凌晨：https://copilot-instructions.md/#main-content-zh
在项目根目录创建此文件，如果尚无 .github 目录，则创建该目录。Copilot 会自动读取并作为上下文参考。
文件路径跟是否启用配置项如下，可以直接在vscode中搜索对应选项：
2.文件内容示例
# Copilot 代码规范 ## 通用编程规范 ### 函数命名规范 - 使用驼峰命名法（camelCase） - 函数名应该是动词或动词短语 - 布尔值返回的函数使用 is/has/can 前缀 #### 示例： ```javascript // ✅ 正确 function calculateTotalPrice(items) { } function isUserLoggedIn() { } function hasPermission(user, action) { } // ❌ 错误 function price(items) { } function userLogin() { } function permission(user, action) { } 也可以写一些团队规范，如：
### 组件开发规范 - React/Vue 组件使用 PascalCase 命名 - 组件文件名与组件名保持一致 - Props 使用 TypeScript 类型定义 - 状态管理优先使用内置 hooks ### API 调用规范 - 使用 async/await 而不是 Promise.then() - 统一错误处理机制 - 请求参数使用 TypeScript 接口定义 ## 项目特定规范 ### 目录结构约定 - `/src/components` - 可复用组件 - `/src/pages` - 页面组件 - `/src/utils` - 工具函数 - `/src/types` - TypeScript 类型定义 - `/src/api` - API 接口封装 ### 样式规范 - 使用 CSS Modules 或 styled-components - 颜色值使用 CSS 变量 - 响应式设计优先使用 flexbox 和 grid ## 代码提交规范 ### Git Commit 消息格式 <type>(<scope>): <subject> <body> <footer> 类型包括： - `feat`: 新功能 - `fix`: 修复 bug - `docs`: 文档更新 - `style`: 代码格式化 - `refactor`: 重构代码 - `test`: 添加测试 - `chore`: 维护任务 ### 代码审查要求 1. 所有 public 方法必须有 JSDoc 注释 2. 复杂逻辑必须添加内联注释 3. 新增功能必须包含单元测试 4. 性能敏感代码需要性能测试 ### API 设计原则 - RESTful API 设计规范 - 使用标准 HTTP 状态码 - 响应数据格式统一使用 JSON - 分页查询统一参数命名 也可以针对特定技术栈创建指令：
# Vue.js 项目指令 ## 组件开发规范 - 使用 Composition API 优于 Options API - 组件 props 必须定义 TypeScript 类型 - 事件命名使用 kebab-case - 组件样式使用 scoped ## 状态管理 - 使用 Pinia 进行状态管理 - Store 模块按功能划分 - Actions 使用 async/await ## 路由配置 - 路由懒加载 - 路由守卫统一处理权限 - 页面标题动态设置 方法二：VS Code 工作区设置
项目级别设置
在项目根目录创建 .vscode/settings.json：
{"github.copilot.enable":{"*":true,"plaintext":false,"markdown":true},"github.copilot.advanced":{"customInstructions":"遵循项目编码规范：函数使用驼峰命名，组件使用 PascalCase，优先使用 TypeScript 类型定义。API 调用使用 async/await。","inlineSuggestCount":3},"editor.rulers":[80,120],"editor.codeActionsOnSave":{"source.fixAll.eslint":true,"source.organizeImports":true}}用户级别设置
打开 VS Code 设置（Ctrl+,），在 settings.json 中添加：
{"github.copilot.advanced":{"inlineSuggestCount":3,"customInstructions":"编写清晰、可维护的代码。优先使用现代 JavaScript/TypeScript 特性。函数命名要有描述性。添加必要的错误处理。"}}方法三：代码内注释指令
文件顶部注释
/** * COPILOT: 本文件遵循以下规范 * 1. 使用 TypeScript 严格模式 * 2. 所有函数必须有类型定义 * 3. 错误处理使用统一的 try-catch 模式 * 4. 异步操作使用 async/await */// COPILOT: 用户相关的工具函数集合exportclassUserUtils{// COPILOT: 验证用户权限，返回布尔值statichasPermission(user: User, permission: string): boolean {return user.permissions.includes(permission);}}内联注释指令
// COPILOT: 创建一个异步函数来获取用户数据，包含错误处理asyncfunctionfetchUserData(userId:string):Promise<User |null>{try{const response =await api.get(`/users/${userId}`);return response.data;}catch(error){console.error('Failed to fetch user data:', error);returnnull;}}// COPILOT: 使用防抖优化搜索功能const debouncedSearch =debounce((query:string)=>{performSearch(query);},300);特定功能指令
<template> <!-- COPILOT: 创建一个响应式的用户卡片组件，支持头像、姓名、角色显示 --> <div> <img :src="user.avatar" :alt="`${user.name}的头像`" /> <div> <h3>{{ user.name }}</h3> <span>{{ user.role }}</span> </div> </div> </template> <script setup lang="ts"> // COPILOT: 定义用户接口类型，包含必要的属性 interface User { id: string; name: string; avatar: string; role: string; email: string; } defineProps<{ user: User; }>(); </script> 实施建议
1. 优先级排序
- 项目级别指令文件（
.copilot-instructions.md）- 最高优先级- 被版本控制跟踪
- 团队共享
- 项目特定规范
- VS Code 工作区设置（
.vscode/settings.json）- 开发环境配置
- 编辑器行为定制
- 插件配置统一
- 代码内注释指令
- 文件或函数级别的特定指导
- 临时性指令
- 上下文相关提示
2. 团队协作最佳实践
规范制定流程
- 团队讨论 - 收集团队成员意见
- 试运行 - 在小范围内测试规范效果
- 正式采用 - 将规范纳入项目文档
- 持续改进 - 定期评估和更新规范
规范执行策略
# 规范执行检查清单 ## 代码提交前检查 - [ ] ESLint 检查通过 - [ ] TypeScript 编译无错误 - [ ] 单元测试覆盖率满足要求 - [ ] API 文档已更新 - [ ] 性能测试通过 ## 代码审查要点 - [ ] 函数命名符合规范 - [ ] 错误处理完整 - [ ] TypeScript 类型定义准确 - [ ] 注释清晰易懂 - [ ] 无安全漏洞 3. 监控和改进
指令效果评估
// 定期评估 Copilot 建议质量const evaluateCopilotSuggestions ={ metrics:{ acceptance_rate:'建议接受率', code_quality:'生成代码质量', consistency:'规范一致性', productivity:'开发效率提升'}, collection_methods:['开发者反馈调研','代码审查记录分析','自动化质量检测','性能指标监控']};持续优化策略
- 定期回顾 - 每月评估规范执行情况
- 反馈收集 - 建立开发者反馈渠道
- 指令调整 - 根据实际使用情况优化指令
- 培训更新 - 定期培训团队新规范
4. 常见问题和解决方案
Q: Copilot 不遵循自定义指令怎么办？
A:
- 检查指令文件格式是否正确
- 确保指令描述清晰具体
- 在代码中添加更多上下文注释
- 使用多种方法组合（文件 + 注释 + 设置）
Q: 团队成员遵循程度不一致？
A:
- 将规范集成到 CI/CD 流程
- 使用自动化工具强制检查
- 定期进行代码审查培训
- 建立规范违反的反馈机制
Q: 如何平衡规范严格性和开发效率？
A:
- 区分强制性规范和建议性规范
- 提供自动化工具减少手动工作
- 根据项目阶段调整规范严格程度
- 收集开发者反馈及时调整
结论
通过合理配置 GitHub Copilot 的自定义指令，可以显著提高代码生成的质量和一致性。建议采用多种方法的组合：
- 使用项目级别指令文件作为主要规范载体
- 配置 VS Code 工作区设置统一开发环境
- 在关键代码处添加内联注释指导
- 集成 ESLint 等工具强制执行规范
- 建立完善的团队协作和监控机制
记住，最好的规范是团队都能理解、接受并愿意执行的规范。在制定和实施过程中，要充分考虑团队实际情况，持续优化改进。
