GitHub Copilot 自定义指令配置指南：规范与协作

方法二：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
  }
}

用户级别设置

如果你希望所有项目都遵循某些通用习惯，可以在全局 settings.json 中添加：

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

方法三：代码内注释指令

有时候我们需要针对特定文件或函数给出临时指导，这时候代码内的注释指令就很实用。

文件顶部注释

在文件头部声明本文件的特殊要求：

/**
 * COPILOT: 本文件遵循以下规范
 * 1. 使用 TypeScript 严格模式
 * 2. 所有函数必须有类型定义
 * 3. 错误处理使用统一的 try-catch 模式
 */
export class UserUtils {
  // COPILOT: 验证用户权限，返回布尔值
  static hasPermission(user: User, permission: string): boolean {
    return user.permissions.includes(permission);
  }
}

内联注释指令

在关键逻辑处直接告诉 Copilot 怎么做：

// 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);

特定功能指令

在模板或脚本中嵌入指令，引导生成符合上下文的代码：

<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）：最高优先级，被版本控制跟踪，适合团队共享和项目特定规范。
2. VS Code 工作区设置（.vscode/settings.json）：用于开发环境配置和插件行为定制。
3. 代码内注释指令：适合文件或函数级别的特定指导，或者临时性的上下文提示。

团队协作最佳实践

规范制定不能闭门造车，建议流程如下：

1. 团队讨论：收集团队成员意见，确保规范可执行。
2. 试运行：在小范围内测试规范效果。
3. 正式采用：将规范纳入项目文档。
4. 持续改进：定期评估和更新规范。

为了保障执行，可以将规范集成到 CI/CD 流程中，例如：

# 规范执行检查清单

## 代码提交前检查
- [ ] ESLint 检查通过
- [ ] TypeScript 编译无错误
- [ ] 单元测试覆盖率满足要求

## 代码审查要点
- [ ] 函数命名符合规范
- [ ] 错误处理完整
- [ ] 无安全漏洞

常见问题解答

Q: Copilot 不遵循自定义指令怎么办？ A: 先检查文件格式是否正确，确保指令描述清晰具体。尝试在代码中添加更多上下文注释，或者组合使用多种方法（文件 + 注释 + 设置）。

Q: 团队成员遵循程度不一致？ A: 将规范集成到 CI/CD 流程，使用自动化工具强制检查，定期进行代码审查培训，建立规范违反的反馈机制。

Q: 如何平衡规范严格性和开发效率？ A: 区分强制性规范和建议性规范，提供自动化工具减少手动工作，根据项目阶段调整规范严格程度。

最后总结一下

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

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

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