写在前面最近一年团队里几乎每个 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 区别于 FlowFlow 是定义模板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单机模式不要假设有集群 # 编码强制要求 - 任何外部 IOHTTP/DB/Redis必须有超时配置禁止使用默认值 - 日志输出统一走 LogUtil不要直接 logger.info - 异常按照 BizException ErrorCode 体系抛出不要 throw new RuntimeException # 禁止的事情 - 不要修改 ipaas-api 模块下的 .proto 和 IDL 文件 - 不要在 service 层直接拼 SQL - 不要新增 Lombok 之外的代码生成框架这份文档解决了 AI 最常见的几类问题用错语法JDK 版本不匹配、引入新依赖团队不许、改错文件敏感目录。2.2 ADR 的复兴让架构决策可追溯ADRArchitecture Decision Record这个概念十年前就有了但用得不多。AI 时代它突然变得很重要——AI 不知道某个看似不合理的设计背后有什么历史决策会自作主张改掉它。举个例子我们的某个核心服务用了一个看起来很怪的双层缓存Redis 本地 Caffeine。AI 看到这种结构会很自然地建议为什么不直接用 Redis双层缓存增加复杂度。但实际上这是因为某次大促时 Redis 被打爆团队为此专门做了本地缓存兜底。我们现在每个非显然的设计都写一份 ADRADR-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典型 N1 问题 ❌ 不要直接捕获 Throwable最大粒度到 Exception ❌ 不要使用 BeanUtils.copyProperties性能差用 MapStruct ❌ 不要在 PostConstruct 里做耗时操作500ms ❌ 不要新增 Spring AOP 切面已有切面会冲突需架构组评审 ❌ 不要使用 System.currentTimeMillis() 测时间用 StopWatch这份清单是动态维护的——每次代码评审发现 AI 反复犯的同类错误就把它加到反模式里。3.4 上下文管理哪些文件先喂给 AIAI 编辑器的上下文窗口是有限的喂错文件比不喂还糟糕——它会按错的样板来写新代码。我们总结的上下文喂养顺序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 行以内方便 reviewAI 标注commit message 里标注 “AI-Assisted” 或 “Human-Written”方便统计 AI 占比和事故归因强制 self-review开发者提 PR 前必须自己 review 一遍 AI 产出特别是异常处理、边界条件、敏感操作三块关键代码人工写核心算法、安全相关、事务边界这三类代码不让 AI 写最后一点很重要。AI 写添砖加瓦的代码很好但写涉及钱、权限、数据一致性的代码必须人来写——AI 的看起来对和真的对差距很大这种代码出问题的成本太高。四、测试阶段从补测试到测试驱动 AI4.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: ListLong请生成以下边界测试 - 空列表 - 只有一个元素 - 包含 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 模板做出来其他的边走边补。七、几个常见误区误区 1AI 是来替代程序员的实际是来改造研发流程的每个环节。程序员的角色从写代码转向定义规范、审查产出、做关键决策。会用 AI 的程序员产出会高 3-5 倍但角色责任更重——出错由你负责。误区 2所有代码都让 AI 写核心算法、安全相关、跨服务事务、性能敏感的代码依然要人写。AI 适合写添砖加瓦的工程代码不适合写一锤定音的核心代码。误区 3AI 写了测试就万事大吉AI 生成的测试覆盖率高但深度未必够。它会覆盖各种参数变种但未必能识别业务上不可能出现的组合和业务上很危险的组合。这两类用例还是要人来设计。误区 4Rules 写得越多越好Rules 太多 AI 会忽略一部分受上下文窗口限制。关键规则要抓重点JDK 版本、命名分层、异常日志、事务边界这几块是核心其他的能简则简。误区 5迁移到新工具就有提升工具只是放大器。流程不改换什么工具都白搭。先把流程理顺再选合适的工具。八、常见问题FAQQ项目历史包袱很重老代码不符合规范怎么让 AI 避免对齐老代码的坏味道A在 Rules 里明确标注以下目录是历史代码仅供 reference 不要作为标杆同时维护一份标杆文件清单列出新代码应该参考哪些文件。AI 在生成代码时会优先模仿明确指定的标杆而不是随便扫到的同类文件。Q怎么衡量这套流程的收益A建议同时跟踪四个指标交付吞吐PR 数/人月、缺陷率线上 bug/千行代码、返工率同一需求的修改次数、code review 通过率一次通过的 PR 占比。AI 流程改造做得好的团队吞吐会涨 2-3 倍缺陷率持平或下降返工率明显下降。Q小团队没有专门的 PM 和架构师谁来维护 Rules、PRD 模板、ADRA让一个资深开发兼任。前期投入大概是每周 4-8 小时跑顺之后每周 1-2 小时维护就够了。这部分时间投入比换来的产出提升划算得多。Q用 Cursor、Qoder、Claude Code 这些工具的 Rules 文件能通用吗A核心内容命名规范、分层规则、反模式清单通用但不同工具的 Rules 文件路径和优先级机制略有不同。建议把核心 Rules 放在docs/rules.md然后在每个工具的专用配置文件中通过 include 或复制的方式引用。这样切换工具时不用全部重写。QAI 生成的代码出了线上事故责任算谁的A算提交代码的人。AI 是工具最终的代码质量由提交者负责。这也是为什么前面强调要做 self-review 和强制 PR review——不能因为是 AI 写的就放低审查标准。团队里要明确这个责任边界避免反正是 AI 写的心态。Q用 AI 写代码会不会让新人成长变慢A用法不对会用法对了反而成长更快。错误用法是提需求 → AI 写 → 直接提交这种模式下新人确实学不到东西。正确用法是AI 写 → 自己看懂每一行 → 能解释清楚为什么这么写 → 提交——本质上 AI 是高级版的样例代码新人通过阅读 AI 产出配合 Rules 和标杆文件比自己摸索学习路径更高效。九、写在最后AI 不会让研发流程变简单恰恰相反它会让研发流程变得更规整——因为只有规整的输入才能得到规整的输出。这一两年我们在数环通 iPaaS 团队推行这套实践最深的体会是**做规范的成本会被 AI 的产能放大效应稀释掉。**以前写 Rules 和 ADR 看起来是额外的工作性价比不高现在每写一条 Rules 都能让 AI 在以后的几百次代码生成里少犯一类错性价比变得极高。AI 时代的研发流程本质上是把人的隐性知识显性化、把团队默契文档化、把代码评审标准 checklist 化。这些事情即使没有 AI 也应该做AI 只是让不做的代价变得更明显。如果你的团队正在被AI 写代码很快但质量参差困扰建议从下面三件事开始写一份项目 Rules半天就够改一版 PRD 模板强制四段式 用例先行挑 5 个标杆文件标注成AI 应参考的样本这三件事做完AI 编辑器在你项目里的表现会立刻提升一个台阶。剩下的优化边用边补就好。标签#AI编程 #AI工作范式 #研发流程 #Cursor #Qoder #ClaudeCode #Copilot #PromptEngineering #TestDriven #ADR #编码规范 #ProjectRules #数环通 #iPaaS #软件工程
AI 工作范式下的研发新范式：从需求到测试的全链路落地指南
发布时间：2026/5/22 17:17:19
写在前面最近一年团队里几乎每个 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 区别于 FlowFlow 是定义模板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单机模式不要假设有集群 # 编码强制要求 - 任何外部 IOHTTP/DB/Redis必须有超时配置禁止使用默认值 - 日志输出统一走 LogUtil不要直接 logger.info - 异常按照 BizException ErrorCode 体系抛出不要 throw new RuntimeException # 禁止的事情 - 不要修改 ipaas-api 模块下的 .proto 和 IDL 文件 - 不要在 service 层直接拼 SQL - 不要新增 Lombok 之外的代码生成框架这份文档解决了 AI 最常见的几类问题用错语法JDK 版本不匹配、引入新依赖团队不许、改错文件敏感目录。2.2 ADR 的复兴让架构决策可追溯ADRArchitecture Decision Record这个概念十年前就有了但用得不多。AI 时代它突然变得很重要——AI 不知道某个看似不合理的设计背后有什么历史决策会自作主张改掉它。举个例子我们的某个核心服务用了一个看起来很怪的双层缓存Redis 本地 Caffeine。AI 看到这种结构会很自然地建议为什么不直接用 Redis双层缓存增加复杂度。但实际上这是因为某次大促时 Redis 被打爆团队为此专门做了本地缓存兜底。我们现在每个非显然的设计都写一份 ADRADR-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典型 N1 问题 ❌ 不要直接捕获 Throwable最大粒度到 Exception ❌ 不要使用 BeanUtils.copyProperties性能差用 MapStruct ❌ 不要在 PostConstruct 里做耗时操作500ms ❌ 不要新增 Spring AOP 切面已有切面会冲突需架构组评审 ❌ 不要使用 System.currentTimeMillis() 测时间用 StopWatch这份清单是动态维护的——每次代码评审发现 AI 反复犯的同类错误就把它加到反模式里。3.4 上下文管理哪些文件先喂给 AIAI 编辑器的上下文窗口是有限的喂错文件比不喂还糟糕——它会按错的样板来写新代码。我们总结的上下文喂养顺序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 行以内方便 reviewAI 标注commit message 里标注 “AI-Assisted” 或 “Human-Written”方便统计 AI 占比和事故归因强制 self-review开发者提 PR 前必须自己 review 一遍 AI 产出特别是异常处理、边界条件、敏感操作三块关键代码人工写核心算法、安全相关、事务边界这三类代码不让 AI 写最后一点很重要。AI 写添砖加瓦的代码很好但写涉及钱、权限、数据一致性的代码必须人来写——AI 的看起来对和真的对差距很大这种代码出问题的成本太高。四、测试阶段从补测试到测试驱动 AI4.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: ListLong请生成以下边界测试 - 空列表 - 只有一个元素 - 包含 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 模板做出来其他的边走边补。七、几个常见误区误区 1AI 是来替代程序员的实际是来改造研发流程的每个环节。程序员的角色从写代码转向定义规范、审查产出、做关键决策。会用 AI 的程序员产出会高 3-5 倍但角色责任更重——出错由你负责。误区 2所有代码都让 AI 写核心算法、安全相关、跨服务事务、性能敏感的代码依然要人写。AI 适合写添砖加瓦的工程代码不适合写一锤定音的核心代码。误区 3AI 写了测试就万事大吉AI 生成的测试覆盖率高但深度未必够。它会覆盖各种参数变种但未必能识别业务上不可能出现的组合和业务上很危险的组合。这两类用例还是要人来设计。误区 4Rules 写得越多越好Rules 太多 AI 会忽略一部分受上下文窗口限制。关键规则要抓重点JDK 版本、命名分层、异常日志、事务边界这几块是核心其他的能简则简。误区 5迁移到新工具就有提升工具只是放大器。流程不改换什么工具都白搭。先把流程理顺再选合适的工具。八、常见问题FAQQ项目历史包袱很重老代码不符合规范怎么让 AI 避免对齐老代码的坏味道A在 Rules 里明确标注以下目录是历史代码仅供 reference 不要作为标杆同时维护一份标杆文件清单列出新代码应该参考哪些文件。AI 在生成代码时会优先模仿明确指定的标杆而不是随便扫到的同类文件。Q怎么衡量这套流程的收益A建议同时跟踪四个指标交付吞吐PR 数/人月、缺陷率线上 bug/千行代码、返工率同一需求的修改次数、code review 通过率一次通过的 PR 占比。AI 流程改造做得好的团队吞吐会涨 2-3 倍缺陷率持平或下降返工率明显下降。Q小团队没有专门的 PM 和架构师谁来维护 Rules、PRD 模板、ADRA让一个资深开发兼任。前期投入大概是每周 4-8 小时跑顺之后每周 1-2 小时维护就够了。这部分时间投入比换来的产出提升划算得多。Q用 Cursor、Qoder、Claude Code 这些工具的 Rules 文件能通用吗A核心内容命名规范、分层规则、反模式清单通用但不同工具的 Rules 文件路径和优先级机制略有不同。建议把核心 Rules 放在docs/rules.md然后在每个工具的专用配置文件中通过 include 或复制的方式引用。这样切换工具时不用全部重写。QAI 生成的代码出了线上事故责任算谁的A算提交代码的人。AI 是工具最终的代码质量由提交者负责。这也是为什么前面强调要做 self-review 和强制 PR review——不能因为是 AI 写的就放低审查标准。团队里要明确这个责任边界避免反正是 AI 写的心态。Q用 AI 写代码会不会让新人成长变慢A用法不对会用法对了反而成长更快。错误用法是提需求 → AI 写 → 直接提交这种模式下新人确实学不到东西。正确用法是AI 写 → 自己看懂每一行 → 能解释清楚为什么这么写 → 提交——本质上 AI 是高级版的样例代码新人通过阅读 AI 产出配合 Rules 和标杆文件比自己摸索学习路径更高效。九、写在最后AI 不会让研发流程变简单恰恰相反它会让研发流程变得更规整——因为只有规整的输入才能得到规整的输出。这一两年我们在数环通 iPaaS 团队推行这套实践最深的体会是**做规范的成本会被 AI 的产能放大效应稀释掉。**以前写 Rules 和 ADR 看起来是额外的工作性价比不高现在每写一条 Rules 都能让 AI 在以后的几百次代码生成里少犯一类错性价比变得极高。AI 时代的研发流程本质上是把人的隐性知识显性化、把团队默契文档化、把代码评审标准 checklist 化。这些事情即使没有 AI 也应该做AI 只是让不做的代价变得更明显。如果你的团队正在被AI 写代码很快但质量参差困扰建议从下面三件事开始写一份项目 Rules半天就够改一版 PRD 模板强制四段式 用例先行挑 5 个标杆文件标注成AI 应参考的样本这三件事做完AI 编辑器在你项目里的表现会立刻提升一个台阶。剩下的优化边用边补就好。标签#AI编程 #AI工作范式 #研发流程 #Cursor #Qoder #ClaudeCode #Copilot #PromptEngineering #TestDriven #ADR #编码规范 #ProjectRules #数环通 #iPaaS #软件工程
