当前位置：首页 > news >正文

AI 工作范式下的研发新范式：从需求到测试的全链路落地指南

news 2026/5/22 17:27:37

写在前面

最近一年，团队里几乎每个 Java 后端、前端、甚至产品经理，都在用 AI 编辑器写代码。Cursor、Qoder、Claude Code、Trae、Copilot……工具的迭代速度肉眼可见。

但用着用着大家发现一个尴尬的现实：工具升级了，研发流程没升级。

旧流程下产出的需求文档、技术方案、代码规范，大多是给人看的——含糊、跳跃、依赖默契、留有想象空间。这套文档喂给 AI 以后，AI 会很尽职地"自由发挥"——猜需求、猜命名、猜异常处理、猜分层。结果就是：表面上代码出得很快，回头审查时发现一堆"不符合项目惯例"的实现，返工成本比从头写还高。

所以这一两年我们团队（数环通 iPaaS 研发团队）做了一件事：把整个研发流程按 AI 友好的方式重新拆解一遍，从需求、设计、编码到测试，每一步都重新定义"输入"和"输出"。

这篇文章把这套实践写下来，包括我们踩过的坑和现在用得比较顺的模板。不讲虚的，全是可落地的东西。

欢迎大家评论区交流AI编程的经验和坑点~~

一、需求阶段：从"PRD 写给人看"到"PRD 写给 AI 看"

1.1 旧 PRD 喂给 AI 会发生什么

以前我们的 PRD 长这样：

“支持租户管理员在流程实例列表页对历史执行记录进行批量导出，导出格式可选 Excel 或 CSV。考虑到性能问题，建议异步处理。”

这段话给人看完全没问题，给 AI 写代码就会出问题：

"租户管理员"是哪种角色？普通成员能不能导出？是否需要做空间隔离校验？
"历史执行记录"是按时间过滤、按执行状态（成功 / 失败 / 已中断）过滤、还是用户自选实例 ID？时间窗口最大多少？
"批量"的上限是多少？1000 条还是 5 万条？
"异步处理"用什么实现——线程池？MQ？定时任务？
导出失败怎么提示？导出文件存哪里？保留多久？
用户重复点击怎么处理？

AI 默认会按"通用最佳实践"猜一套出来。但每个团队对"最佳实践"的定义都不一样——有的团队用 RocketMQ，有的用 Kafka；有的把临时文件放 OSS，有的存本地；有的用 Redis 做防重，有的用数据库唯一索引。猜对的概率随着项目复杂度递减。

1.2 AI 友好的需求结构

我们现在写需求强制按四段式结构：

[用户故事] 作为 <角色>，我希望 <动作>，以便 <价值>。 [前置条件] - 用户已登录且具备当前空间的"流程查看"权限 - 流程实例数据在 ipaas_flow_instance 表中 [验收标准 AC] 1. 当用户在流程实例列表选中 N 条记录点击导出时... 2. 当导出任务进入异步队列时，前端立即返回任务ID... 3. 当导出文件生成完成时，通过站内消息通知... 4. 当导出失败时，记录失败原因并通知... [反例 / Out of Scope] - 不支持跨租户 / 跨空间导出 - 不支持执行详情中的二进制附件导出 - 单次导出上限 5 万条，超过时返回错误码 FLOW_INSTANCE_EXPORT_LIMIT_EXCEEDED

这四段里反例和验收标准是最关键的。

反例直接告诉 AI：“这些场景你不需要考虑”。AI 收到反例后不会再扩展边界。

验收标准用"当…时…应该…"的格式表达，等价于一条条可执行的测试用例。这个结构给 AI 的提示是非常具体的——它知道每条 AC 对应一个测试用例，知道每个测试用例需要哪些断言。

1.3 项目级 Glossary：业务术语词典

iPaaS 这种平台型项目，业务术语特别多：流程、连接器、触发器、动作、租户、组织、空间、应用、API代理、数据流……同一个词在不同上下文里含义可能不一样。"流程"在编排域里指 Flow，在执行域里指 Execution，在监控域里指 FlowInstance。

我们建了一个docs/glossary.md，作为项目的术语词典：

## 流程（Flow） 编排域中的流程定义。包含触发器节点、动作节点、条件节点等。 对应数据库表：ipaas_flow 对应代码包：com.shuhuan.ipaas.flow.domain ## 流程实例（FlowInstance） 流程在某次具体触发时的运行实例。 对应数据库表：ipaas_flow_instance 对应代码包：com.shuhuan.ipaas.execution.domain 区别于 Flow：Flow 是定义（模板），FlowInstance 是运行实例

写需求时，所有业务术语必须使用 Glossary 里的标准词。AI 编辑器在生成代码前先读 Glossary，能精准对应到代码包和数据表，错位的概率大幅下降。

1.4 用例先行：把验收标准变成可执行测试

这是最有效的一招——写需求的时候就把测试用例写出来。

不是写在测试代码里，而是写在 PRD 里。每条 AC 后面跟一个具体的测试场景：

## AC-3: 单次导出超过 5 万条返回错误 测试场景： - Given: 当前租户下符合筛选条件的流程实例数为 60000 条 - When: 租户管理员调用导出接口，参数为"近 30 天全部失败实例" - Then: - HTTP 状态码 400 - 响应体 errorCode = "FLOW_INSTANCE_EXPORT_LIMIT_EXCEEDED" - 响应体 message = "单次导出最多 5 万条，请缩小筛选范围" - 不创建任何导出任务记录

这个测试场景就是 AI 后面要生成的单元测试的输入。"用例先行"的好处不止是给 AI 看——它强制需求方在需求阶段就把所有边界想清楚。很多模糊的需求（“性能要好”“异常要处理”）在写测试场景时就会暴露——你根本写不出 Given-When-Then，因为不知道边界在哪里。

二、技术方案阶段：上下文比方案本身更重要

2.1 项目自述文件：让 AI 一进来就懂项目

每个仓库根目录放一份给 AI 看的项目说明，命名根据使用的工具决定（CLAUDE.md / AGENTS.md / .cursor/rules / .qoder/rules）。这份文件是 AI 进入项目的"第一眼"。

我们的模板（精简版）：

# 项目简介 数环通 iPaaS 引擎核心模块。基于 Spring Boot 2.7 + MyBatis Plus + Nacos。 日均处理百万级流程执行，对稳定性要求高。 # 模块结构 - shuhuan-ipaas-api: 对外 API 层（控制器 + DTO） - shuhuan-ipaas-engine-core: 核心引擎（执行机、调度、快照） - shuhuan-ipaas-app-libs: 连接器实现（每个连接器独立 jar） # 关键技术约束 - JDK: 8（不能用 var、Records、新 switch 语法） - 序列化: Hessian2，不要换成 Java 原生 - 消息队列: RocketMQ，不要引入 Kafka - 缓存: Redis（单机模式），不要假设有集群 # 编码强制要求 - 任何外部 IO（HTTP/DB/Redis）必须有超时配置，禁止使用默认值 - 日志输出统一走 LogUtil，不要直接 logger.info - 异常按照 BizException + ErrorCode 体系抛出，不要 throw new RuntimeException # 禁止的事情 - 不要修改 ipaas-api 模块下的 .proto 和 IDL 文件 - 不要在 service 层直接拼 SQL - 不要新增 Lombok 之外的代码生成框架

这份文档解决了 AI 最常见的几类问题：用错语法（JDK 版本不匹配）、引入新依赖（团队不许）、改错文件（敏感目录）。

2.2 ADR 的复兴：让架构决策可追溯

ADR（Architecture Decision Record）这个概念十年前就有了，但用得不多。AI 时代它突然变得很重要——AI 不知道某个看似不合理的设计背后有什么历史决策，会自作主张改掉它。

举个例子：我们的某个核心服务用了一个看起来很怪的双层缓存（Redis + 本地 Caffeine）。AI 看到这种结构会很自然地建议"为什么不直接用 Redis？双层缓存增加复杂度"。但实际上这是因为某次大促时 Redis 被打爆，团队为此专门做了本地缓存兜底。

我们现在每个非显然的设计都写一份 ADR：

ADR-007: 引入本地缓存兜底 背景：2024 春节大促 Redis 集群被打爆，导致引擎降级 决策：在执行机的热点路径增加 Caffeine 本地缓存（5 秒 TTL） 权衡：增加内存占用 ~200MB，换取 Redis 故障下的可用性 影响范围：ExecutionRunner.getFlowDeployment() 不要改：除非有更好的兜底方案，不要移除本地缓存层

AI 编辑器在改这块代码前会读 ADR，知道"哦，这是有意为之的"，就不会随手改掉。

2.3 接口契约先行

技术方案设计阶段，先写接口，再写实现。具体到代码层就是：

DTO 类先定义清楚，包含字段名、类型、约束、示例值（写在 javadoc 里）
接口类（Controller、Service、Mapper）的签名先定义好
错误码先定义好（ErrorCode 枚举里加好）

把接口契约定义清楚后再让 AI 写实现，产出质量会高一个档次。原因很简单——AI 在生成实现时不需要再猜接口形状，可以专注于业务逻辑本身。

2.4 让 AI 生成"候选方案"而不是"最终方案"

这是一个使用习惯上的转变。

旧习惯：让 AI 给一个最佳方案，然后照着写。

新习惯：让 AI 给 2-3 个候选方案，列出每个方案的优缺点和适用场景，然后人来做决策，最后让 AI 按选定的方案生成代码。

为什么这样？因为 AI 给"最佳方案"时，倾向于给最通用、最四平八稳的方案，未必符合具体项目的约束。让它列出候选，人能从候选里挑出和项目约束最匹配的那个。

这个转变本质上是：把 AI 从"决策者"降级为"信息整理者"，把决策权留在人这边。

三、编码阶段：给 AI 立规矩

这是改造工作量最大的一章。AI 写代码的速度是人的几倍到十几倍，但如果没有规矩，产出的代码合规性问题会指数级放大。

3.1 项目级 Rules 的分层设计

我们的 Rules 分三层：

全局 Rules（团队共享） ↓ 项目 Rules（仓库根目录 .qoder/rules.md 或 .cursor/rules） ↓ 模块 Rules（特定模块下的 rules.md）

全局 Rules写跨项目通用的东西：注释语言、commit 格式、基础命名约定。

项目 Rules写当前仓库的硬约束：JDK 版本、依赖白名单、敏感目录、日志规范。

模块 Rules写特定模块的细节：比如连接器开发规范、引擎执行机的并发约束。

AI 编辑器读取 Rules 是有优先级的——模块 Rules 优先级最高，全局 Rules 优先级最低。这样组织的好处是不需要把所有规则塞进一个巨大的文件，而是按上下文加载。

3.2 几条最值得写进 Rules 的硬规则

写过几个项目后我们发现，下面这几条规则放进 Rules 收益最大：

命名规则

- 接口类不要加 I 前缀，直接用业务名（如 FlowService） - 实现类用 Impl 后缀（FlowServiceImpl） - DTO/VO/PO 后缀强制区分： - DTO 用于 Service 层 - VO 用于 Controller 返回前端 - PO 用于数据库映射 - 时间字段统一命名：xxxTime（不用 xxxDate） - 状态字段统一命名：xxxStatus（不用 xxxState）

分层规则

- Controller 不能直接调用 Mapper，必须经过 Service - Service 不能直接 new 其他 Service，用依赖注入 - Service 之间的调用允许，但需要在类注释里说明 - 不要在 Util 类里调用 Service - 不要在 Config 类里写业务逻辑

异常规则

- 业务异常统一抛 BizException，必须带 ErrorCode 枚举 - 不要 throw new RuntimeException("xxx") - 不要 catch (Exception e) 后吞掉，至少要记录日志或重新抛出 - 不要在 Controller 里写 try-catch（统一异常处理器接管）

日志规则

- 不要使用 logger.info("xxx" + variable)，用占位符 logger.info("xxx={}", variable) - 关键路径必须打印 traceId（已通过 MDC 注入） - 敏感信息（密码、token、手机号）禁止入日志，使用 LogDesensitizer 工具类 - error 日志必须打 stack trace（不要 logger.error(e.getMessage())）

事务规则

- @Transactional 必须明确指定 rollbackFor = Exception.class - 长事务（>5 秒）禁止使用 @Transactional，改用编程式事务 - 跨库操作不要用本地事务，使用平台提供的分布式事务方案 - 不要在事务方法内调用远程接口（HTTP/RPC）

这些规则看起来很基础，但是没有写进 Rules 之前，AI 写出的代码经常违反——特别是异常处理、日志格式、事务边界这几块。

3.3 反模式清单：明确告诉 AI 不要做什么

正向规则只能解决一部分问题，更多时候需要明确告诉 AI不要做什么。我们维护了一份"反模式清单"：

❌ 不要使用 fastjson 1.x，全部统一用 fastjson2 ❌ 不要用 SimpleDateFormat（线程不安全），用 DateTimeFormatter ❌ 不要用 ParallelStream 处理 IO 密集型任务 ❌ 不要在循环里调用数据库或 Redis（典型 N+1 问题） ❌ 不要直接捕获 Throwable，最大粒度到 Exception ❌ 不要使用 BeanUtils.copyProperties（性能差），用 MapStruct ❌ 不要在 @PostConstruct 里做耗时操作（>500ms） ❌ 不要新增 Spring AOP 切面（已有切面会冲突，需架构组评审） ❌ 不要使用 System.currentTimeMillis() 测时间，用 StopWatch

这份清单是动态维护的——每次代码评审发现 AI 反复犯的同类错误，就把它加到反模式里。

3.4 上下文管理：哪些文件先喂给 AI

AI 编辑器的上下文窗口是有限的，喂错文件比不喂还糟糕——它会按错的样板来写新代码。

我们总结的"上下文喂养"顺序：

1. 项目 Rules（必喂） 2. 当前需求文档（必喂） 3. Glossary 业务术语（按需） 4. 同类已有代码（关键） - 写 Controller？喂一个标杆 Controller - 写 Service？喂一个标杆 Service - 写测试？喂一个标杆测试 5. 当前要修改的文件本体 6. 直接被引用的依赖类（DTO、ErrorCode）

第 4 步是关键。AI 模仿能力极强，给它一个高质量的标杆，它写出来的代码 90% 符合项目风格。给它一个低质量的标杆（哪怕是项目里某个老旧模块），它会忠实复制那种坏味道。

我们给每个常见任务标注了"标杆文件"路径：

任务类型 标杆文件 ───────────────────────────────────────────────── 新增 Controller FlowController.java 新增 Service FlowServiceImpl.java 新增 Mapper FlowMapper.java 新增连接器 DingTalkConnector.java 新增定时任务 FlowInstanceCleanScheduler.java 新增 MQ 消费者 FlowResumeMessageListener.java

新人接手任务时直接照着标杆喂给 AI，比自己摸索快得多。

3.5 提交粒度与审查节奏

AI 写代码快，但 review 速度跟不上。我们的实践：

小步提交：每个 commit 控制在 200 行以内，方便 review
AI 标注：commit message 里标注 “AI-Assisted” 或 “Human-Written”，方便统计 AI 占比和事故归因
强制 self-review：开发者提 PR 前必须自己 review 一遍 AI 产出，特别是异常处理、边界条件、敏感操作三块
关键代码人工写：核心算法、安全相关、事务边界这三类代码不让 AI 写

最后一点很重要。AI 写"添砖加瓦"的代码很好，但写涉及钱、权限、数据一致性的代码必须人来写——AI 的"看起来对"和"真的对"差距很大，这种代码出问题的成本太高。

四、测试阶段：从"补测试"到"测试驱动 AI"

4.1 让 AI 先写测试，再写实现

旧习惯是：写完业务代码，让 AI 帮忙补测试。

新习惯反过来：先让 AI 根据 PRD 的验收标准生成测试代码，再让它根据测试生成实现。

为什么？因为测试是验收标准的代码化表达，写测试的过程是把需求理解透的过程。先写测试有几个好处：

测试是可执行的需求文档，AI 后续生成实现时有明确目标
边界条件在写测试时就暴露出来（“这个 case 要不要测？”）
实现写完直接跑测试就知道对不对，不用人工验证
测试和实现分两次 prompt 生成，注意力不会被实现细节带偏

具体流程：

步骤1: 把 PRD 的 AC 段落 + 标杆测试文件 喂给 AI 步骤2: AI 生成测试代码（先不要求通过） 步骤3: 人 review 测试代码，确认覆盖了所有 AC 步骤4: 把测试代码 + 标杆实现 + Rules 喂给 AI 步骤5: AI 生成实现代码 步骤6: 跑测试，反馈失败用例给 AI 修正

4.2 边界用例的自动扩展

AI 生成测试的另一个杀手锏是边界用例覆盖。我们让 AI 在生成主线测试后，再针对每个输入生成"边界变种"：

对于参数 instanceIds: List<Long>，请生成以下边界测试： - 空列表 - 只有一个元素 - 包含 null 元素 - 包含重复元素 - 超过最大限制（5 万 + 1） - 全部不存在的 ID - 部分不存在的 ID - 跨租户 ID（应被拒绝）

人手写测试时，“全部不存在”"跨租户"这种边界经常会漏。AI 不会觉得累，让它穷举一遍，覆盖率显著提升。

4.3 测试数据的生成与隔离

业务类项目的测试数据准备特别耗时。AI 在这块能帮上很大忙：

用对象 builder 模式构造测试数据（让 AI 一次生成 10 个变种）
让 AI 根据 schema 生成 mock 数据（带合理的字段分布）
用项目自带的 TestDataFactory，让 AI 调用现成方法

注意一点：测试数据不要用真实数据。即使是脱敏后的真实数据，也存在隐私和合规风险。让 AI 生成数据时，明确写在 prompt 里"使用合成数据，不要使用任何真实手机号、身份证、姓名"。

五、工程治理：让流程跑得久

5.1 代码评审的重心迁移

AI 时代的 PR review，重点不再是"代码写得对不对"——这部分 AI 自己就能跑测试验证。重点变成了：

业务理解对不对：AI 是否正确理解了 PRD 的意图，特别是隐含约束
边界处理是否完整：异常路径、超时、并发、空值
是否符合项目惯例：分层、命名、依赖方向
是否引入了不必要的复杂度：AI 有时会过度工程化，加一堆不需要的抽象

我们的 review checklist：

[业务正确性] □ 实现是否完整覆盖所有 AC □ 反例场景是否被正确处理 □ 是否引入了 PRD 之外的功能（过度发挥） [健壮性] □ 所有外部 IO 是否设了超时 □ 所有可能为空的对象是否做了空值检查 □ 异常处理是否符合规范 [一致性] □ 命名是否符合项目惯例 □ 分层是否正确（Controller→Service→Mapper） □ 是否引入了反模式清单中的写法 [简洁性] □ 是否有不必要的抽象（接口、工厂、策略模式） □ 是否有不必要的重复代码

5.2 知识沉淀的飞轮

AI 时代知识沉淀变得前所未有的重要。每次 review 发现的问题、每次踩到的坑、每次架构决策，都要沉淀成文档（Rules、ADR、反模式清单），让下次 AI 不再犯同样的错。

我们形成了一个飞轮：

开发任务 → AI 生成 → review 发现问题 ↑ ↓ ←── 更新 Rules ←─┘

这个飞轮转得越久，AI 在项目里产出的代码质量越高，因为 Rules 越来越精细，标杆代码越来越多。

5.3 安全与合规的硬边界

最后说一点底线问题。AI 编辑器使用过程中，以下东西严格禁止进入 prompt：

生产环境数据库连接信息
用户的真实数据（哪怕脱敏了）
密钥、token、签名 secret
客户的业务数据（流程执行明细、连接器配置中的认证信息）
内部代号未公开的产品名

这些信息一旦进 prompt，就有被记录、被泄露的风险。我们在团队里约定了一份"AI 输入禁止清单"，并通过 IDE 插件做关键词预检——发现 prompt 里包含禁止内容就拦截。

六、可落地清单：从今天开始能做的事

如果今天就要在团队里推行这套实践，按下面的顺序做最有效：

第 1 周（基础设施） □ 在仓库根目录建立项目级 Rules 文档 □ 整理项目 Glossary（业务术语词典） □ 选定 5-10 个标杆文件，建立"任务-标杆"对照表 □ 整理反模式清单（从最近 3 个月的代码 review 反馈中提炼） 第 2 周（流程改造） □ 修改 PRD 模板，强制四段式（用户故事+前置条件+AC+反例） □ 培训 PM 写"用例先行"的 AC □ 修改 PR 模板，加入 review checklist □ 启动每周一次的 Rules 更新会 第 3 周（开发实践） □ 推行"先测试后实现"的开发顺序 □ 推行"候选方案 + 人工决策"的方案设计模式 □ 启动每月一次的 ADR 复盘会 第 4 周（持续优化） □ 统计 AI 生成代码占比和事故归因 □ 收集开发者使用反馈，迭代 Rules □ 沉淀团队级 AI 使用最佳实践文档

不需要等到所有东西就位再启动——先把 Rules 和 PRD 模板做出来，其他的边走边补。

七、几个常见误区

误区 1：AI 是来替代程序员的

实际是来改造研发流程的每个环节。程序员的角色从"写代码"转向"定义规范、审查产出、做关键决策"。会用 AI 的程序员产出会高 3-5 倍，但角色责任更重——出错由你负责。

误区 2：所有代码都让 AI 写

核心算法、安全相关、跨服务事务、性能敏感的代码，依然要人写。AI 适合写"添砖加瓦"的工程代码，不适合写"一锤定音"的核心代码。

误区 3：AI 写了测试就万事大吉

AI 生成的测试覆盖率高，但深度未必够。它会覆盖各种参数变种，但未必能识别"业务上不可能出现的组合"和"业务上很危险的组合"。这两类用例还是要人来设计。

误区 4：Rules 写得越多越好

Rules 太多 AI 会忽略一部分（受上下文窗口限制）。关键规则要抓重点：JDK 版本、命名分层、异常日志、事务边界这几块是核心，其他的能简则简。

误区 5：迁移到新工具就有提升

工具只是放大器。流程不改，换什么工具都白搭。先把流程理顺，再选合适的工具。

八、常见问题（FAQ）

Q：项目历史包袱很重，老代码不符合规范，怎么让 AI 避免"对齐"老代码的坏味道？

A：在 Rules 里明确标注"以下目录是历史代码，仅供 reference 不要作为标杆"，同时维护一份"标杆文件清单"列出新代码应该参考哪些文件。AI 在生成代码时会优先模仿明确指定的标杆，而不是随便扫到的同类文件。

Q：怎么衡量这套流程的收益？

A：建议同时跟踪四个指标：交付吞吐（PR 数/人月）、缺陷率（线上 bug/千行代码）、返工率（同一需求的修改次数）、code review 通过率（一次通过的 PR 占比）。AI 流程改造做得好的团队，吞吐会涨 2-3 倍，缺陷率持平或下降，返工率明显下降。

Q：小团队没有专门的 PM 和架构师，谁来维护 Rules、PRD 模板、ADR？

A：让一个资深开发兼任。前期投入大概是每周 4-8 小时，跑顺之后每周 1-2 小时维护就够了。这部分时间投入比换来的产出提升划算得多。

Q：用 Cursor、Qoder、Claude Code 这些工具的 Rules 文件能通用吗？

A：核心内容（命名规范、分层规则、反模式清单）通用，但不同工具的 Rules 文件路径和优先级机制略有不同。建议把核心 Rules 放在docs/rules.md，然后在每个工具的专用配置文件中通过 include 或复制的方式引用。这样切换工具时不用全部重写。

Q：AI 生成的代码出了线上事故，责任算谁的？

A：算提交代码的人。AI 是工具，最终的代码质量由提交者负责。这也是为什么前面强调要做 self-review 和强制 PR review——不能因为是 AI 写的就放低审查标准。团队里要明确这个责任边界，避免"反正是 AI 写的"心态。

Q：用 AI 写代码会不会让新人成长变慢？

A：用法不对会，用法对了反而成长更快。错误用法是"提需求 → AI 写 → 直接提交"，这种模式下新人确实学不到东西。正确用法是"AI 写 → 自己看懂每一行 → 能解释清楚为什么这么写 → 提交"——本质上 AI 是高级版的样例代码，新人通过阅读 AI 产出，配合 Rules 和标杆文件，比自己摸索学习路径更高效。