为Github Copilot创建自定义指令/说明/注意事项

GitHub Copilot 是一个强大的 AI 编程助手，通过合理配置自定义指令，可以让它更好地理解和遵循项目特定的编码规范，省的每次提问时输入重复提示语。

方法一：项目级别指令文件（推荐）

1. 创建 `.github/.copilot-instructions.md` 文件

官方文档凌晨：copilot-instructions.md/#main-conte...

在项目根目录创建此文件，如果尚无 .github 目录，则创建该目录。Copilot 会自动读取并作为上下文参考。文件路径跟是否启用配置项如下，可以直接在vscode中搜索对应选项：

2.文件内容示例

markdown 复制代码

# Copilot 代码规范

## 通用编程规范

### 函数命名规范
- 使用驼峰命名法（camelCase）
- 函数名应该是动词或动词短语
- 布尔值返回的函数使用 is/has/can 前缀

#### 示例：
```javascript
// ✅ 正确
function calculateTotalPrice(items) { }
function isUserLoggedIn() { }
function hasPermission(user, action) { }

// ❌ 错误
function price(items) { }
function userLogin() { }
function permission(user, action) { }

也可以写一些团队规范，如：

markdown 复制代码

### 组件开发规范
- 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
- 分页查询统一参数命名

也可以针对特定技术栈创建指令：

markdown 复制代码

# Vue.js 项目指令

## 组件开发规范
- 使用 Composition API 优于 Options API
- 组件 props 必须定义 TypeScript 类型
- 事件命名使用 kebab-case
- 组件样式使用 scoped

## 状态管理
- 使用 Pinia 进行状态管理
- Store 模块按功能划分
- Actions 使用 async/await

## 路由配置
- 路由懒加载
- 路由守卫统一处理权限
- 页面标题动态设置

方法二：VS Code 工作区设置

项目级别设置

在项目根目录创建 .vscode/settings.json：

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 中添加：

json 复制代码

{
  "github.copilot.advanced": {
    "inlineSuggestCount": 3,
    "customInstructions": "编写清晰、可维护的代码。优先使用现代 JavaScript/TypeScript 特性。函数命名要有描述性。添加必要的错误处理。"
  }
}

方法三：代码内注释指令

文件顶部注释

javascript 复制代码

/**
 * COPILOT: 本文件遵循以下规范
 * 1. 使用 TypeScript 严格模式
 * 2. 所有函数必须有类型定义
 * 3. 错误处理使用统一的 try-catch 模式
 * 4. 异步操作使用 async/await
 */

// COPILOT: 用户相关的工具函数集合
export class UserUtils {
  // COPILOT: 验证用户权限，返回布尔值
  static hasPermission(user: User, permission: string): boolean {
    return user.permissions.includes(permission);
  }
}

内联注释指令

typescript 复制代码

// COPILOT: 创建一个异步函数来获取用户数据，包含错误处理
async function fetchUserData(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);
    return null;
  }
}

// COPILOT: 使用防抖优化搜索功能
const debouncedSearch = debounce((query: string) => {
  performSearch(query);
}, 300);

特定功能指令

vue 复制代码

<template>
  <!-- COPILOT: 创建一个响应式的用户卡片组件，支持头像、姓名、角色显示 -->
  <div class="user-card">
    <img :src="user.avatar" :alt="`${user.name}的头像`" class="avatar" />
    <div class="user-info">
      <h3 class="user-name">{{ user.name }}</h3>
      <span class="user-role">{{ 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. 团队协作最佳实践

规范制定流程

团队讨论 - 收集团队成员意见
试运行 - 在小范围内测试规范效果
正式采用 - 将规范纳入项目文档
持续改进 - 定期评估和更新规范

规范执行策略

markdown 复制代码

# 规范执行检查清单

## 代码提交前检查
- [ ] ESLint 检查通过
- [ ] TypeScript 编译无错误
- [ ] 单元测试覆盖率满足要求
- [ ] API 文档已更新
- [ ] 性能测试通过

## 代码审查要点
- [ ] 函数命名符合规范
- [ ] 错误处理完整
- [ ] TypeScript 类型定义准确
- [ ] 注释清晰易懂
- [ ] 无安全漏洞

3. 监控和改进

指令效果评估

javascript 复制代码

// 定期评估 Copilot 建议质量
const evaluateCopilotSuggestions = {
  metrics: {
    acceptance_rate: '建议接受率',
    code_quality: '生成代码质量',
    consistency: '规范一致性',
    productivity: '开发效率提升'
  },
  
  collection_methods: [
    '开发者反馈调研',
    '代码审查记录分析',
    '自动化质量检测',
    '性能指标监控'
  ]
};

持续优化策略

定期回顾 - 每月评估规范执行情况
反馈收集 - 建立开发者反馈渠道
指令调整 - 根据实际使用情况优化指令
培训更新 - 定期培训团队新规范

4. 常见问题和解决方案

Q: Copilot 不遵循自定义指令怎么办？

检查指令文件格式是否正确
确保指令描述清晰具体
在代码中添加更多上下文注释
使用多种方法组合（文件 + 注释 + 设置）

Q: 团队成员遵循程度不一致？

将规范集成到 CI/CD 流程
使用自动化工具强制检查
定期进行代码审查培训
建立规范违反的反馈机制

Q: 如何平衡规范严格性和开发效率？

区分强制性规范和建议性规范
提供自动化工具减少手动工作
根据项目阶段调整规范严格程度
收集开发者反馈及时调整

结论

通过合理配置 GitHub Copilot 的自定义指令，可以显著提高代码生成的质量和一致性。建议采用多种方法的组合：

使用项目级别指令文件作为主要规范载体
配置 VS Code 工作区设置统一开发环境
在关键代码处添加内联注释指导
集成 ESLint 等工具强制执行规范
建立完善的团队协作和监控机制

记住，最好的规范是团队都能理解、接受并愿意执行的规范。在制定和实施过程中，要充分考虑团队实际情况，持续优化改进。

为Github Copilot创建自定义指令/说明/注意事项

目录

方法一：项目级别指令文件（推荐）

1. 创建 .github/.copilot-instructions.md 文件

2.文件内容示例

方法二：VS Code 工作区设置

项目级别设置

用户级别设置

方法三：代码内注释指令

文件顶部注释

内联注释指令

特定功能指令

实施建议

1. 优先级排序

2. 团队协作最佳实践

规范制定流程

规范执行策略

3. 监控和改进

指令效果评估

持续优化策略

4. 常见问题和解决方案

Q: Copilot 不遵循自定义指令怎么办？

Q: 团队成员遵循程度不一致？

Q: 如何平衡规范严格性和开发效率？

结论

1. 创建 `.github/.copilot-instructions.md` 文件