whale-town-end/AI代码检查规范_简洁版.md

AI代码检查规范（简洁版）

执行原则

• 分步执行：每次只执行一个步骤，完成后等待用户确认
• 用户信息收集：开始前必须收集用户当前日期和名称
• 修改验证：每次修改后必须重新检查该步骤

检查步骤

步骤1：命名规范检查

• 文件/文件夹：snake_case（下划线分隔），严禁kebab-case
• 变量/函数：camelCase
• 类/接口：PascalCase
• 常量：SCREAMING_SNAKE_CASE
• 路由：kebab-case
• 文件夹优化：删除单文件文件夹，扁平化结构
• Core层命名：业务支撑模块用_core后缀，工具模块不用

文件夹结构检查要求

必须使用listDirectory工具详细检查每个文件夹的内容：

1. 使用listDirectory(path, depth=2)获取完整文件夹结构
2. 统计每个文件夹内的文件数量
3. 识别只有1个文件的文件夹（单文件文件夹）
4. 将单文件文件夹中的文件移动到上级目录
5. 更新所有相关的import路径引用

检查标准：

• 不超过3个文件的文件夹：必须扁平化处理
• 4个以上文件：通常保持独立文件夹
• 完整功能模块：即使文件较少也可以保持独立（需特殊说明）

常见错误：

• 只看文件夹名称，不检查内容
• 凭印象判断，不使用工具获取准确数据
• 遗漏3个文件以下文件夹的识别

步骤2：注释规范检查

• 文件头注释：功能描述、职责分离、修改记录、@author、@version、@since、@lastModified
• 类注释：职责、主要方法、使用场景
• 方法注释：业务逻辑步骤、@param、@returns、@throws、@example
• 修改记录：使用用户提供的日期和名称，格式"日期: 类型 - 内容 (修改者: 名称)"
• @author处理规范：
  • 保留原则：人名必须保留，不得随意修改
  • AI标识替换：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
  • 判断示例：@author kiro → 可替换，@author 张三 → 必须保留
• 版本号递增：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1
• 时间更新：每次修改必须更新@lastModified字段

步骤3：代码质量检查

• 清理未使用：导入、变量、方法
• 常量定义：使用SCREAMING_SNAKE_CASE
• 方法长度：建议不超过50行
• 代码重复：识别并消除重复代码

步骤4：架构分层检查

• Core层：专注技术实现，不含业务逻辑，业务支撑模块用_core后缀
• Business层：专注业务逻辑，不含技术实现细节
• 依赖关系：Core层不能导入Business层，Business层通过依赖注入使用Core层
• 职责分离：确保各层职责清晰，边界明确

步骤5：测试覆盖检查

• 测试文件存在性：每个Service必须有.spec.ts文件
• 方法覆盖：所有公共方法必须有测试
• 场景覆盖：正常、异常、边界情况
• 测试质量：真实有效的测试用例，不是空壳
• 集成测试：复杂Service需要.integration.spec.ts
• 测试执行：必须执行测试命令验证通过

步骤6：功能文档生成

• README结构：模块概述、对外接口、内部依赖、核心特性、潜在风险
• 接口描述：每个公共方法一句话功能说明
• 依赖分析：列出所有项目内部依赖及用途
• 特性识别：技术特性、功能特性、质量特性
• 风险评估：技术风险、业务风险、运维风险、安全风险

关键规则

命名规范

// 文件命名
✅ user_service.ts, create_user_dto.ts
❌ user-service.ts, UserService.ts

// 变量命名  
✅ const userName = 'test';
❌ const UserName = 'test';

// 常量命名
✅ const MAX_RETRY_COUNT = 3;
❌ const maxRetryCount = 3;

注释规范

/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 功能点1
 * - 功能点2
 * 
 * 最近修改：
 * - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
 * 
 * @author [处理后的作者名称]
 * @version x.x.x
 * @since [创建日期]
 * @lastModified [用户日期]
 */

@author字段处理规则：

• 保留人名：如果@author是人名，必须保留不变
• 替换AI标识：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换
• 示例：
  • @author kiro → 可替换为 @author [用户名称]
  • @author 张三 → 必须保留为 @author 张三

架构分层

// Core层 - 技术实现
@Injectable()
export class RedisService {
  async set(key: string, value: any): Promise<void> {
    // 专注技术实现
  }
}

// Business层 - 业务逻辑
@Injectable() 
export class UserBusinessService {
  constructor(private readonly userCoreService: UserCoreService) {}
  
  async registerUser(data: RegisterDto): Promise<User> {
    // 业务逻辑：验证、调用Core层、返回结果
  }
}

测试覆盖

describe('UserService', () => {
  describe('createUser', () => {
    it('should create user successfully', () => {}); // 正常情况
    it('should throw error when email exists', () => {}); // 异常情况  
    it('should handle empty name', () => {}); // 边界情况
  });
});

执行模板

每步完成后使用此模板报告：

## 步骤X：[步骤名称]检查报告

### 🔍 检查结果
[发现的问题列表]

### 🛠️ 修正方案  
[具体修正建议]

### ✅ 完成状态
- 检查项1 ✓/✗
- 检查项2 ✓/✗

**请确认修正方案，确认后进行下一步骤**

修改验证流程

修改后必须：

1. 重新执行该步骤检查
2. 提供验证报告
3. 确认问题是否解决
4. 等待用户确认

强制要求

• 用户信息：开始前必须收集用户日期和名称
• 分步执行：严禁一次执行多步骤
• 等待确认：每步完成后必须等待用户确认
• 修改验证：修改后必须重新检查验证
• 测试执行：步骤5必须执行实际测试命令
• 日期使用：所有日期字段使用用户提供的真实日期
• 作者字段保护：@author字段中的人名不得修改，只有AI标识才可替换
• 修改记录强制：每次修改文件必须添加修改记录和更新@lastModified