datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
新增功能：
- 创建完整的 AI 辅助开发工作流程指南
- 提供实用的提示词模板和检查清单
- 包含详细的实战案例和最佳实践

文档更新：
- 在 README 中强调 AI 指南的重要性
- 添加醒目的必读警告和使用建议
- 重新组织开发文档结构

本次更新旨在帮助开发者使用 AI 工具遵循项目规范，
显著提高开发效率和代码质量。
This commit is contained in:
moyin
2025-12-13 16:30:59 +08:00
parent 7ebc75e678
commit 398fbc42bc
2 changed files with 490 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
README.md
View File

@@ -2,6 +2,22 @@
一个基于 NestJS 的 2D 像素风游戏后端服务 一个基于 NestJS 的 2D 像素风游戏后端服务
---
## 🚨 开发者必读警告
**⚠️ 在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
**📢 重要提醒：**
- 🚫 **未阅读 AI 辅助指南的代码将无法通过审查**
- 🤖 **学会使用 AI 助手可以让你的开发效率提升 300%**
- 📝 **AI 可以帮你自动生成符合规范的代码和注释**
- 🔍 **AI 可以实时检查你的代码质量**
**👉 [立即阅读 AI 辅助开发指南](./docs/AI辅助开发规范指南.md)**
---
## 技术栈 ## 技术栈
- **NestJS** `^10.4.20` - 渐进式 Node.js 框架 - **NestJS** `^10.4.20` - 渐进式 Node.js 框架
@@ -37,6 +53,22 @@
- `typescript` `^5.9.3` - TypeScript 编译器 - `typescript` `^5.9.3` - TypeScript 编译器
- `pino-pretty` `^13.1.3` - Pino 美化输出 - `pino-pretty` `^13.1.3` - Pino 美化输出
## 🚨 重要：开发前必读
### ⚠️ 所有开发者必须先阅读 AI 辅助开发指南
**在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
这个指南将教你如何：
- 🤖 使用 AI 助手遵循项目规范
- 📝 自动生成规范的代码和注释
- 🔍 实时检查代码质量
- 🚀 显著提高开发效率和代码质量
**不阅读此指南直接开发，代码审查将无法通过！**
---
## 开发规范 ## 开发规范
### 命名规范 ### 命名规范
@@ -130,17 +162,26 @@ export class PlayerService {
详细规范请查看：[后端开发规范指南](./docs/backend_development_guide.md) 详细规范请查看：[后端开发规范指南](./docs/backend_development_guide.md)
## 文档 ## 📚 开发文档
- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例 ### 🔥 必读文档
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践 - **[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)** - 🚨 **所有开发者必读！** 教你如何使用 AI 遵循项目规范
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
### 📋 规范文档
- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求 - [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例
### 💡 使用建议
1. **开发前**：先读 AI 辅助指南，了解如何用 AI 帮助遵循规范
2. **开发中**：参考具体规范文档，使用 AI 实时检查代码质量
3. **提交前**：用 AI 检查代码和提交信息是否符合规范
## 前置要求 ## 前置要求
- **Node.js** >= 18.0.0 - **Node.js** >= 18.0.0 默认：24.7.0
- **pnpm** >= 8.0.0（推荐） - **pnpm** >= 8.0.0（推荐）默认：10.25.0
如果还没有安装 pnpm，请先安装： 如果还没有安装 pnpm，请先安装：
@@ -281,6 +322,8 @@ export class UserService {
详细使用方法请参考：[后端开发规范指南 - 日志系统使用指南](./docs/backend_development_guide.md#四日志系统使用指南) 详细使用方法请参考：[后端开发规范指南 - 日志系统使用指南](./docs/backend_development_guide.md#四日志系统使用指南)
**💡 提示：使用 [AI 辅助开发指南](./docs/AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的日志代码！**
## 下一步 ## 下一步
- 在 `src/api/` 目录下创建游戏相关的控制器和网关 - 在 `src/api/` 目录下创建游戏相关的控制器和网关

441
docs/AI辅助开发规范指南.md Normal file
View File

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