【使用Github Copilot自动按规范文档生成全部代码】

简介

Github Copilot是一个强大的 AI 编程助手，他是GitHub上的一个商业性的项目（需要订阅），也是一个插件，本例在Vscode中使用。
借助于Copilot，可以实现
1、代码补全；
2、下一步建议；
3、也可以完整的生成代码计划，生成代码

文章目标

前两点在Vs code中可以无缝的直接应用。通过 ctrl+I 指令，可以在代码编辑窗体，可以在 Copilot chat窗体，也可以在终端窗体中，随时拉起Copilot交互，提供建议。
本例子中是通过完整的一套markdown（包含需求文档和编程规范），让copilot 完整的按照需求及项目规范（包括项目结构，技术规范，代码规范，逻辑规范，事件消息规范）生成整套代码，并编译测试完成。

结果展示

目录结果：

• AGENTS.md 中要求的

UnionActivity.Backend/ ├── Controllers/ ├── Services/ ├── Repositories/ ├── Models/Entities/ ├── DTOs/ ├── MappingProfiles/ ├── Validators/ ├── Middlewares/ └── Extensions/

• 实际AI生成的

代码风格

• AGENTS.md中要求的

- 服务层示例：IActivityService 包含 Task<PagedResult<ActivityDto>> GetPublishedActivitiesAsync(ActivityQuery query) 等方法。 - 依赖注入：在 Program.cs 中注册 Scoped 生命周期。 - Redis 缓存：在服务构造函数中注入 IDistributedCache，缓存活动列表 10 分钟，主动失效。 - API 示例： ```csharp [HttpGet] public async Task<IActionResult> GetActivities([FromQuery] ActivityQueryParams @params) { var activities = await _activityService.GetActivitiesAsync(@params); return Ok(activities); }

• 实际生成的：
• 服务层：
  
• controller层：
  

功能要求：

• 需求文档（requirements.md)：

• skills约束：
  
• 实际生成
  

先总结：

对于中小型的项目，文档结构目录没有那么复杂的（当然大型建议拆分成多个中小型），严格按照项目需求，规范要求，定义好项目规范文档的话，GitHub Copilot可以很方便的生成你想要的项目。

步骤

环境准备

• 1、安装VS Code

• 2、安装“GitHub Copilot”插件：

  • 从VS Code 左侧的“扩展”图标（或按 Ctrl+Shift+X）中，搜索 GitHub Copilot Chat 安装。

  • 安装 OAI Compatible Provider for Copilot 来管理模型，可以使用这个插件，在Copilot Chat 模型中、CLI模式中 使用 智谱等大模型
    

  • 登录并授权：
    安装后，VS Code右下角会出现一个较小的Copilot图标。点击它，按提示登录你的GitHub账号并授权。
    

  • Github Copilot 虽然是一个插件，但是也是一个商业付费软件，没有订阅的用户可以在此期间选择 Copilot Free，
    从2026年6月1日起，Copilot 将调整收费模式，仍然对 Free的用户限制使用频次，对 pro 或 pro+ 用户分别是10美元和39美元的月费
    不过Chat模式下的代码补全功能，是免费的。

指令分类

常用指令

交互模式

• Chat (聊天模式)一个可以直接对话的AI助手，可以询问代码相关问题，或让它根据你的指令完成特定任务。

  打开方式

  • 侧边栏聊天 (Chat View)：点击 VS Code 左侧活动栏的“聊天”图标，或使用快捷键 Ctrl+Alt+I（Windows/Linux） / Cmd+Alt+I（macOS）。

  • 内联聊天 (Inline Chat)：在编辑器中选中代码，按 Ctrl+I（Windows/Linux） / Cmd+I（macOS）即可调出。

  • 快速聊天 (Quick Chat)：按快捷键 Ctrl+Shift+I（Windows/Linux）/ Cmd+Shift+I（macOS）调出快速输入框，提问后即可关闭。

• Agent Mode (代理模式)：这是它“智能体”特性的核心体现。是按照命令和提示，它会自主分析、规划步骤、创建修改文件、运行终端命令、执行测试，并根据结果自我修正，像一个初级开发者那样去完成任务。
  打开方式

  • 将聊天模式切换至 Agent：点击侧边栏或内联聊天输入框旁的Agent下拉菜单，选择 “Agent”

步骤

准备目录

1、在项目目录下创建 .github目录，

.github ├── copilot-instructions.md # 全局编码规范与技术栈约束 ├── AGENTS.md # AI 代理角色与协作流程 ├── requirements.md # 需求文档 至关重要 ├── agents/ #指定某个模块或者某个子项目的agent，这里可以直接认为是一个角色，比如后端专家，前端专家，是 按子项目或者大模块划分 │ ├── backend.agent.md # 后端开发专用代理 │ ├── frontend.agent.md # 前端 UniApp 代理 │ ├── database.agent.md # 数据库设计代理 │ ├── skills/ │ ├── activity-management-skill.md # 活动管理全流程技能 │ ├── export-statistics-skill.md # 数据导出与统计分析技能 │ └── rbac-skill.md # 角色权限控制技能 ├── hooks/ │ └── pre-generation-hook.md # 钩子，在xxx事件触发时要执行的一些动作，本例中加入了，每次 AI 生成代码前的一些动作 ├── instructions/ │ ├── backend-implementation.instructions.md # 后端整体开发指引约束 │ ├── frontend-implementation.instructions.md # 前端整体开发指引约束 │ └── redis-integration.instructions.md # 数据库设计详细说明约束 │ ├── prompts/ # 一次性模板，特定任务执行时，会按照模板执行 ├── api-design.prompt.md # 当需要设计新 API 时的模板 ├── database-schema.prompt.md #生成新表时的模板 ├── unit-test.prompt.md #使用 xUnit + Moq 测试服务层时的模板

每个文件的作用

• 1. AGENTS.md（多代理协作说明）

  • 作用：通常是一个项目级文档，描述有哪些 AI 代理、各自职责、协作流程。它本身不是 Copilot 直接执行的指令文件，而是给人（和 AI 的上下文）阅读的。但在 Copilot Chat 中，如果用户问“如何协作”，AI 会参考它。Copilot 的“Agent Mode”或自定义代理（*.agent.md）是真正可调用的。

  • 生效时机：当用户使用 /agent 命令或明确请求某个代理角色时，AI 会读取对应的 *.agent.md 文件，而 AGENTS.md 更多是说明性文档。

• 2. agent.md（或 *.agent.md，如 backend.agent.md）

  • 作用：定义可调用的 AI 代理。文件中通常包含角色描述、行为规则、输出格式等。在 Copilot Chat 中，用户输入 /agent backend 后，Copilot 会加载该文件作为系统提示，使 AI 扮演该角色执行任务。

  • 生效时机：用户主动调用 /agent 时。Copilot 会读取 .github/agents/.agent.md 文件，并注入到当前对话上下文。

  • 区别：与 AGENTS.md 不同，agent.md 是可执行的角色定义；与 prompt.md 不同，agent.md 是持久性的角色配置，而 prompt.md 通常是一次性任务模板。

• 3. hook.md（钩子文件）

  • 作用：在特定事件（如代码生成前/后、文件保存前）执行自定义逻辑。类似于 Git hooks 或 IDE 的脚本钩子。

  • 生效时机：理论上是在代码生成之前或之后，但由于 Copilot 没有内置钩子系统，通常需要人驱动或AI 自觉遵守（通过指令要求 AI 在输出前自我审查）。

  • 区别：hook.md 是动作触发，而其他文件是状态定义或模板。

• 4. skills.md / *.skill.md（技能文件）

  • 作用：描述如何完成某个功能模块或业务流程（例如“活动报名”的实现步骤、缓存策略、并发控制）。它不是可执行代码，而是知识文档。在 Copilot 中，可以通过 @workspace 引用这些文件，或要求 AI “参考 skills/activity-management-skill.md 实现报名功能”。

  • 生效时机：当用户明确要求参考该技能，或 AI 自动检索到相关文档时。如果放在 .github/skills/，Copilot 可能会将其作为上下文的一部分（取决于模型检索能力）。更可靠的做法是用户在对话中 @ 引用。

• 5. prompt.md（提示文件）

  • 作用：定义一个一次性、结构化的任务模板，例如“设计一个 API 端点”、“生成单元测试”。通常包含固定的输出格式、步骤要求。用户可以通过斜杠命令（如果配置了）或直接说“按照 .github/prompts/api-design.prompt.md 来设计”来触发。

  • 生效时机：用户主动引用时。它不像 agent.md 那样改变 AI 的整体角色，而是限定当前任务的输出结构。

  • 区别：与 skills.md 相比，prompt.md 更短小、聚焦、可执行；skills.md 更全面、背景丰富。与 agent.md 相比，prompt.md 不改变 AI 的身份，只改变输出格式。

• 6. instructions.md（如 backend-implementation.instructions.md）
     作用：提供分步骤的开发指南，通常用于指导开发者（或 AI）按顺序完成一系列任务。在 Copilot 中，可以作为路径级指令文件（.github/instructions/ 下），当编辑特定文件时自动注入；也可以通过 @ 引用。

  • 生效时机：
    如果放置在 .github/instructions/ 目录下，并设置了 applyTo 字段，则当用户打开匹配的文件路径时，Copilot 会自动加载该指令（类似上下文增强）。
    也可以手动要求 AI 遵循该指令。

  • 区别：instructions.md 侧重于过程指导（先做什么，后做什么），而 copilot-instructions.md 是全局编码规范；agent.md 是角色行为定义。

实例

本文实例也是借助于 deepSeek 生成，但是得把握以上的重要点和区分，可以在代码生成后，通过指定命令再补齐，
但是一定要注意的是，所有的md文件尽量清晰，但是不可以互相重叠，冲突，宁可缺少细节，但是不能互相冲突，错乱

需求（requirements.md)

copilot-instructions.md

AGENTS.md

指定Agent.md

hook.md

instructions.md

prompts.md

skills.md

与Copilot 交互

• 1、以上文件都准备好后，本例是通过OAI Compatible Provider for Copilot 选择了 glm5.1大模型
• 2、 在 copilot的chat 窗口内输入的 /init命令，
• 3、copilot自动开始工作

  • review了 所有的 文件
    

  • 制定了生成计划
    

  • 生成前后端代码
    
    此处必须 高亮突出 ：代码生成中完全遵循了agent及intrustions中的规范和所有的约束，全部按照md中的示例及要求生成。

  • 开始调试
    

  • 调试完成
    
    以上全部都自动完成，至此，约花去共15wtoken

启动项目

• 因为本地数据库和redis都已启动，服务端完全没有任何操作，连 restore都不用，直接就通过 IDE就成功启动了，
• 前端项目运行npm install ，npm run dev:h5等命令均出现错误【分析是因为本次指令中 要求 通过 Uniapp模式生成，此模式对H5支持本来就需要调试】
• 注意调试中出现的错误，需要手动 在chat窗口中与 copilot交互，来进行修复，此处要多次操作允许copilot执行，与设置的安全级别有关。
• 注意可直接输入错误，并输入要求，也可采用/fix等指令来让copilot执行
  
  调试错误很耗费token，一共又花去了15w token

经验

Markdown 文档一定要指令清晰，要职责分明，不能互相冲突，重要的部分 比如需求文档，colipot-instructions.md ,各个 Agent.md，各个skill.md 是不可少的。一次性模板，可以后续通过明确指令 再让 Copilot执行添加。
中小型的项目可以很方便通过此模式 直接生成。
但是比较 耗费token
copilot free 模式，限制也比较大