docs：新增 AI 辅助开发规范指南并更新文档

新增功能： - 创建完整的 AI 辅助开发工作流程指南 - 提供实用的提示词模板和检查清单 - 包含详细的实战案例和最佳实践文档更新： - 在 README 中强调 AI 指南的重要性 - 添加醒目的必读警告和使用建议 - 重新组织开发文档结构本次更新旨在帮助开发者使用 AI 工具遵循项目规范，显著提高开发效率和代码质量。
2025-12-13 16:30:59 +08:00
parent 7ebc75e678
commit 398fbc42bc
2 changed files with 490 additions and 6 deletions
--- a/docs/AI辅助开发规范指南.md
+++ b/docs/AI辅助开发规范指南.md
@@ -0,0 +1,441 @@
+# AI 辅助开发规范指南
+
+## 📋 文档概述
+
+本指南教你如何使用 AI 助手（如 Claude、ChatGPT、Kiro 等）来帮助遵循项目的开发规范，提高代码质量和开发效率。
+
+**⚠️ 重要提醒：所有开发者在开始编码前必须阅读本指南！**
+
+---
+
+## 🎯 为什么需要 AI 辅助？
+
+### 传统开发痛点
+- ❌ 记不住复杂的规范要求
+- ❌ 注释写得不够详细或格式不对
+- ❌ Git 提交信息不规范
+- ❌ 代码审查时发现大量规范问题
+- ❌ 新手学习成本高，容易出错
+
+### AI 辅助的优势
+- ✅ 实时检查和建议
+- ✅ 自动生成规范的注释和文档
+- ✅ 智能提示最佳实践
+- ✅ 减少人工审查工作量
+- ✅ 快速学习和应用规范
+
+---
+
+## 📚 项目规范文档体系
+
+我们的项目有以下四个核心规范文档：
+
+| 文档 | 用途 | AI 检查重点 |
+|------|------|------------|
+| [命名规范](./naming_convention.md) | 文件、变量、函数命名 | 命名格式、一致性检查 |
+| [Git 提交规范](./git_commit_guide.md) | 提交信息格式 | 提交类型、描述格式 |
+| [后端开发规范](./backend_development_guide.md) | 注释、日志、业务逻辑 | 注释完整性、日志规范 |
+| [NestJS 使用指南](./nestjs_guide.md) | 框架最佳实践 | 架构设计、代码组织 |
+
+---
+
+## 🤖 AI 辅助开发工作流程
+
+### 阶段一：开发前准备
+
+#### 1.1 向 AI 提供项目上下文
+
+**推荐提示词模板：**
+
+```
+我正在开发一个基于 NestJS 的像素游戏后端项目。
+
+项目有以下规范要求：
+1. 命名规范：[粘贴 naming_convention.md 的关键内容]
+2. Git 提交规范：[粘贴 git_commit_guide.md 的关键内容]  
+3. 后端开发规范：[粘贴 backend_development_guide.md 的关键内容]
+4. NestJS 使用指南：[粘贴 nestjs_guide.md 的关键内容]
+
+请帮我在开发过程中严格遵循这些规范。
+```
+
+#### 1.2 功能开发规划
+
+**提示词示例：**
+
+```
+我要开发一个用户管理功能，包括：
+- 用户注册
+- 用户登录  
+- 用户信息查询
+- 用户信息更新
+
+请帮我：
+1. 按照命名规范设计文件和类名
+2. 按照 NestJS 指南规划代码结构
+3. 按照后端开发规范设计注释模板
+```
+
+### 阶段二：编码过程中
+
+#### 2.1 代码生成和检查
+
+**提示词模板：**
+
+```
+请帮我生成一个用户服务类，要求：
+
+1. 严格按照后端开发规范添加完整注释：
+   - 模块级注释（功能描述、依赖模块、作者、版本）
+   - 类级注释（职责、主要方法、使用场景）
+   - 方法级注释（功能描述、业务逻辑、参数、返回值、异常、示例）
+
+2. 按照命名规范：
+   - 类名使用大驼峰
+   - 方法名使用小驼峰
+   - 文件名使用下划线分隔
+
+3. 包含以下方法：
+   - createUser() - 创建用户
+   - getUserById() - 根据ID获取用户
+   - updateUser() - 更新用户信息
+
+4. 每个方法都要考虑：
+   - 参数验证
+   - 异常处理
+   - 日志记录
+   - 业务逻辑完整性
+```
+
+#### 2.2 代码审查和优化
+
+**提示词示例：**
+
+```
+请帮我检查以下代码是否符合项目规范：
+
+[粘贴你的代码]
+
+请检查：
+1. 注释是否完整和规范
+2. 命名是否符合规范
+3. 业务逻辑是否考虑了所有情况
+4. 异常处理是否完善
+5. 日志记录是否合适
+6. 是否遵循了 NestJS 最佳实践
+
+如有问题，请提供具体的修改建议。
+```
+
+### 阶段三：提交前检查
+
+#### 3.1 Git 提交信息生成
+
+**提示词模板：**
+
+```
+我完成了以下开发工作：
+[描述你的具体改动]
+
+请按照 Git 提交规范帮我生成合适的提交信息：
+1. 选择正确的提交类型（feat/fix/docs/refactor等）
+2. 写出简短明确的描述（不超过50字符）
+3. 如果改动复杂，提供详细描述
+4. 考虑是否需要拆分成多个提交
+
+提交规范要求：
+- 使用中文冒号
+- 一次提交只做一件事
+- 描述要清晰明确
+```
+
+#### 3.2 最终代码检查
+
+**提示词示例：**
+
+```
+这是我准备提交的完整代码，请做最后的规范检查：
+
+[粘贴完整代码]
+
+请确认：
+1. 所有注释都符合后端开发规范
+2. 命名都符合命名规范
+3. 代码结构符合 NestJS 指南
+4. 没有遗漏的异常处理
+5. 日志记录完整合适
+6. 代码可以直接运行
+
+如有任何问题，请指出并提供修改建议。
+```
+
+---
+
+## 💡 AI 提示词最佳实践
+
+### 1. 上下文提供技巧
+
+**✅ 好的做法：**
+```
+我在开发 NestJS 项目的用户模块，项目要求：
+- 每个方法必须有完整注释
+- 使用 AppLoggerService 记录日志
+- 异常要抛出合适的 HTTP 状态码
+- 文件名使用下划线命名
+
+请帮我生成 UserController...
+```
+
+**❌ 不好的做法：**
+```
+帮我写个用户控制器
+```
+
+### 2. 具体化需求
+
+**✅ 好的做法：**
+```
+请检查这个方法是否符合规范：
+1. 注释是否包含功能描述、业务逻辑、参数说明？
+2. 是否考虑了参数验证？
+3. 是否有适当的异常处理？
+4. 是否记录了关键操作日志？
+```
+
+**❌ 不好的做法：**
+```
+这个代码有问题吗？
+```
+
+### 3. 迭代优化
+
+**建议流程：**
+1. 先让 AI 生成基础代码
+2. 要求 AI 检查规范符合性
+3. 根据建议进行修改
+4. 再次检查直到完全符合规范
+
+---
+
+## 🔧 常用 AI 检查清单
+
+### 代码质量检查
+
+复制以下清单，让 AI 帮你逐项检查：
+
+```
+请帮我检查代码是否符合以下规范：
+
+□ 模块级注释（功能描述、依赖模块、作者、版本）
+□ 类级注释（职责、主要方法、使用场景）  
+□ 方法级注释（功能描述、业务逻辑、参数、返回值、异常、示例）
+□ 文件命名使用下划线分隔
+□ 类名使用大驼峰命名
+□ 方法名使用小驼峰命名
+□ 变量名使用小驼峰命名
+□ 常量使用全大写+下划线
+□ 参数验证完整
+□ 异常处理合适
+□ 日志记录规范
+□ 业务逻辑考虑全面
+□ 符合 NestJS 最佳实践
+```
+
+### Git 提交检查
+
+```
+请帮我检查提交信息是否符合规范：
+
+□ 使用了正确的提交类型
+□ 使用中文冒号
+□ 描述简短明确（不超过50字符）
+□ 一次提交只做一件事
+□ 如有必要，包含详细描述
+□ 考虑了是否需要拆分提交
+```
+
+---
+
+## 📖 实战案例演示
+
+### 案例1：开发用户注册功能
+
+#### 第1步：向 AI 提供上下文
+
+```
+我要开发用户注册功能，项目规范要求：
+
+1. 后端开发规范：
+   - 每个方法必须有完整的三级注释
+   - 必须考虑所有异常情况
+   - 关键操作必须记录日志
+   - 使用防御性编程
+
+2. 命名规范：
+   - 文件名：user_service.ts
+   - 类名：UserService  
+   - 方法名：registerUser
+
+3. 需要实现的业务逻辑：
+   - 邮箱格式验证
+   - 邮箱唯一性检查
+   - 密码强度验证
+   - 创建用户记录
+   - 返回用户信息（不含密码）
+
+请帮我生成符合规范的代码。
+```
+
+#### 第2步：AI 生成代码
+
+AI 会生成包含完整注释和异常处理的代码。
+
+#### 第3步：代码检查
+
+```
+请检查上面生成的代码是否完全符合项目规范：
+1. 注释是否完整？
+2. 异常处理是否全面？
+3. 日志记录是否合适？
+4. 业务逻辑是否考虑了所有情况？
+```
+
+#### 第4步：提交信息生成
+
+```
+我完成了用户注册功能的开发，包括：
+- 创建 UserService 类
+- 实现 registerUser 方法
+- 添加完整的参数验证和异常处理
+- 记录关键操作日志
+
+请按照 Git 提交规范生成提交信息。
+```
+
+### 案例2：代码审查场景
+
+#### 现有代码检查
+
+```
+这是我写的代码，请帮我检查是否符合项目规范：
+
+[粘贴代码]
+
+项目规范要求：
+- 完整的三级注释
+- 防御性编程
+- 合适的异常处理
+- 规范的命名
+- 关键操作日志记录
+
+请指出所有不符合规范的地方，并提供修改建议。
+```
+
+---
+
+## ⚠️ 注意事项和限制
+
+### AI 的局限性
+
+1. **不能替代人工判断**
+   - AI 可能不理解特定的业务逻辑
+   - 复杂的架构决策仍需人工判断
+
+2. **需要明确的指导**
+   - 必须提供详细的规范要求
+   - 模糊的需求会得到模糊的结果
+
+3. **需要验证和测试**
+   - AI 生成的代码必须经过测试
+   - 不要盲目信任 AI 的输出
+
+### 最佳实践建议
+
+1. **始终提供项目上下文**
+2. **使用具体的检查清单**
+3. **迭代优化，不要一次性完成**
+4. **结合人工审查**
+5. **保持学习，理解规范背后的原理**
+
+---
+
+## 🚀 进阶技巧
+
+### 1. 创建个人 AI 助手模板
+
+将常用的提示词保存为模板，提高效率：
+
+```
+# 我的开发助手模板
+
+## 项目上下文
+我在开发 NestJS 像素游戏后端项目，规范要求：
+[保存项目规范要点]
+
+## 代码生成模板
+请生成符合规范的代码，包括：
+- 完整的三级注释
+- 防御性编程
+- 异常处理
+- 日志记录
+- 规范命名
+
+## 代码检查模板  
+请检查代码规范符合性：
+[保存检查清单]
+```
+
+### 2. 建立代码片段库
+
+让 AI 帮你生成常用的代码模板：
+
+```
+请帮我生成以下代码模板，符合项目规范：
+
+1. Controller 类模板
+2. Service 类模板  
+3. 异常处理模板
+4. 日志记录模板
+5. 参数验证模板
+
+每个模板都要包含完整的注释和最佳实践。
+```
+
+### 3. 自动化检查脚本
+
+```
+请帮我写一个脚本，自动检查代码是否符合命名规范：
+- 检查文件名是否使用下划线
+- 检查类名是否使用大驼峰
+- 检查方法名是否使用小驼峰
+- 生成检查报告
+```
+
+---
+
+## 📞 获得帮助
+
+如果在使用 AI 辅助开发过程中遇到问题：
+
+1. **查看规范文档**：确保理解项目规范要求
+2. **优化提示词**：提供更详细的上下文和需求
+3. **寻求人工帮助**：复杂问题可以咨询有经验的开发者
+4. **持续学习**：理解规范背后的原理，不只是机械执行
+
+---
+
+## 🎉 总结
+
+使用 AI 辅助开发可以显著提高代码质量和开发效率，但关键是：
+
+1. **提供清晰的上下文和规范要求**
+2. **使用具体的检查清单**
+3. **迭代优化，持续改进**
+4. **结合人工判断，不盲目依赖**
+5. **理解规范原理，而不只是执行**
+
+记住：**AI 是你的助手，不是替代品。好的开发者会善用工具，但始终保持思考和判断能力。**
+
+---
+
+**🔥 开始使用 AI 辅助开发，让代码质量和效率双提升！**