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

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

简介
文章目标
结果展示
步骤
步骤
- 准备目录
- 每个文件的作用
- 实例
- [与Copilot 交互](#与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> 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模式下的代码补全功能，是免费的。

指令分类

名称	操作
`斜杠命令 (/)	用快捷键快速指定任务类型，如 /tests（生成测试）、/fix（修复代码）、/explain（解释代码）、/docs（生成文档）。
上下文引用 (#)`	在提示中引用特定文件(#file)、文件夹(#folder)或代码块(#selection)，提供精准上下文
聊天参与者 (@)	召唤特定领域的"专家"，如 @workspace（理解整个项目）、@terminal（终端操作）等

常用指令

指令名称	作用
/explain	解释你选中的代码是如何工作的
/tests	为选中的函数或类生成单元测试。
/fix	让Copilot分析并尝试修复选中的错误代码。
/clear	清空当前聊天会话，开启新对话。
/new	开启一个新的、专注于特定任务的聊天会话
/plan	在进行大型开发前，使用Plan代理生成一份详细的实现计划。
/init	按照你编写的Markdown初始化项目目录结构，生成对应的内容本例子中主要使用了此命令。
@workspace	在聊天中引用整个工作区，让Copilot基于项目上下文回答问题。

交互模式

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 更多是说明性文档。
1. 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 通常是一次性任务模板。
1. hook.md（钩子文件）
- 作用：在特定事件（如代码生成前/后、文件保存前）执行自定义逻辑。类似于 Git hooks 或 IDE 的脚本钩子。
- 生效时机：理论上是在代码生成之前或之后，但由于 Copilot 没有内置钩子系统，通常需要人驱动或AI 自觉遵守（通过指令要求 AI 在输出前自我审查）。
- 区别：hook.md 是动作触发，而其他文件是状态定义或模板。
1. skills.md / *.skill.md（技能文件）
- 作用：描述如何完成某个功能模块或业务流程（例如"活动报名"的实现步骤、缓存策略、并发控制）。它不是可执行代码，而是知识文档。在 Copilot 中，可以通过 @workspace 引用这些文件，或要求 AI "参考 skills/activity-management-skill.md 实现报名功能"。
- 生效时机：当用户明确要求参考该技能，或 AI 自动检索到相关文档时。如果放在 .github/skills/，Copilot 可能会将其作为上下文的一部分（取决于模型检索能力）。更可靠的做法是用户在对话中 @ 引用。
1. prompt.md（提示文件）
- 作用：定义一个一次性、结构化的任务模板，例如"设计一个 API 端点"、"生成单元测试"。通常包含固定的输出格式、步骤要求。用户可以通过斜杠命令（如果配置了）或直接说"按照 .github/prompts/api-design.prompt.md 来设计"来触发。
- 生效时机：用户主动引用时。它不像 agent.md 那样改变 AI 的整体角色，而是限定当前任务的输出结构。
- 区别：与 skills.md 相比，prompt.md 更短小、聚焦、可执行；skills.md 更全面、背景丰富。与 agent.md 相比，prompt.md 不改变 AI 的身份，只改变输出格式。
1. 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 模式，限制也比较大