whale-town-end/docs/AI辅助开发规范指南.md

AI 辅助开发规范指南

📋 文档概述

本指南教你如何使用 AI 助手（如 Claude、ChatGPT、Kiro 等）来帮助遵循项目的开发规范，提高代码质量和开发效率。

⚠️ 重要提醒：所有开发者在开始编码前必须阅读本指南！

---

🎯 为什么需要 AI 辅助？

传统开发痛点

• ❌ 记不住复杂的规范要求
• ❌ 注释写得不够详细或格式不对
• ❌ Git 提交信息不规范
• ❌ 代码审查时发现大量规范问题
• ❌ 新手学习成本高，容易出错

AI 辅助的优势

• ✅ 实时检查和建议
• ✅ 自动生成规范的注释和文档
• ✅ 智能提示最佳实践
• ✅ 减少人工审查工作量
• ✅ 快速学习和应用规范

---

📚 项目规范文档体系

我们的项目有以下四个核心规范文档：

文档	用途	AI 检查重点
命名规范	文件、变量、函数命名	命名格式、一致性检查
Git 提交规范	提交信息格式	提交类型、描述格式
后端开发规范	注释、日志、业务逻辑	注释完整性、日志规范
NestJS 使用指南	框架最佳实践	架构设计、代码组织

---

🤖 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 辅助开发，让代码质量和效率双提升！