在 AI 辅助编码日益普及的今天，许多开发团队都面临着相似的困境：工具用上了，但生成流程混乱无序；代码产出速度是快了，质量却难以保证；AI 的输出像一匹脱缰野马，常常偏离预期。问题的核心往往不在 AI 工具本身，而在于我们缺少一套能将“软件工程范式”与“标准化规范”紧密结合的约束体系。
本文将聚焦 Claude Code（轻量级 AI 编码工具）与 Spec-Kit（接口规范管理工具）这套轻量化工具链，通过落地 OOA/OOD/OOP 面向对象规范及测试规范，构建一套从需求分析、设计、编码到测试确认的全流程可控 AI 编码范式。无需部署复杂平台，仅需两款工具和几个规范文件，即可在实际项目中直接复用，让 AI 生成的代码从一开始就符合团队标准。
核心理念：AI 编码不是替代开发，而是规范落地
AI 编码的终极价值，在于将抽象的软件工程规范固化为工具可执行的规则，从而将开发者从重复性的编码劳动中解放出来，使其能更专注于核心业务逻辑的创新。本文所探讨的范式，严格遵循以下两大核心原则：
- 流程可控：严格遵循“需求分析→确认→设计→确认→编码→确认→测试→确认”的分步流水线。每一步都需要人工校验与确认，确保 AI 的输出始终在预期轨道上，避免“一次性生成，后期大改”的窘境。
- 规范先行：将 OOA（面向对象分析）、OOD（面向对象设计）、OOP（面向对象编程）及测试规范，固化为 AI 可识别、可执行的指令模板。让 AI 生成的代码天生就符合团队架构标准，极大减少后期重构与调整的成本。
- 轻量化落地：不依赖复杂笨重的专用平台，仅使用 Claude Code（负责 AI 编码）和 Spec-Kit（负责接口标准化）两款轻量工具，显著降低团队的接入与学习门槛。
工具链准备：2 个核心工具的定位与配置
工具链分工
| 工具 |
核心定位 |
核心价值 |
| Spec-Kit |
接口规范管理工具（CLI + YAML 配置） |
定义接口入参/出参/请求方式/校验规则，统一前后端协作标准 |
| Claude Code |
轻量 AI 编码 CLI 工具 |
快速调用大模型（支持 Claude、GLM-4 等）生成代码，支持通过精准指令进行约束 |
基础配置（快速上手，5 分钟完成）
1. 安装工具（以 Windows 环境为例）
# 1. 安装 Python（版本 ≥ 3.8，Claude Code 依赖）
# 官网下载：https://www.python.org/
# 2. 安装 Claude Code（支持切换多种模型）
pip install claude-code
# 3. 安装 Node.js（版本 ≥ 18，Spec-Kit 依赖）
# 官网下载：https://nodejs.org/
# 4. 全局安装 Spec-Kit
npm install -g specify-cli
2. 核心配置文件准备
所有的编码规范和接口标准将集中在以下两个文件中，它们是确保 AI 输出标准化的“宪法”：
AI-CODING-SPEC.md（编码规范文件，核心）：存放 OOA/OOD/OOP/测试等全部规范，作为 Claude Code 生成代码时必须遵循的指令模板。team-api.spec.yaml（Spec-Kit 接口规范文件）：定义业务接口的详细标准，确保 AI 生成的代码与前后端约定完全一致。
关键前提：定义可落地的 AI 编码规范
规范是约束 AI 编码的“紧箍咒”。我们需要将抽象的面向对象设计原则，转化为 Claude Code 能够精准识别的具体指令，避免使用模糊描述。以下是针对 Java/Spring Boot 项目的核心规范模板，你可以直接复制到项目根目录的 AI-CODING-SPEC.md 文件中使用。
# AI 编码规范：OOA/OOD/OOP + 测试规范（test-cloud 项目专用）
## 项目基础信息
- 技术栈：Java 17 + SpringBoot 3.2 + MySQL 8.0 + MyBatis-Plus 3.5
- 包路径：com.test.cloud
- 编码范式：面向对象编程（OOP），遵循 SOLID 原则，采用「OOA→OOD→OOP→测试」流程
# 1. OOA（面向对象分析）规范【强制遵守】
## 1.1 分析范围（必须覆盖）
- 业务实体：提取核心实体，严格区分 4 类对象（禁止混用）：
✅ PO（持久化对象）：与数据库表一一映射，仅含字段+getter/setter；
✅ DTO（数据传输对象）：接口入参/出参，仅含传输字段+校验规则；
✅ VO（视图对象）：返回给前端的脱敏数据，隐藏敏感字段；
✅ BO（业务对象）：封装核心业务逻辑，仅在 Service 层使用；
- 实体属性：明确字段类型、是否必填、业务约束（如手机号 11 位）；
- 实体关系：1:1/1:N/N:M/继承/组合，标注关联字段；
- 核心业务行为：每个实体的核心方法，含入参/出参/业务规则。
## 1.2 输出格式（固定，不可修改）
业务实体清单：
实体名（类型：PO/DTO/VO/BO）：属性 1（类型，是否必填，约束）、属性 2（类型，是否必填，约束）
实体关系：
实体 A 与 实体 B：关系类型（1:1/1:N/N:M / 继承 / 组合）+ 关联字段（如 user_id）
核心业务行为：
实体名：方法名 (入参类型)：方法描述 + 业务规则（如 “校验手机号格式为 11 位”）
UML 类图文本描述：
实体名 {
私有属性 1: 类型
私有属性 2: 类型
公有方法 1 (入参类型): 返回值类型
公有方法 2 (入参类型): 返回值类型
}
# 2. OOD（面向对象设计）规范【强制遵守】
## 2.1 SOLID 原则落地规则（可直接作为指令）
### 2.1.1 单一职责原则
- 一个类仅负责一个业务模块（如 UserController 仅处理用户接口，不包含订单逻辑）；
- 一个方法仅做一件事（如 login() 仅处理登录，不包含注册+登录）；
- 禁止“万能类”（如 CommonService 包含用户/订单/商品所有逻辑）。
### 2.1.2 开闭原则
- 新增功能必须通过「扩展类」实现，禁止修改原有稳定代码；
- 示例：新增“验证码登录”，需新增 CodeLoginStrategy 类，而非修改原 PasswordLoginStrategy。
### 2.1.3 依赖倒置原则
- 高层模块（Service）依赖「接口/抽象类」，不依赖具体实现类；
- 禁止“硬依赖”（如在 Service 中 new UserMapperImpl()）；
- 示例：UserService 依赖 UserMapper 接口，而非 UserMapperImpl 实现类。
## 2.2 分层目录结构（固定，必须按此路径生成代码）
src/main/java/com/test.cloud/
├── controller/ # 接口层：仅接收请求 / 参数校验 / 调用 Service / 返回响应，无业务逻辑
├── service/ # 业务层：接口（IUserService）+ 实现类（UserServiceImpl），封装核心逻辑
├── mapper/ # 数据层：仅数据库 CRUD，继承 BaseMapper，无业务逻辑
├── entity/ # 实体层（按类型拆分）：
│ ├── po/ # 数据库映射实体（UserPO）
│ ├── dto/ # 接口入参（UserLoginDTO）
│ ├── vo/ # 接口出参（UserVO）
│ └── bo/ # 业务对象（UserBO）
├── exception/ # 自定义异常（UserException）+ 全局处理器（GlobalExceptionHandler）
├── constant/ # 常量类（UserConstant），禁止硬编码
└── strategy/ # 设计模式实现（如登录策略 LoginStrategy）
## 2.3 设计方案输出格式
- 类结构设计：包路径 + 类名 + 类型（Controller/Service/PO 等）+ 核心方法（含入参 / 出参）
- 设计模式选型：模式名 + 使用场景 + 符合的 SOLID 原则（如策略模式 + 登录逻辑 + 开闭原则）
- 分层职责：明确每层的工作边界（如 Controller 不写业务逻辑）
- 接口关联：关联 `team-api.spec.yaml` 中的接口定义（如 UserLoginDTO 对应 /api/user/login 入参）
# 3. OOP（面向对象编程）规范【强制遵守】
## 3.1 核心原则
- 封装：所有实体类属性必须私有化（private），仅通过 getter/setter 访问；
- 继承：仅「is-a」关系使用（如 AdminUser is-a User），继承层级不超过 2 层；
- 多态：必须通过「接口/抽象类」实现（如 LoginStrategy 接口+多实现类），禁止用 if-else 替代多态。
## 3.2 编码细节规范
### 3.2.1 命名规范
- 类名：大驼峰（UserController、UserPO）；
- 方法/变量名：小驼峰（getUserById、userName）；
- 常量：全大写+下划线（USER_STATUS_ENABLED、VERIFY_CODE_EXPIRE_TIME）；
- 包名：全小写（com.test.cloud.controller）；
- 接口名：以 I 开头（IUserService）或业务名结尾（LoginStrategy）。
### 3.2.2 注释规范
- 类注释：必须包含「类职责+作者+创建时间」；
示例：
/**
* 用户模块 Controller
* 职责：处理用户注册/登录/查询接口请求，不包含业务逻辑
* @author test-cloud-team
* @date 2026-03-05
*/
- 方法注释：必须包含「方法描述+入参+出参+异常」；
示例：
/**
* 用户登录接口
* @param loginDTO 登录入参（手机号+密码/验证码）
* @return ResponseVO 登录成功返回 JWT token，失败返回错误信息
* @throws UserException 手机号不存在/密码错误/验证码过期时抛出
*/
- 核心逻辑行注释：关键业务步骤必须加注释（如“密码 BCrypt 加密处理”“管理员权限校验”）。
### 3.2.3 异常处理规则
- 必须自定义业务异常（如 UserException extends RuntimeException），禁止直接抛出 Exception；
- 必须用全局异常处理器（GlobalExceptionHandler）统一捕获异常，返回统一响应格式；
- 异常信息必须明确（如“手机号已注册”，而非“参数错误”）。
# 4. 测试规范【强制遵守】
### 4.1 测试覆盖要求
- 每个核心方法必须包含 3 类用例：正常场景+异常场景+边界场景；
- 异常场景示例：密码错误、手机号已注册、验证码过期；
- 边界场景示例：手机号为空、密码长度 5 位（小于最小限制 6 位）。
### 4.2 测试代码规范
- 测试类命名：业务类名+Test（UserService→UserServiceTest）；
- 测试方法命名：test+方法名+场景（testLogin_Success、testLogin_Fail_PasswordWrong、testLogin_Boundary_PhoneEmpty）；
- 断言要求：每个测试方法必须包含断言（Assert），校验返回值/异常/数据状态；
- 输出目录：测试代码必须放在 `src/test/java/com/test.cloud/` 对应目录（如 Service 测试放在 service 目录）。
全流程实战：用户模块开发
下面，我们以 test-cloud 项目的用户模块为例，完整演示如何从规范到工具再到落地流程。整个过程将严格按“分步确认”模式推进，每一步只让 Claude Code 输出当前阶段的内容，人工确认无误后再进行下一步。
4.1 阶段 1：需求输入（结构化需求文件）
首先，我们需要一份结构清晰的需求文档。将其保存为 需求-用户模块.txt。
# 需求：test-cloud 用户模块 V1.0
1. 核心功能：
- 用户注册：手机号（11位）+ 密码（6-20位），校验手机号格式和密码长度，密码用 BCrypt 加密存储；
- 用户登录：支持「手机号+密码」「手机号+验证码」两种方式，登录成功返回 JWT token；
- 用户信息查询：仅本人或管理员可查询，手机号脱敏（前3后4位，如 138****1234）；
- 用户状态管理：管理员可禁用/启用用户，禁用后用户无法登录。
2. 非功能要求：
- 接口响应时间 < 100ms；
- 接口需加幂等性校验（防重复提交，如注册接口用手机号做幂等键）；
- 密码加密方式：BCrypt（带盐值）。
3. 异常场景：
- 手机号已注册、密码错误、验证码过期；
- 非管理员操作用户状态、禁用用户尝试登录；
- 输入参数不合法（手机号非11位、密码长度不足）。
4.2 阶段 2：OOA 需求分析（Claude Code 分析 → 人工确认）
1. 执行 AI 分析指令
# 进入项目根目录
cd D:\SRC\test-cloud
# 调用 Claude Code 执行 OOA 分析（指定规范文件+需求文件）
claude-code chat -q "请严格遵循当前目录「AI-CODING-SPEC.md」中的 OOA 规范，分析「需求-用户模块.txt」文件，输出完整的 OOA 分析结果。要求：1. 严格按规范中的固定格式输出；2. 区分 PO/DTO/VO/BO 四类对象；3. 明确实体关系和业务规则；4. 不涉及任何设计或编码内容，仅输出 OOA 分析结果"
2. Claude Code 输出示例（符合规范格式）
### OOA 分析结果
1. 业务实体清单：
- UserPO（PO）：id(Long，主键，必填)、phone(String，必填，约束：11位手机号)、password(String，必填，约束：BCrypt加密后存储)、status(Integer，必填，默认1，约束：1=启用，0=禁用)、role(String，必填，默认common，约束：common=普通用户，admin=管理员)、createTime(LocalDateTime，必填，默认当前时间)
- UserLoginDTO（DTO）：phone(String，必填，约束：11位手机号)、password(String，可选，约束：6-20位，与验证码二选一)、code(String，可选，约束：6位数字，与密码二选一)
- UserVO（VO）：id(Long，非必填)、phone(String，非必填，约束：脱敏显示前3后4位)、status(Integer，非必填)、role(String，非必填)、token(String，非必填，登录成功返回)
- UserBO（BO）：loginStrategy(LoginStrategy，必填，约束：封装登录业务逻辑)、userMapper(UserMapper，必填，约束：操作数据库)
2. 实体关系：
- UserPO 与 UserLoginDTO：1:1 关系，关联字段 phone（UserLoginDTO 的 phone 对应 UserPO 的 phone）；
- UserBO 与 LoginStrategy：组合关系（UserBO 包含 LoginStrategy，LoginStrategy 无法独立存在）；
- UserBO 与 UserPO：1:1 关系，UserBO 依赖 UserPO 封装业务数据。
3. 核心业务行为：
- UserBO.register(UserLoginDTO)：用户注册，业务规则：校验手机号格式+密码长度，手机号未注册则加密密码并保存；
- UserBO.login(UserLoginDTO)：用户登录，业务规则：支持密码/验证码两种方式，启用状态的用户才可登录，返回 JWT token；
- UserBO.getUserInfo(Long userId, String currentRole)：查询用户信息，业务规则：本人或管理员可查询，手机号脱敏；
- UserBO.updateStatus(Long userId, Integer status, String currentRole)：修改用户状态，业务规则：仅管理员可操作，修改后更新 UserPO 状态。
4. UML 类图文本描述：
UserPO {
- id: Long
- phone: String
- password: String
- status: Integer
- role: String
- createTime: LocalDateTime
+ getId(): Long
+ setPhone(String phone): void
+ getStatus(): Integer
+ setStatus(Integer status): void
}
UserBO {
- loginStrategy: LoginStrategy
- userMapper: UserMapper
+ register(loginDTO: UserLoginDTO): Boolean
+ login(loginDTO: UserLoginDTO): String
+ getUserInfo(userId: Long, currentRole: String): UserVO
+ updateStatus(userId: Long, status: Integer, currentRole: String): Boolean
}
UserLoginDTO {
- phone: String
- password: String
- code: String
+ getPhone(): String
+ getPassword(): String
+ getCode(): String
}
3. 人工确认与修正
- 核对要点：实体是否完整覆盖四类对象？属性约束是否符合需求（如手机号11位）？业务行为是否覆盖所有功能？实体关系是否合理？
- 修正指令示例（补充验证码有效期）：
claude-code chat -q “基于之前的 OOA 分析结果，补充以下修正：1. 在 UserLoginDTO 的 code 属性约束中添加「验证码有效期 5 分钟」；2. 在 UserBO.login 方法的业务规则中添加「验证码过期则抛出异常」；3. 保持输出格式与之前一致，仅修改指定部分”
4.3 阶段 3：OOD 架构设计（Claude Code 设计 → 人工确认）
1. 执行 AI 设计指令（基于确认后的 OOA 结果）
claude-code chat -q “基于我已确认的用户模块 OOA 分析结果，严格遵循当前目录「AI-CODING-SPEC.md」中的 OOD 规范，输出完整的 OOD 设计方案。要求：1. 严格按规范中的固定格式输出；2. 登录逻辑使用策略模式（符合开闭原则）；3. 明确每个类的包路径和核心方法；4. 关联 team-api.spec.yaml 中的接口定义；5. 不涉及任何编码内容，仅输出设计方案”
2. Claude Code 输出示例（符合分层规范）
### OOD 设计方案
1. 类结构设计：
- com.test.cloud.entity.po.UserPO（PO）：id(Long)、phone(String)、password(String)、status(Integer)、role(String)、createTime(LocalDateTime)，核心方法：getter/setter
- com.test.cloud.entity.dto.UserLoginDTO（DTO）：phone(String)、password(String)、code(String)，核心方法：getter/setter，添加参数校验注解（@NotBlank、@Pattern、@Length）
- com.test.cloud.entity.vo.UserVO（VO）：id(Long)、phone(String)、status(Integer)、role(String)、token(String)，核心方法：getter/setter
- com.test.cloud.entity.bo.UserBO（BO）：loginStrategy(LoginStrategy)、userMapper(UserMapper)，核心方法：register(UserLoginDTO)、login(UserLoginDTO)、getUserInfo(Long, String)、updateStatus(Long, Integer, String)
- com.test.cloud.controller.UserController（Controller）：核心方法：register(@Valid UserLoginDTO)→ResponseVO、login(@Valid UserLoginDTO)→ResponseVO、getUserInfo(Long)→ResponseVO、updateStatus(Long, Integer)→ResponseVO
- com.test.cloud.service.IUserService（Service 接口）：核心方法：register(UserLoginDTO)→Boolean、login(UserLoginDTO)→String、getUserInfo(Long, String)→UserVO、updateStatus(Long, Integer, String)→Boolean
- com.test.cloud.service.impl.UserServiceImpl（Service 实现）：实现 IUserService 所有方法，依赖 UserBO 和 UserMapper
- com.test.cloud.strategy.LoginStrategy（接口）：核心方法：login(UserLoginDTO, UserPO)→String
- com.test.cloud.strategy.impl.PasswordLoginStrategy（实现类）：实现 LoginStrategy，处理密码登录逻辑
- com.test.cloud.strategy.impl.CodeLoginStrategy（实现类）：实现 LoginStrategy，处理验证码登录逻辑
- com.test.cloud.exception.UserException（自定义异常）：继承 RuntimeException，包含错误信息和错误码
- com.test.cloud.exception.GlobalExceptionHandler（全局异常处理器）：捕获 UserException 和参数校验异常，返回统一响应
- com.test.cloud.constant.UserConstant（常量类）：USER_STATUS_ENABLED(1)、USER_STATUS_DISABLED(0)、VERIFY_CODE_EXPIRE_TIME(300)（5分钟）
- com.test.cloud.annotation.Idempotent（自定义注解）：用于接口幂等性校验，含幂等键字段（如 phone）
2. 设计模式选型：
- 策略模式：登录逻辑（密码/验证码登录）→ 原因：符合开闭原则，新增登录方式（如第三方登录）仅需新增 Strategy 实现类，无需修改原有代码
3. 分层职责：
- Controller：接收 HTTP 请求，用 @Valid 校验入参，调用 Service 方法，返回统一 ResponseVO，不包含任何业务逻辑；
- Service：封装业务逻辑，调用 BO 处理核心流程，依赖 Mapper 操作数据库，不直接接收 HTTP 请求；
- BO：封装复杂业务逻辑（如登录策略选择），解耦 Service 与具体实现；
- Mapper：仅执行数据库 CRUD 操作，无业务逻辑，继承 MyBatis-Plus BaseMapper；
- Strategy：封装特定场景逻辑（如不同登录方式），通过接口实现多态。
4. 接口关联：
- UserController.register 关联 /api/user/register 接口（POST 方法），入参为 UserLoginDTO；
- UserController.login 关联 /api/user/login 接口（POST 方法），入参为 UserLoginDTO；
- UserController.getUserInfo 关联 /api/user/info/{userId} 接口（GET 方法），入参为 userId，出参为 UserVO；
- UserController.updateStatus 关联 /api/user/status 接口（PUT 方法），入参为 userId+status；
- 所有接口的响应格式统一为 ResponseVO（code: 状态码，msg: 信息，data: 数据）。
3. 人工确认与修正
- 核对要点：分层结构是否符合规范？包路径是否正确？设计模式应用是否合理？类职责是否清晰（Controller是否包含业务逻辑）？接口关联是否准确？
- 修正指令示例（明确幂等性注解）：
claude-code chat -q “基于之前的 OOD 设计方案，补充以下修正：1. 在 UserController 的 register 方法上添加 @Idempotent 幂等性注解（幂等键为 phone）；2. 在类结构设计中补充 com.test.cloud.annotation.Idempotent 注解类（自定义注解）；3. 保持其他内容不变”
4.4 阶段 4：Spec-Kit 接口规范定义（前后端同步）
基于 OOD 阶段确定的接口定义，我们使用 Spec-Kit 生成标准化的接口文档（YAML）。这确保了后续 AI 生成的代码能与前端、测试的接口约定完全一致，从源头避免对接矛盾。
1. 初始化 Spec-Kit 并创建接口规范文件
# 初始化 Spec-Kit（在项目根目录执行）
specify init
# 创建接口规范文件（team-api.spec.yaml）
specify create team-api.spec.yaml
2. 编辑接口规范文件（team-api.spec.yaml）
openapi: 3.0.0
info:
title: test-cloud 用户模块接口文档
description: 包含用户注册、登录、信息查询、状态管理接口，遵循 RESTful 规范
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/api/user/register:
post:
summary: 用户注册接口
description: 手机号+密码注册，校验手机号格式和密码长度，手机号唯一，密码 BCrypt 加密
requestBody:
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/UserLoginDTO’
responses:
‘200’:
description: 注册成功
content:
application/json:
schema:
$ref: ‘#/components/schemas/ResponseVO’
‘400’:
description: 参数错误（手机号格式错误/密码长度不足）
‘409’:
description: 手机号已注册
/api/user/login:
post:
summary: 用户登录接口
description: 支持手机号+密码/手机号+验证码两种方式，返回 JWT token
requestBody:
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/UserLoginDTO’
responses:
‘200’:
description: 登录成功
content:
application/json:
schema:
$ref: ‘#/components/schemas/ResponseVO’
‘400’:
description: 参数错误（手机号为空/验证码格式错误）
‘401’:
description: 认证失败（手机号不存在/密码错误/验证码过期/用户已禁用）
/api/user/info/{userId}:
get:
summary: 查询用户信息
description: 仅用户本人或管理员可查询，返回脱敏后的用户信息
parameters:
- name: userId
in: path
required: true
schema:
type: integer
responses:
‘200’:
description: 查询成功
content:
application/json:
schema:
$ref: ‘#/components/schemas/ResponseVO’
‘403’:
description: 无权限访问
‘404’:
description: 用户不存在
/api/user/status:
put:
summary: 修改用户状态
description: 仅管理员可操作，启用或禁用用户
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userId:
type: integer
status:
type: integer
enum: [0, 1]
required:
- userId
- status
responses:
‘200’:
description: 修改成功
content:
application/json:
schema:
$ref: ‘#/components/schemas/ResponseVO’
‘403’:
description: 非管理员无权操作
components:
schemas:
UserLoginDTO:
type: object
properties:
phone:
type: string
pattern: ‘^1[3-9]\d{9}$’
description: 11位手机号
password:
type: string
minLength: 6
maxLength: 20
description: 密码（6-20位）
code:
type: string
pattern: ‘^\d{6}$’
description: 6位数字验证码
required:
- phone
ResponseVO:
type: object
properties:
code:
type: integer
description: 状态码 (200=成功)
msg:
type: string
description: 提示信息
data:
type: object
description: 响应数据
3. 生成接口文档（可选，便于前后端共享）
# 用 Spec-Kit 生成 HTML 格式的接口文档（便于前后端查看）
specify generate docs --format html --output ./api-docs
4.5 阶段 5：OOP 编码实现（Claude Code 编码 → 人工确认）
1. 执行 AI 编码指令（结合 OOD 设计 + Spec-Kit 规范）
claude-code chat -q “基于我已确认的用户模块 OOD 设计方案和 team-api.spec.yaml 接口规范，严格遵循当前目录「AI-CODING-SPEC.md」中的 OOP 规范，生成以下代码：1. Controller（UserController）；2. Service 接口+实现（IUserService、UserServiceImpl）；3. Entity（PO/DTO/VO/BO）；4. Strategy 接口+实现（LoginStrategy、PasswordLoginStrategy、CodeLoginStrategy）；5. 自定义异常（UserException）+ 全局处理器（GlobalExceptionHandler）；6. 常量类（UserConstant）；7. 自定义幂等性注解（Idempotent）。要求：1. 代码输出到规范指定的包路径；2. 实体类添加参数校验注解；3. 方法添加完整注释；4. 禁止硬编码，使用常量类；5. 严格遵循 OOP 规范（封装/继承/多态）；6. 不生成测试代码，仅生成业务代码”
2. Claude Code 生成代码示例（核心文件片段）
```java
package com.test.cloud.entity.dto;
import jakarta.validation.constraints.Length;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;
import lombok.Data;
/**
* 用户登录/注册入参 DTO
* 关联接口：/api/user/login、/api/user/register
* @author test-cloud-team
* @date 2026-03-05
*/
@Data
public class UserLoginDTO {
/**
* 手机号（11位）
*/
@NotBlank(message = “手机号不能为空”)
@Pattern(regexp = “^1[3-9]\\d{9}$”, message = “手机号格式错误”)
private String phone;
/**
* 密码（6-20位，与验证码二选一）
*/
@Length(min = 6, max = 20, message = “密码长度必须为6-20位”)
private String password;
/**
* 验证码（6位数字，与密码二选一，有效期5分钟）
*/
@Length(min = 6, max = 6, message = “验证码必须为6位数字”)
private String code;
}
```
3. 人工确认代码
- 核对要点：
- ✅ 包路径是否符合规范（com.test.cloud.xxx）？
- ✅ 编码规范是否遵守（命名、注释、封装）？
- ✅ 核心逻辑是否符合需求（密码加密、权限校验、脱敏）？
- ✅ 接口是否与 Spec-Kit 规范一致（入参 / 出参）？
- ✅ 设计模式是否正确实现（策略模式无 if-else）？
- 修正指令示例（补充日志或修复逻辑）：
claude-code chat -q “修正 UserServiceImpl 的 getUserInfo 方法：1. 在 desensitizePhone 方法中添加日志 log.info(‘手机号脱敏，原始手机号：{}，脱敏后：{}’, phone, desensitizedPhone)；2. 修复 getCurrentLoginUserId 方法的返回值，改为从 JWT token 解析（提示：使用 JwtUtil 工具类，JwtUtil.getUserId(request.getHeader(‘Authorization’)))”
4.6 阶段 6：测试用例生成（Claude Code 生成 → 人工确认 → 执行测试）
1. 执行 AI 生成测试指令
claude-code chat -q “基于我已确认的用户模块业务代码，严格遵循当前目录「AI-CODING-SPEC.md」中的测试规范，生成以下代码的单元测试：1. UserServiceImpl；2. PasswordLoginStrategy；3. CodeLoginStrategy。要求：1. 测试代码输出到 `src/test/java/com.test.cloud/` 对应目录；2. 每个核心方法包含正常+异常+边界 3 个用例；3. 测试方法命名符合规范（test+方法名+场景）；4. 每个用例包含断言校验；5. 使用 Mockito 模拟依赖（如 UserMapper、BCryptPasswordEncoder）”
2. Claude Code 生成测试示例（UserServiceTest.java 片段）
```java
package com.test.cloud.service;
import com.test.cloud.entity.dto.UserLoginDTO;
import com.test.cloud.entity.po.UserPO;
import com.test.cloud.exception.UserException;
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.*;
/**
* UserService 单元测试类
* 覆盖正常/异常/边界场景，使用 Mockito 模拟依赖
* @author test-cloud-team
* @date 2026-03-05
*/
@ExtendWith(MockitoExtension.class)
public class UserServiceTest {
@Mock
private UserMapper userMapper;
@Mock
private BCryptPasswordEncoder passwordEncoder;
@InjectMocks
private UserServiceImpl userService;
private UserLoginDTO validLoginDTO;
private UserPO existUserPO;
/**
* 测试前初始化测试数据
*/
@BeforeEach
void setUp() {
// 初始化合法登录入参
validLoginDTO = new UserLoginDTO();
validLoginDTO.setPhone(“13800138000”);
validLoginDTO.setPassword(“123456”);
// 初始化已存在的用户信息
existUserPO = new UserPO();
existUserPO.setId(10001L);
existUserPO.setPhone(“13800138000”);
existUserPO.setPassword(“$2a$10$EixZaYbB.rK4flxWx8H9aO7eR6Q5eR6Q5eR6Q5eR6Q5eR6Q5eR6Q”); // 加密后的 123456
existUserPO.setStatus(UserConstant.USER_STATUS_ENABLED);
existUserPO.setRole(UserConstant.USER_ROLE_COMMON);
existUserPO.setCreateTime(LocalDateTime.now());
}
/**
* 测试注册成功场景
* 预期结果：返回 true，UserMapper.insert 被调用一次
*/
@Test
void testRegister_Success() {
// 模拟：手机号未注册（查询返回 null）
when(userMapper.selectOne(“phone”, validLoginDTO.getPhone())).thenReturn(null);
// 模拟：密码加密返回固定值
when(passwordEncoder.encode(validLoginDTO.getPassword())).thenReturn(“encryptedPassword”);
// 模拟：插入成功返回 1
when(userMapper.insert(any(UserPO.class))).thenReturn(1);
// 执行测试
Boolean result = userService.register(validLoginDTO);
// 断言结果
assertTrue(result);
// 验证依赖方法被调用
verify(userMapper, times(1)).selectOne(“phone”, validLoginDTO.getPhone());
verify(passwordEncoder, times(1)).encode(validLoginDTO.getPassword());
verify(userMapper, times(1)).insert(any(UserPO.class));
}
/**
* 测试注册失败-手机号已注册场景
* 预期结果：抛出 UserException，提示“手机号已注册”
*/
@Test
void testRegister_Fail_PhoneExist() {
// 模拟：手机号已注册（查询返回 existUserPO）
when(userMapper.selectOne(“phone”, validLoginDTO.getPhone())).thenReturn(existUserPO);
// 执行测试并断言异常
UserException exception = assertThrows(UserException.class, () -> {
userService.register(validLoginDTO);
});
// 断言异常信息
assertEquals(“手机号已注册”, exception.getMessage());
// 验证插入方法未被调用
verify(userMapper, never()).insert(any(UserPO.class));
}
}
```
3. 执行测试（验证代码正确性）
落地价值：AI 编码 + 规范范式的核心收益
5.1 效率提升：减少重复工作，聚焦核心逻辑
- 编码效率：AI 可自动生成约 80% 的重复性代码（如实体类、基础接口、测试用例骨架），开发者只需专注于剩下的 20% 核心业务逻辑（复杂校验、策略选择等）。
- 协作效率：通过 Spec-Kit 统一接口规范，前后端无需反复沟通联调，AI 生成的代码直接适配前端请求格式，这在构建复杂的 后端 & 架构 时尤为重要。
- 测试效率：AI 能按规范自动生成覆盖正常、异常、边界场景的测试用例，可节省约 60% 的手动编写测试的时间。
5.2 质量保障：规范约束，减少线上问题
- 一致性：所有代码都遵循同一套
AI-CODING-SPEC.md 规范（命名、注释、分层），彻底消除团队协作中的“编码风格冲突”。
- 可维护性：严格遵循 SOLID 原则和恰当的设计模式，代码解耦彻底。例如，后续新增“微信扫码登录”，只需新增一个 Strategy 实现类，符合 开闭原则，无需触碰任何原有稳定代码。
- 稳定性：自动生成的测试用例全面覆盖各种场景，能在编码阶段提前暴露业务逻辑漏洞（如密码长度校验缺失、权限控制漏洞），提升代码健壮性。
5.3 成本降低：轻量化落地，无额外负担
- 工具成本：Claude Code 与 Spec-Kit 均为开源/轻量级工具，无需购买或部署复杂的商业平台，5 分钟即可完成环境配置。
- 学习成本：规范文件 (
AI-CODING-SPEC.md) 本身即为最佳实践文档，新成员无需记忆复杂规则，参照执行即可快速融入标准化开发流程。
- 重构成本：AI 生成的代码天生符合工程规范，后期因风格不一致或设计缺陷导致的大规模重构率极低（可降至 5% 以内），与传统“生成后大改”的模式（重构率约 40%）形成鲜明对比。
总结
本文提出的“Claude Code + Spec-Kit + 标准化规范”AI 编码软件工程范式，其核心在于将抽象的软件工程原则转化为工具可识别的、可执行的具象规则。通过 流程可控、规范先行、轻量化落地 三大原则，直击 AI 编码“效率与质量难以兼得”的核心痛点。
该范式无需复杂的基础设施部署，可直接在当前 Java /Spring Boot 项目中复用。其理念也具有普适性，可适配 Python、Go 等其他技术栈，只需根据目标技术栈调整 AI-CODING-SPEC.md 文件中的技术栈描述和分层结构即可快速迁移。
通过实践这一范式，团队有望实现 AI 生成代码 80% 以上直接可用、单元测试覆盖率 90% 以上、后期因规范问题导致的重构率低于 5% 的目标。这标志着 AI 真正从“玩具”或“不确定的帮手”，转变为开发者手中稳定、可靠的“得力助手”，让 AI 的工作成果始终处于工程化的掌控之中。
希望这篇关于企业级 AI 编码工程化的落地实践，能为你和你的团队带来启发。探索更高效的开发方式，是每个技术团队永恒的课题，也欢迎你到 云栈社区 与更多开发者交流在 软件测试 及工程化实践中的心得。
发表于 2 小时前
|
查看: 4|
回复: 0
