# 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) | 框架最佳实践 | 架构设计、代码组织 |

**📝 重要：修改记录注释规范**

当对现有文件进行修改时，必须在文件头注释中添加修改记录，格式如下：

```typescript
/**
 * 文件功能描述
 * 
 * 最近修改：
 * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
 * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
 * 
 * @author 原作者
 * @version x.x.x (修改后递增版本号)
 * @since 创建日期
 * @lastModified 最后修改日期
 */
```

**📏 重要限制：修改记录只保留最近5次修改，超出时删除最旧记录，保持注释简洁。**

**修改类型包括：**
- `代码规范优化` - 命名规范、注释规范、代码清理等
- `功能新增` - 添加新的功能或方法
- `功能修改` - 修改现有功能的实现
- `Bug修复` - 修复代码缺陷
- `性能优化` - 提升代码性能
- `重构` - 代码结构调整但功能不变

---

## 🤖 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 帮你逐项检查：

```
请帮我检查代码是否符合以下规范：

□ 模块级注释（功能描述、依赖模块、作者、版本）
□ 类级注释（职责、主要方法、使用场景）  
□ 方法级注释（功能描述、业务逻辑、参数、返回值、异常、示例）
□ 修改记录注释（如果是修改现有文件，必须添加修改记录和更新版本号，只保留最近5次修改）
□ 文件命名使用下划线分隔
□ 类名使用大驼峰命名
□ 方法名使用小驼峰命名
□ 变量名使用小驼峰命名
□ 常量使用全大写+下划线
□ 参数验证完整
□ 异常处理合适
□ 日志记录规范
□ 业务逻辑考虑全面
□ 符合 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 提交规范生成提交信息。
```

### 案例3：修改现有文件规范

#### 修改现有代码时的注释更新

```
我需要修改现有的 login_core.service.ts 文件，进行以下优化：
- 清理未使用的导入 (EmailSendResult, crypto)
- 修复常量命名 (saltRounds -> SALT_ROUNDS)  
- 删除未使用的私有方法 (generateVerificationCode)

请帮我：
1. 在文件头注释中添加修改记录
2. 更新版本号 (1.0.0 -> 1.0.1)
3. 添加 @lastModified 标记
4. 确保修改记录格式符合规范
5. 只保留最近5次修改记录，保持注释简洁

修改记录格式要求：
- 日期格式：YYYY-MM-DD
- 修改类型：代码规范优化
- 描述要具体明确
- 最多保留5条记录
```

#### AI 生成的修改记录示例

```typescript
/**
 * 登录核心服务
 * 
 * 最近修改：
 * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
 * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
 * - 2025-01-07: 代码规范优化 - 删除未使用的私有方法(generateVerificationCode)
 * - 2025-01-07: 代码质量提升 - 确保完全符合项目命名规范和注释规范
 * 
 * @author moyin
 * @version 1.0.1
 * @since 2025-12-17
 * @lastModified 2025-01-07
 */
```

### 案例4：代码审查场景

#### 现有代码检查

```
这是我写的代码，请帮我检查是否符合项目规范：

[粘贴代码]

项目规范要求：
- 完整的三级注释
- 防御性编程
- 合适的异常处理
- 规范的命名
- 关键操作日志记录

请指出所有不符合规范的地方，并提供修改建议。
```

---

## ⚠️ 注意事项和限制

### AI 的局限性

1. **不能替代人工判断**
   - AI 可能不理解特定的业务逻辑
   - 复杂的架构决策仍需人工判断

2. **需要明确的指导**
   - 必须提供详细的规范要求
   - 模糊的需求会得到模糊的结果

3. **需要验证和测试**
   - AI 生成的代码必须经过测试
   - 不要盲目信任 AI 的输出

### 最佳实践建议

1. **始终提供项目上下文**
2. **使用具体的检查清单**
3. **迭代优化，不要一次性完成**
4. **结合人工审查**
5. **保持学习，理解规范背后的原理**

---

## 🚀 进阶技巧

### 1. 创建个人 AI 助手模板

将常用的提示词保存为模板，提高效率：

```
# 我的开发助手模板

## 项目上下文
我在开发 NestJS 像素游戏后端项目，规范要求：
[保存项目规范要点]

## 代码生成模板
请生成符合规范的代码，包括：
- 完整的三级注释
- 防御性编程
- 异常处理
- 日志记录
- 规范命名

## 代码修改模板
修改现有文件时，请：
- 在文件头注释添加修改记录
- 更新版本号（递增小版本号）
- 添加 @lastModified 标记
- 修改记录格式：YYYY-MM-DD: 修改类型 - 具体描述
- 只保留最近5次修改记录，保持注释简洁

## 代码检查模板  
请检查代码规范符合性：
[保存检查清单]
```

### 2. 建立代码片段库

让 AI 帮你生成常用的代码模板：

```
请帮我生成以下代码模板，符合项目规范：

1. Controller 类模板
2. Service 类模板  
3. 异常处理模板
4. 日志记录模板
5. 参数验证模板
6. 文件修改记录注释模板

每个模板都要包含完整的注释和最佳实践。
```

### 3. 自动化检查脚本

```
请帮我写一个脚本，自动检查代码是否符合命名规范：
- 检查文件名是否使用下划线
- 检查类名是否使用大驼峰
- 检查方法名是否使用小驼峰
- 生成检查报告
```

---

## 📞 获得帮助

如果在使用 AI 辅助开发过程中遇到问题：

1. **查看规范文档**：确保理解项目规范要求
2. **优化提示词**：提供更详细的上下文和需求
3. **寻求人工帮助**：复杂问题可以咨询有经验的开发者
4. **持续学习**：理解规范背后的原理，不只是机械执行

---

## 🎉 总结

使用 AI 辅助开发可以显著提高代码质量和开发效率，但关键是：

1. **提供清晰的上下文和规范要求**
2. **使用具体的检查清单**
3. **迭代优化，持续改进**
4. **结合人工判断，不盲目依赖**
5. **理解规范原理，而不只是执行**

记住：**AI 是你的助手，不是替代品。好的开发者会善用工具，但始终保持思考和判断能力。**

---

**🔥 开始使用 AI 辅助开发，让代码质量和效率双提升！**