VibeCoding 工程化协作开发规范

核心理念：让 AI 在既有架构框架内写代码，而非替你设计架构。通过定义清晰的业务对象和交互逻辑，约束 AI 的生成范围，使其在"正确的上下文"中生成"符合架构规范的代码"，实现从自然语言需求到结构化代码的无损转换。

三阶价值闭环：① Model/Object 结构解决代码散乱 → ② Entity 状态管理解决逻辑泄露 → ③ Rule/Skill 体系解决 AI 不可控。

铁律：目录结构与四层职责

任何代码生成任务开始前，先确认目标位置符合垂直切片结构（按业务模块和领域对象组织代码，摒弃传统技术分层）：

model/order/                      # Order 模块根目录（按业务模块垂直切片）
├── OrderObject/                  # 领域对象聚合根：Entity、枚举、异常
│   ├── OrderEntity.java          # 含静态内部类 OrderDTO（视图，工厂方法构建）
│   ├── OrderPlacementEntity.java # 场景组合实体：多实体协同时的大业务Entity（按需）
│   ├── OrderStatus.java
│   └── OrderException.java
├── OrderService.java             # 业务逻辑编排（内部大脑）
├── OrderPersistenceService.java  # 持久化服务：选型约束驱动，默认 JDBC 起步（SQL 收口；ORM 正当场景映射也收口于此）
└── OrderController.java          # 对外 API 门面

调用链路：Controller → Service → Entity → Object/Value。所有 Entity、枚举、Exception 必须物理内聚在对应的 Object 文件夹内，实现模块自闭环。不设独立 DTO 文件：视图 DTO 作为 Entity 的静态内部类，仅通过 Entity 工厂方法（如 toDTO()）构建。无独立 Request 文件：Controller 接 JSON 直接绑定 Entity 内部入参 DTO（CreateDTO），经 Entity 构造函数解析构建实体；入参与出参（OrderDTO）是两个独立内部类，禁止共用（见 references/badcases.md BC-01）。跨模块调用必须通过对方 Service 接口。

Service 与 Entity 互相绑定：Entity 提供基础操作方法（业务规则内聚），Service 负责业务编排（决定顺序与条件）——两者缺一不可，规则进 Entity、流程进 Service。Service 编排 Entity 基础方法是标准模式，不算违规；违规的是 Service 重复实现业务规则或直接改实体字段。

持久化与事务边界

• 持久化集中（选型约束驱动，不预设 ORM）：持久化选型是约束驱动的架构决策，禁止"模板用什么照抄什么"。默认从 JDBC 风格（Spring JdbcTemplate + 手写 SQL）起步：Entity 零妥协（final 字段、构造函数构建、无 ORM 注解，反射 setter/懒加载代理问题不存在），乐观锁条件更新直白到一行 WHERE status=? AND version=?，且 JDBC 是 JDK 接口零框架绑定（支撑独立升级路线）。选 MyBatis/JPA 的正当理由（动态 SQL 生态、团队存量、复杂映射）成立时同样允许，但映射细节必须收口于 PersistenceService，Entity 的妥协范围 @decision 留痕。无论选哪种：全部 SQL 集中在本模块独立的持久化 Service（如 OrderPersistenceService），禁止随业务代码散落——利于维护，也方便构建完整事物流；入参出参一律 Entity/DTO，业务层不感知持久化细节；持久化重建走 restore() 全参静态工厂（含 version），不走 setter 灌值。选型结论与理由 @decision 留痕。
• 事务独立方法：所有事务拆成独立方法，每个 @Transactional 方法只做一件事、只管一个资源域，禁止事务方法互相嵌套混杂。
• 事务混杂 → 人工决策：发现跨 DB、跨第三方（如支付网关+本地订单）的事务混杂时，不再构建事务——停下交给人判断：拆成独立事务+补偿（Saga）、取消事务，还是退化为手动 commit() 控制。AI 只陈述选项与影响面，不得替人决策。
• 框架依赖策略（独立升级路线）：当模块作为基础库被多服务引用、或要求独立升级时，采用"内核纯 Java + 薄装配层"——业务内核（持久化通道/缓存封装/连接管理）只用 JDK + 裸客户端（JDBC/Jedis 等），零框架注解；Spring 只出现在装配层（Adapter/@Configuration 把内核桥进容器），内核与装配分层可拆。该决策 @decision 留痕"独立升级"约束，给内核加框架注解即破坏约束（纯 Java 内核可跨 Spring 大版本存活零改动）。框架选择是约束驱动的思考方式——不是"永远用框架生态"，也不是"永远排斥"，按模块的升级/复用约束决定。

代码风格铁律：全局禁用 Stream 与 Lambda

集合的遍历、过滤、映射、聚合、查找、分组一律写标准的有界循环语句（for / 增强 for / 带终止条件的 while），全局禁止函数式内联写法。理由：循环语句执行路径线性，断点与异常堆栈行号直接对应业务代码行，变量命名显式。

• 禁止 Stream API：stream() / parallelStream() / Collectors.* / 链式 .map().filter().forEach().reduce() 等全套管道。
• 禁止 Lambda 表达式与方法引用：(x) -> ... 与 Xxx::yyy（方法引用是 Lambda 的等价形式，一并禁止，防止换写法绕过）。
• 替代写法对照：
• 过滤+映射 → for 循环 + if 条件判断 + 普通 add；
• 聚合（求和/计数/拼接）→ 循环外声明累加变量，循环内累加；
• 查找（findFirst/anyMatch）→ for 循环命中即 return / break；
• 分组（groupingBy）→ 显式 Map + get() 判空 + put()，禁止 computeIfAbsent（其参数就是 Lambda）；
• 函数式接口参数（RowMapper/Comparator 等）→ 匿名内部类实现；
• Optional.orElseThrow(() -> ...) → 显式判空 + throw。
• 范围：全部 Java 代码（Entity/Service/Controller/PersistenceService/测试），与层级无关。箭头 switch（case X -> ...）是控制流语法不是 Lambda，不受本禁令限制。
• 存量处理：遵循存量渐进迁移原则——不因本规则顺手重写存量 Stream/Lambda，只重构本次正在修改的链路；个别必须保留的例外，在对应 Entity JavaDoc 显式声明。

工作流：按任务场景执行

场景 1：新建业务模块（领域对象生成器）

输入业务对象名称（如 Order），生成完整骨架：

1. 创建 model/<module>/<Module>Object/ 文件夹及三个文件：<Module>Entity.java（内含静态内部类 <Module>DTO 与 toDTO() 工厂方法）、<Module>Status.java（状态枚举）、<Module>Exception.java（继承 RuntimeException 的领域专属异常）。禁止生成独立 DTO 文件。
2. Entity 状态字段内置 @Setter(AccessLevel.NONE) 状态保护。
3. 每个公开命令方法预留 @logic 五要素 JavaDoc 框架（见场景 2）。
4. 依据用户口述的状态清单填充枚举值与状态流转方法（如 CREATED/PAID/SHIPPED/COMPLETED + pay()/ship()/cancel()）。

完整文件模板见 assets/templates/（Entity含DTO内部类/Enum/Exception/Service/PersistenceService/Controller/Mock 可直接复制改名）。

场景 2：Entity 充血模型逻辑实现

为状态流转方法生成实现时，遵循"校验 → 变更"模式：

/**
 * @logic 仅CREATED状态可支付，支付后订单进入PAID状态
 * @precondition 当前状态必须为 CREATED
 * @postcondition 执行后状态变更为 PAID
 * @rule 1. 支付金额不得为负数
 * @throws OrderException 状态不合法时抛出（类名+触发条件+业务含义）
 * @concurrency 乐观锁：更新须带 version 条件（UPDATE...WHERE status='CREATED' AND version=?），
 *              影响行数为 0 视为并发冲突，抛 OrderException 由上层决定重试
 */
public void pay() {
    if (this.status != OrderStatus.CREATED) {
        throw new OrderException("当前状态[" + this.status + "]不可支付");
    }
    this.status = OrderStatus.PAID;
}

硬性要求：

• @logic 五要素缺一不可：@logic（第一行，概括业务语义）、@precondition（明确前置状态，禁止"合法状态"等模糊描述）、@postcondition（流转目标+副作用）、@rule（逐条编号，禁止合并）、@throws。
• 只抛领域专属异常：仅抛出当前 Object 文件夹下定义的 <Module>Exception，确保链路可追溯。
• 原子性校验：先校验全部前置条件，全部通过后才执行状态变更，禁止部分写入后中断。
• 实体始终有效：构造函数强制满足基本不变量（ID 非空、初始状态合法）；创建即合法。
• 视图经工厂方法：对外视图一律 entity.toDTO() 构建，禁止在 Entity 外逐字段拷贝构建 DTO。
• 并发控制入 JavaDoc：状态流转涉及并发的，必须声明 @concurrency（乐观锁 version 条件更新/幂等键），Entity 预留 version 字段——并发策略不写进 JavaDoc，没有人会记得，也没有任何文档会记录它。
• 错误码分通用与专属：通用 HTTP 语义错误用 common 通用 Entity HttpErrorEntity（NOT_FOUND/STATE_CONFLICT/INVALID_PARAM，全项目共用，禁止各模块重复定义）；业务专属错误码才跟业务 Entity 走（如 SendMessageError），Controller 按枚举映射 HTTP 状态。
• 解析已有 @logic 描述实现逻辑时，描述即契约，不得偏离。

多实体组合 → 场景组合实体（一致性边界）：一个业务场景涉及多个实体协同时，在本模块 Object 文件夹内创建场景组合实体（命名 <Module><场景>Entity，如 OrderPlacementEntity），类 JavaDoc 首行标注组合场景：@logic 在【下单】场景下组合 OrderEntity 与 OrderItemEntity。组合实体是场景一致性边界，不是流程编排者：跨实体不变量校验与联动状态变更内聚于其场景方法（如 place()）；流程编排（步骤顺序、外部调用、事务）归 Service——Service 编排（校验用户→锁库存→placement.place()→落库），place() 只保跨实体一致性。组合仅限本模块实体，跨模块仍走对方 Service 接口。模板见 assets/templates/AggregateEntityTemplate.java。

聚合默认无表，有表必须写明表聚合逻辑：场景组合实体是无表聚合——它是内存中的一致性边界，自身不对应数据库表、不独立落库；持久化由子实体各落各表，组合落库收口在 PersistenceService 单一事务方法。仅当聚合级数据需要独立持久化（场景单号、聚合自身状态机、跨子实体汇总快照、聚合级 version）时才建有表聚合，且必须在组合实体类 JavaDoc 写清楚表聚合逻辑：①表定位（聚合表存什么、与子表外键关系）②落库拆解（聚合表+子表同事务写入顺序）③重建组装（restore() 全参工厂+子实体装配）④聚合级 @concurrency；并以 @decision 留痕建表理由（默认无表，建表是显式偏离）。判别口径：聚合级数据是否需要独立查询或聚合自身有独立状态流转——都不需要则一律无表。详见 references/entity-standards.md。

组合视图 DTO 归组合实体：DTO 的归属看业务发生在哪，不看数据来自哪个实体。跨实体组合视图（如订单详情页=订单+明细）的 DTO 定义在组合实体上——组合实体持有自己的静态内部类 DTO 与 toDTO()（内部委托子实体工厂方法取数），Controller 从进来到结束全程使用该组合 Entity，禁止在 Service/Controller 拼装多个子实体 DTO。

详见 references/entity-standards.md。

场景 3：调用链路与 Service 编排（链路先行）

每个入口（Controller endpoint / 消息监听 Listener / 定时 Job）必须保留完整的数据调用链路（@chain），与实际代码保持一致。链路是业务流程的唯一权威登记处——检索、修改、审查全部以它为入口。入口必薄：Listener/Job 与 Controller 同规，禁止内写分发 switch 或业务规则（类型路由进枚举/Entity，见 badcases.md BC-09）；非 HTTP 入口的 @chain 标注在 Listener/Job 类 JavaDoc，且必须写幂等（消息重复投递/Job 重跑是常态）。

@chain 采用树形格式，多分支逐条写清（[条件] 标注分支走向，异常路径也是分支）：

/**
 * @param orderId 订单ID（路径参数，必填）
 * @return 支付后的订单视图
 * @chain 数据调用链路（修改前先改此处，再改代码）：
 *   OrderController.pay                        -- 入口
 *   └─ OrderService.pay
 *      ├─ OrderRepository.findById             查询订单，不存在抛 OrderException
 *      ├─ OrderEntity.pay                      状态流转 CREATED→PAID
 *      └─ PaymentGateway.charge                外部支付
 *         ├─ [支付成功] OrderRepository.save   落库已支付订单
 *         └─ [支付失败] OrderEntity.cancel     分支：回滚订单
 *            └─ RefundService.rollback         触发退款
 */

三条工作流：

1. 检索业务流程：找流程先找对应入口（Controller / Listener / 定时 Job）的 @chain，禁止凭记忆猜测。沿节点逐跳：@chain → 各节点 @see（正向定位实现）→ @used-by（反向反查影响面）。
2. 链路先行修改：任何代码修改前，先把变更翻译成新 @chain（改节点/增删分支），链路确认后沿链路逐节点改代码，最后回验链路与代码符号一一对应。
3. 链路逆向（存量代码无 @chain 时）：禁止直接改代码。先通读 Controller→Service→Entity→外部调用，把 if/else、异常 catch、Mock/真实多态等多分支全部写清，逆向出 @chain 写入 Controller JavaDoc，再执行链路先行修改。

Service 接口定义后，先由 AI 生成详细伪代码骨架，确保上下游逻辑对齐，再逐步填充实现（伪代码是 @chain 在 Service 内部的展开）：

// 入参/出参分离（badcases.md BC-01）：入参 CreateDTO（Controller 接 JSON，无独立 Request 文件），
// 出参 OrderDTO（Entity 静态内部类，经 order.toDTO() 工厂方法构建）
public OrderEntity.OrderDTO createOrder(OrderEntity.CreateDTO req) {
    // 1. 校验用户
    //    @see UserService.validate(req.getUserId())
    // 2. 锁定库存
    //    @see InventoryService.lock()
    // 3. 构建实体（Entity 解析入参 DTO 构建自身）
    //    new OrderEntity(req)
    // TODO: 待实现——落库（后续通知走对方 Service 同步调用），返回 order.toDTO()
    ...
}

标记协议（代码即文档，标记即契约）：

• @chain：完整数据调用链路，登记在 Controller 方法 JavaDoc；多分支写清；修改前先改。
• @see：正向标记，在 Service 方法中标注依赖的外部 API，建立代码间"超链接"。
• @used-by：反向标记，在被调用的 API 上标注使用者，防止误删。
• @status：标注实现/迁移状态——mock/implemented（Mock 联调），legacy/migrated（存量接口迁移进度），维护全局视图。
• @decision：人工决策记录（循环依赖拆解、事务混杂处置、架构选型等）——写明结论、为什么、谁定的（决策人+日期），置顶登记在涉及链路的 Controller 与 Entity JavaDoc。
• @history：方法变更履历——行为方法每次行为变更在方法 JavaDoc 追加一条（日期 需求【需求号/背景】变更要点），时间正序、旧条目禁删改；方法变更多次时历次时间与需求全部可循，修改前先读（详见 references/collaboration-protocol.md）。

详见 references/collaboration-protocol.md。

场景 4：多态 Mock 实现

外部依赖未就绪时，为 Service 接口生成双实现，实现 POC 到生产的无缝切换：

• Mock 实现类标注 @Profile("poc")，模拟成功与失败两种返回。
• 真实实现标注 @Profile("prod")。
• 模板见 assets/templates/MockServiceTemplate.java。

场景 5：单元测试生成

解析 Entity 业务方法，自动生成 JUnit 测试，双路径覆盖：

• 正常路径：新建订单 → 调用 pay() → 断言状态变为 PAID。
• 异常路径：已发货订单 → 调用 pay() → 断言抛出 <Module>Exception。
• 使用自描述测试数据（buildPaidOrder() 等语义化构造方法），降低维护成本。

场景 6：架构合规审查

对既有代码执行规则库检查，输出违规清单并修复。核心检查项：

1. 结构：严格遵循 Model → Object → Service/Controller 层级；Entity/枚举/Exception 位于对应 Object 文件夹内；无独立 DTO 文件（DTO 内聚于 Entity 并经工厂方法构建）。
2. Entity：状态字段无 public setter；状态变更仅通过业务方法；内部无 Service 依赖注入；多实体协同场景有组合实体且 JavaDoc 标注了组合场景；聚合默认无表，有表聚合已写明表聚合逻辑（表定位/落库拆解/重建组装/聚合级并发）并 @decision 留痕。
3. Service：Controller 无业务逻辑；跨模块调用走 Service 接口；无直接操作其他模块 Entity/DAO。
4. 文档协作：Service 公共方法 JavaDoc 含 @param、@return、@logic；跨模块调用有 @see 标记；Controller 每个 endpoint 有 @chain 完整链路且与代码一致（多分支写清）；行为方法历次变更有 @history 履历（日期+需求【】+要点），旧条目无删改。
5. 异常处理：通用错误码走 common 的 HttpErrorEntity（NOT_FOUND→404、STATE_CONFLICT→409、INVALID_PARAM→422，禁止模块内重复定义）；业务专属错误才建 <Module>Error 跟业务 Entity 走；Controller 按枚举映射，禁止解析 message 区分语义。
6. 并发与事务：状态流转方法有 @concurrency 声明（乐观锁/幂等键）；事务方法单一资源域独立；发现事务混杂只陈述选项交人工决策。
7. 代码风格：无 Stream API、无 Lambda 表达式、无方法引用；集合遍历/过滤/映射/聚合/分组全部为标准有界循环语句（for/增强 for/带终止条件 while），函数式接口参数为匿名内部类。

审查清单与规则增强模式（组合校验 / 分层规范编排 / 规则库集成）详见 references/rules-checklist.md。

场景 7：知识考古与作者访谈（存量设计意图落档）

存量代码运行良好（如长期 0 丢失/0 事故）但设计思路只在作者脑中时，把"作者在场保证"变成"文档化保证"：

• 触发：读存量代码发现设计意图可从结构反推但有歧义（为什么自动提交？为什么批量失败降级单条？finally 里重建线程是有意还是巧合？），或运行指标依赖的机制无任何文档。
• 禁止臆断：AI 不得把推断写成 JavaDoc/@decision 事实——理论上的风险窗口 ≠ 实际事故，先问幂等闭环/自愈机制再下判断（BC-09 三轮改判的教训）。
• 访谈三步：① AI 通读代码，逆向出候选解释与疑问清单（每问 = 现象 + 候选解释 A/B + 影响面，禁止开放式"这是什么意思"）；② 向作者提问，拿到真实机制；③ AI 整理成 @decision（结论/为什么/谁定的+日期，含"禁止变更"清单）与 @chain 写回类 JavaDoc，作者确认后落档。
• 落档位置：系统级保证（幂等闭环/背压语义）→ 入口类（Listener/主 Service）JavaDoc；单类机制（自愈/降级）→ 该类 JavaDoc。
• 修改前必读：触碰带 @decision 的存量代码，先读其"禁止变更"清单——看起来怪的代码（finally 自我重生、批量失败逐条重插）可能正是 0 丢失/自愈的保证本体，按常规"代码坏味道"清理掉即破坏保证。

存量项目渐进迁移

• 禁止一次性重写：存量项目先逆向理清所有 Controller 的 @chain 链路，在后续修改中逐步替换为规范结构——每次只迁移正在修改的链路，不要求项目一夜变成规范形态。理清链路前，先对运行良好但无文档的设计执行场景 7 作者访谈——设计意图落档优先于结构调整，防止迁移破坏隐性保证（幂等闭环、自愈机制、背压路径）。
• 接口状态标记：endpoint 标注 @status legacy（存量未迁移）/ @status migrated（已迁移），整个链路与 @used-by 中可清晰追溯哪些接口是存量的、哪些已改造完成；迁移完成后更新标记。
• 无退出条件：除存量项目渐进迁移外，新代码一律遵守本规范；个别特殊方法/场景的例外，必须在对应 Entity 的 JavaDoc 中显式声明走什么规范，禁止默认绕过。

强制执行协议（Hard Gates）

规范生效靠关卡，不靠自觉。任何编码任务必须依次通过三道门，未通过不得进入下一步：

门 1 · 开工门（写第一行实现代码之前）

1. 归属判定：明确说出目标代码属于哪个模块、哪个层级、哪个文件；说不出即停下向用户确认，禁止"先写再说"。
2. 链路状态检查：定位目标 endpoint 的 @chain——新建流程先起草完整链路（多分支写清）再生成骨架；修改流程先读现有链路定位受影响节点；无 @chain 先执行链路逆向（场景 3），补齐后才允许继续。
3. 输出计划链路：把本次变更后的 @chain 完整写出，作为任务蓝图。

门 2 · 交付门（交付物三件套，缺一不可）

• ① 变更前 @chain（或注明"原本无链路，已逆向补齐"）；
• ② 变更后 @chain（已写入 Controller JavaDoc）；
• ③ 链路→代码映射：新/改节点 ↔ 文件.方法 一一对应。

门 3 · 收尾门（Exit Checklist，逐项核对后才算完成）

• [ ] @chain 每个节点在代码中真实存在；代码关键调用/分支在链路中有登记
• [ ] Entity 新增/修改方法 @logic 五要素齐全，@rule 逐条编号
• [ ] 本次修改的行为方法已追加 @history（日期+需求【】+要点），未删改旧条目
• [ ] 无独立 DTO 文件；视图全部经 toDTO() 等工厂方法构建
• [ ] @see/@used-by 双向同步；@status 如实
• [ ] 多实体协同经场景组合实体（一致性边界）；Service 编排 Entity 基础方法但未重复实现规则、未直接改实体字段；聚合默认无表，有表聚合的表聚合逻辑（表定位/落库拆解/重建组装/聚合级并发）已写明并 @decision 留痕
• [ ] 涉及并发的状态流转已声明 @concurrency（乐观锁 version 条件更新/幂等键）
• [ ] 无事务混杂：事务方法单一资源域独立；跨资源场景已交人工决策并留痕
• [ ] 无 Stream API / Lambda / 方法引用：集合处理全部为标准有界循环语句，函数式接口参数为匿名内部类（箭头 switch 不受限）
• [ ] 新增/变更分支有对应 JUnit 用例（正常+异常双路径）

任一项不满足：当场补齐后重新过门，禁止"遗留 TODO 以后处理"式收尾。

跳过即违规：本技能加载后，跳过任何一道门直接产出代码视为执行失败，必须自我纠正、从门 1 重来；前置条件无法满足时（找不到链路、无法判定归属），停下说明缺口并请求输入，而不是猜测后继续。团队/CI 层面的强制手段（ArchUnit 构建期校验、提交门禁脚本）见 references/rules-checklist.md 的「工程侧强制门禁」。

资源导航

行为准则

• 生成任何代码前，先判断其归属的模块与层级，再动手；不确定归属时先向用户确认模块划分。
• 遇到不符合本规范的存量代码，主动提示违规项并按规范修复，而非沿用旧风格。
• 禁止创建独立 DTO 文件，也禁止在 Entity 外逐字段拷贝构建视图；一律使用 Entity 内工厂方法。
• 全局禁用 Stream 流、Lambda 表达式与方法引用：集合的遍历/过滤/映射/聚合/分组一律写标准有界循环（for/增强 for/带终止条件 while），函数式接口参数用匿名内部类；箭头 switch（case X -> ...）是控制流语法，不受限。
• 状态流转、跨模块依赖等关键决策点，在 JavaDoc 与标记协议中留痕，保证 AI 协作上下文可追溯；行为方法每次变更追加 @history 履历（日期+需求【】+要点，时间正序、旧条目禁删改），让所有变更有迹可循。
• 严格执行三道门：写代码前过开工门（归属+链路+计划链路），交付附三件套，收尾过 Exit Checklist；无法满足时停下说明缺口，禁止跳关。
• 发现事务混杂（跨 DB/跨第三方）或模块间循环依赖（A→B→A）立即停下交人决策，只陈述选项不替人拍板；决策经 @decision 写清 JavaDoc（结论/为什么/谁定的）置顶于 Controller 与 Entity。
• 架构细节（幂等键载体、事件中间件选型等）不替人拍板：留 TODO 由人工补充 JavaDoc 设计思路并 @decision 留痕；模块间通知凡对方有 Service 即走同步调用，无对方 Service 的异步场景按架构细节人工定案。新代码无退出条件，例外仅在对应 Entity 的 JavaDoc 中显式声明。