用Claude Code和COLA状态机打造订单MVP：先建模再写代码

这次我们聊一个 AI 编程实战里的核心问题用 Claude Code 给业务系统写代码第一步不是写代码而是先做 MVP把状态流转想清楚。很多人拿到 AI 编程工具就直接让它写订单、审批、工单这类业务模块结果往往是这样功能能跑但状态一多 AI 就开始乱跳改一个分支带出三个 bug新开会话以后又忘掉上下文。问题的根源不是提示词写得好不好而是业务模型没有被固定下来。这篇实战文章会按照“先做 MVP 设计再请 Claude Code 动手”的思路演示一套可落地的流程。我们会先安装并配置 Claude Code再引入阿里巴巴开源的 cola-statemachine 状态机组件用一个订单状态流转的 MVP 例子把状态、事件、条件和动作定义清楚然后让 Claude Code 基于这套模型生成代码最后用单元测试验证整个流转。如果你正在用 Claude Code、Cursor 这类 AI 编程工具做业务系统或者刚接触 DDD、状态机、vibe coding 和传统开发方式的取舍这篇文章可以直接收藏。它不会教你写花哨的提示词而是教你给 AI 划清楚工作边界让生成结果稳定可维护。1. 核心能力速览先花一分钟把这次要用的能力和门槛讲清楚。下面的表格来自项目实际使用中常见的信息维度便于你在继续往下看之前先判断这篇文章的方法适不适合你的场景。能力项说明项目主题AI 编程实战COLA 状态机 Claude Code 的 MVP 开发流程状态机组件cola-statemachine阿里巴巴 COLA 系列组件之一AI 编程工具Claude CodeAnthropic 官方命令行编程助手核心价值先把状态转移矩阵设计好再让 AI 按模型生成代码减少上下文混乱和反复修改本地显存要求不依赖本地 GPUClaude Code 的推理发生在云端本地以 Node.js 进程运行支持平台macOS / Linux / WindowsWindows 推荐使用 WSL使用 Node.js 环境主要功能状态机建模、事件流转、条件动作绑定、AI 代码生成、CLI 交互、非交互批处理API 能力Claude Code 提供命令行交互与非交互模式也可以配合 Anthropic API/SDK 做接口集成批量任务可通过命令行脚本批量生成状态机代码、批量编译与测试适合场景订单、审批流、工单、发布流程等状态明确的业务系统 MVP从表里可以看出来这套方法的重心不在“显存够不够跑模型”而在“能不能把 AI 编程的工作边界锁住”。Claude Code 负责写代码cola-statemachine 负责教业务系统怎么定义和收敛状态流转。2. 适用场景与使用边界这套方法最适合的状态很明确业务逻辑里存在明确状态机例如订单从待支付到已完成、审批流从待审核到已驳回、工单从待处理到已关闭。这类系统的核心难点不是界面而是状态流转不能被绕过、不能被随意跳转。状态机天然适合描述这些问题而 Claude Code 在给定模型约束后生成的代码比完全自由发挥时要稳定得多。具体来说COLA 状态机 Claude Code 的组合能解决三个问题。第一业务规则前置状态、事件、条件、动作在设计阶段就写清楚AI 生成代码时不需要猜业务。第二上下文可持续把状态矩阵写进项目记忆文件后Claude Code 新开会话也能找回项目约定不用每次重新讲一遍需求。第三测试可核对状态机每个跳转都是独立用例AI 生成的代码能不能用跑一遍单测就知道。但这不是万能模板。如果你在写一次性脚本、纯算法原型、强视觉交互页面或者业务状态本身很模糊那么引入状态机反而会增加成本。这类场景更适合让 Claude Code 直接自由探索而不是先套一个模型。使用边界方面必须强调合规。Claude Code 是云端推理工具本地文件内容可能作为上下文发送到服务端所以不要往里塞密钥、令牌、客户隐私数据也不要把没有授权的外部代码丢进去让 AI 改写。涉及商用代码生成时要确认你拥有使用 AI 生成结果的授权。本地方案虽然不消耗 GPU但数据安全意识和代码审核流程不能省。3. 环境准备与前置条件在开始之前先把环境准备好。这套流程涉及两个技术栈Claude Code 需要 Node.js 环境cola-statemachine 是 Java 组件所以还需要 JDK 和 Maven/Gradle。建议先执行以下命令检查环境node -v npm -v java -version mvn -v检查时注意几点Node.js 建议安装 18 或 20 的 LTS 版本。Claude Code 通过 npm 全局安装Node 版本太低会导致安装或启动失败。JDK 建议 8 或以上。cola-statemachine 是运行在 JVM 上的状态机组件项目本身是 Java 工程。Maven 或 Gradle 至少要有一个可用。本文示例使用 Maven但 Gradle 也完全可以。网络方面需要确认当前环境能够访问 Claude Code 官方服务。如果你处在服务不可用的地区需要先解决网络访问路径或者在配置层面接入合规的兼容网关这一步必须在项目启动前处理好。准备一个空项目目录本文中统一叫order-mvp。建议先建一个干净的 Git 仓库方便观察 Claude Code 每次修改的差异。另外如果你习惯在 VS Code 里开发可以打开项目根目录后直接使用集成终端执行 Claude Code 命令它会把当前目录当作工作区读取项目上下文。社区里也有人用 cc-switch 这类工具在 VS Code 中切换不同的模型供应商配置后面讲最佳实践时再展开。4. 安装部署与启动方式4.1 安装 Claude Code 并完成登录Claude Code 是 Anthropic 推出的命令行编程助手安装入口是 npm 全局包。打开终端执行以下命令npm install -g anthropic-ai/claude-code安装完成后先验证版本再进入交互界面claude --version claude首次启动时Claude Code 会引导完成登录。你可以选择用 Claude 账号登录也可以配置 API Key 方式。具体选择哪种以你当前的账号权限为准只要能看到交互提示符就说明启动成功。进入交互界面后Claude Code 会读取当前目录作为项目上下文。它会请求读写文件、执行命令的权限终端里通常可以用数字键或 Tab 键快速选择允许或拒绝。如果你在搜索资料时见过 “claude code 1 2 3 tab approve” 这类描述说的就是这个交互过程。具体按键布局因版本而异启动后按提示操作即可。4.2 初始化 order-mvp 工程并引入 cola-statemachine在继续之前先在order-mvp目录下初始化一个基础的 Maven 工程。这里不贴完整 pom只给出引入 COLA 状态机需要关注的核心依赖dependency groupIdcom.alibaba.cola/groupId artifactIdcola-statemachine/artifactId !-- 版本号以 Maven Central 最新稳定版为准 -- /dependency如果你用的是 Gradle对应依赖写法如下implementation com.alibaba.cola:cola-statemachine:版本号以官方最新发布为准原因很简单cola-statemachine 作为开源组件会持续更新写死一个不确定的版本号没有意义。实际引入时去 Maven Central 查一下最新版本即可。第一次建议先引入并编译一次确认依赖能正常下载。初始化完成后把项目结构整理成下面这个样子后续代码都放在对应位置order-mvp ├── pom.xml ├── CLAUDE.md └── src/main/java/com/example/order ├── OrderState.java ├── OrderEvent.java ├── OrderContext.java ├── OrderStateMachineConfig.java └── OrderService.java这里多了一个CLAUDE.md这是给 Claude Code 看的项目记忆文件。它会在每次会话中自动被读取相当于给 AI 编程工具一个稳定的上下文底座。我们会在第 5 节具体说明里面该写什么。5. 功能测试与效果验证5.1 先做 MVP整理状态转移矩阵很多人在这一步跳过直接让 Claude Code 生成代码这是 AI 编程最容易翻车的地方。MVP 的“产品”不是代码而是一张状态转移矩阵。矩阵里写清楚当前状态、触发事件、满足条件、执行动作、目标状态。这张表就是后续所有代码的约束。以订单系统为例先定义 6 个状态和 6 个事件状态待支付、已支付、已发货、退款中、已完成、已取消事件支付成功、取消订单、发货、确认收货、申请退款、退款完成状态转移矩阵如下当前状态触发事件条件动作目标状态待支付支付成功金额 0扣库存、创建物流单已支付待支付取消订单用户发起执行退款已取消已支付发货库存和地址校验通过更新物流单已发货已发货确认收货物流完成完成结算已完成已发货申请退款平台规则允许冻结货款退款中退款中退款完成校验通过原路退款已取消这张矩阵就是整个 AI 编程任务的 MVP。不要急着让 Claude Code 生成接口先确认状态之间没有遗漏、没有非法跳转。矩阵里没有出现的路径例如已取消订单再发货就应该在代码中被禁止。5.2 定义状态和事件枚举矩阵确认后第一步代码非常简单把状态和事件翻译成枚举。这两段代码建议直接手写因为它是整个状态机的地基交给 AI 反而可能出现枚举命名不一致的问题。public enum OrderState { WAIT_PAY, PAID, SHIPPED, REFUNDING, COMPLETED, CANCELED }public enum OrderEvent { PAY_SUCCESS, CANCEL, SHIP, CONFIRM_RECEIPT, APPLY_REFUND, REFUND_SUCCESS }同时定义一个上下文对象用来在状态流转过程中传递参数比如金额、物流单号、用户信息等。它由业务服务创建每次 fireEvent 时传入状态机。5.3 用 cola-statemachine 把流转变成代码接下来是核心部分把状态转移矩阵翻译成 cola-statemachine 的 builder 代码。以“待支付 - 已支付”和“待支付 - 已取消”两条流转为例StateMachineBuilderOrderState, OrderEvent, OrderContext builder StateMachineBuilderFactory.create(); builder.externalTransition() .from(OrderState.WAIT_PAY) .to(OrderState.PAID) .on(OrderEvent.PAY_SUCCESS) .when(ctx - ctx.getAmount() 0) .perform(ctx - System.out.println(扣减库存创建物流单)); builder.externalTransition() .from(OrderState.WAIT_PAY) .to(OrderState.CANCELED) .on(OrderEvent.CANCEL) .when(ctx - true) .perform(ctx - System.out.println(执行退款流程)); StateMachineOrderState, OrderEvent, OrderContext stateMachine builder.build(orderStateMachine);不同版本的 COLA 状态机 API 可能略有差异实际使用以你引入版本的源码注释和StateMachineBuilderFactory提供的接口为准。这段代码的核心价值是每一条业务规则在代码里都有独立位置后续 AI 加逻辑时不会散落得到处都是。5.4 让 Claude Code 在约束下生成代码状态机配置完成后才是 Claude Code 正式上场的时候。在项目根目录的终端里启动claude然后粘贴下面这段提示词项目是 order-mvp技术栈 Java Maven cola-statemachine。 CLAUDE.md 中已经定义了状态矩阵和项目规范。 请在 src/main/java/com/example/order 下完成 1. 实现 OrderService对外提供状态流转入口 2. 为每个 transition 补充日志记录 3. 不要新增矩阵之外的状态和跳转路径 4. 完成后列出你修改的文件清单。注意提示词的第一要求不是“生成华丽代码”而是“锁定边界”。Claude Code 会读取项目文件在写文件、执行命令前请求授权。你批准后它会基于现有代码生成 OrderService。如果 Claude Code 开始增加矩阵里没有的状态或者自己发明跳转路径要立刻让它停下来回到 5.1 节的矩阵重新确认。这一步是 AI 编程实战里最重要的纠偏动作。5.5 用单元测试验证状态流转AI 生成的代码能不能用最终以测试结果为准。为状态机补一个核心测试用例验证“待支付 - 已支付”这条流转Test void should_pay_success_move_from_wait_pay_to_paid() { OrderContext ctx new OrderContext(); ctx.setAmount(100); StateMachineOrderState, OrderEvent, OrderContext sm OrderStateMachineConfig.build(); OrderState target sm.fireEvent(OrderState.WAIT_PAY, OrderEvent.PAY_SUCCESS, ctx); assertEquals(OrderState.PAID, target); }预期结果很明确合法流转返回目标状态非法流转应该抛出异常或停留在原状态。判断标准就看测试是否通过。如果测试失败优先检查三处when条件是否满足、Event枚举是否和矩阵一致、transition是否在 builder 中注册。6. 接口 API 与批量任务6.1 Claude Code 非交互模式Claude Code 不只支持交互式对话还提供非交互模式。常见调用方式是通过claude -p传入一条指令适合脚本化和 CI 集成。具体参数以claude --help输出为准下面是一个使用示例claude -p 只读取 src/main/java/com/example/order 目录检查 OrderStateMachineConfig 中是否缺少 WAIT_PAY - PAID 的 transition如果有就补上并输出补丁说明。这种模式适合任务边界清晰、结果可校验的场景。比如让 AI 检查枚举遗漏、补全日志、生成指定状态的测试用例。大范围重构不建议使用非交互模式因为缺少人工确认AI 一旦理解偏差可能直接改写整份文件。6.2 批量生成状态机代码的脚本如果你的项目里存在多个业务模块每个模块都需要一套状态机可以把非交互模式套进脚本。下面是一个通用模板#!/usr/bin/env bash # 批量生成多个模块的状态机代码实际路径按项目结构调整 for module in order payment refund; do claude -p 在 ${module}-mvp 项目中按照 CLAUDE.md 中定义的状态矩阵生成状态机配置代码不新增矩阵之外的状态。 if [ $? -ne 0 ]; then echo 模块 ${module} 执行失败 exit 1 fi done这个脚本的逻辑是每个模块独立执行一次生成任务失败则立即退出并打日志。批量任务最重要的是可观测性和失败重试不能把多次任务堆在一个会话里跑完否则失败时很难定位。6.3 状态机服务的 HTTP 接口当状态机落地为业务服务时Controller 层会变得很薄。因为业务动作都已经定义在状态机里接口只需要接收事件、加载上下文、触发流转。典型的 Spring Boot 接口示例PostMapping(/orders/{id}/events) public OrderEventResult fire(PathVariable Long id, RequestBody FireEventRequest req) { OrderContext ctx orderRepository.loadContext(id); OrderState next stateMachine.fireEvent(req.getCurrentState(), req.getEvent(), ctx); return new OrderEventResult(next); }请求体只需要包含当前状态和触发事件目标状态由状态机决定。这样 Claude Code 在生成这类接口时很难跑偏因为业务判断逻辑已经前置到了状态机配置里。7. 资源占用与性能观察Claude Code 是终端应用运行依赖是本地的 Node.js 进程。它不调用本地 GPU也不占显存推理发生在云端。本地观察资源占用时重点看两个方向终端进程的内存消耗和 Anthropic API 侧的 token 消耗。先说本地进程。Claude Code 在做文件读取、编辑时 CPU 会有短时间上升但整体内存占用通常不高。如果你发现终端响应变慢先检查是否有多个claude进程同时堆积再用任务管理器或top命令按内存排序定位进程。再说 token 消耗。这是实际使用中更值得关注的成本。结合社区反馈以下几类任务通常消耗较大把多个大文件反复塞进上下文进行全文重写新开会话后重新描述一遍完整需求而不是让项目记忆文件提供上下文每次修改都让 AI 输出整个文件而不是精确的 diff 补丁会话不清理、上下文越滚越长继续追问也导致消耗上升。想控制成本核心思路是减少无效往返。状态机先建模的价值在这里会体现得非常直接矩阵固定后AI 不会因为需求理解偏差反复猜代码修改次数明显下降。此外把项目规范写进 CLAUDE.md让新开会话也能读取约定这是解决“新开会话丢失上下文记忆”问题的标准做法。8. 常见问题与排查方法AI 编程工具在实际使用中一定会遇到各种环境问题。下面这张表整理了 Claude Code 和状态机使用过程中的常见异常供你排查时参考。问题现象可能原因排查方式解决方案error: claude code process exited with code 3Node 版本不兼容或依赖损坏先执行claude --version确认能否启动升级 Node 到 LTS 版本重装npm install -g anthropic-ai/claude-codelatest模型名报错例如提示 model 不被当前版本识别Claude Code 版本过旧或供应商模型名配置错误检查 CLI 版本和模型配置项升级 Claude Code或按网关文档核对模型名提示 organization 已禁用 claude subscription access组织策略限制订阅访问检查账号权限联系管理员开通或改用 API Key 方式提示当前地区可能不可用官方服务支持范围限制确认网络环境可访问官方服务通过合规网关或兼容 API 供应商接入新开会话后 AI 忘记项目需求缺少持久化上下文检查项目根目录是否存在 CLAUDE.md把技术栈、状态矩阵、包结构写进 CLAUDE.md状态机 transition 不生效条件判断失败或事件未注册检查 when 条件、Event 枚举、builder 注册代码在对应 transition 加日志跑单测定位批量任务卡住或静默失败prompt 边界不清晰或等待授权查看会话日志确认是否有未批准的权限请求改用非交互模式并加入超时和失败重试API 调用失败网络异常、Key 无效或配额不足检查环境变量、网络连通性、账号配额修复网络配置轮换 Key 或提升配额这个表无法覆盖所有情况但思路是一致的先确认环境再确认版本最后确认配置。遇到 AI 编程工具报错时不要立刻重装先用--version和日志定位问题范围。9. 最佳实践与使用建议到这里整套流程已经跑通。接下来是一些实际项目中值得坚持的习惯。第一先画状态转移矩阵再让 AI 动手。这一步是整套方法的灵魂。矩阵不完整时生成的代码再华丽也是空中楼阁。建议把矩阵直接维护在项目文档里状态机和文档保持同步。第二维护好 CLAUDE.md。Claude Code 会把根目录的 CLAUDE.md 当作长期记忆所以里面应该写清楚技术栈、包结构、状态枚举、关键矩阵。这样即使新开会话AI 也能快速回到正确上下文。第三一次只改一个状态。让 Claude Code 小步修改一次只新增一条 transition然后跑测试再继续下一条。不要在一轮会话里让它一次性把所有功能写完否则出了问题很难定位是哪个状态的逻辑写错了。第四批量任务必须加日志和失败重试。使用非交互模式批量生成代码时每个任务都要记录退出码和输出文件失败后要能单独重跑不能全班重来。第五敏感信息不进 prompt。不要往 Claude Code 会话里贴生产密钥、内部令牌、客户隐私数据。AI 编程工具是把上下文发送到云端后推理的这个边界必须严格遵守。第六结合 DDD 思维组织业务。状态机可以看作聚合根的行为模型。让 Claude Code 生成 OrderService 时如果它有 DDD 基础生成出来的领域对象和仓储接口会更清晰。这就是为什么社区里“DDD 领域驱动设计和 AI 编程的结合”会被反复讨论——AI 生成代码不是没有章法而是需要人类提供领域模型约束。第七多供应商切换要谨慎。把 Claude Code 接到第三方模型或兼容网关时常见做法是用 cc-switch 这类工具管理配置然后在 VS Code 中切换后重启会话。切换后遇到模型名不识别的问题先检查版本兼容性再检查配置的模型标识。这个流程在不同供应商之间差异较大具体以对应工具文档为准。10. 总结与下一步这套流程最值得尝试的点是给 AI 编程加了一个“行为边界”Claude Code 依然负责写代码但写什么、怎么跳转由状态转移矩阵控制。你最先应该验证的就是一个订单状态机6 个状态、6 个事件、6 条流转全部跑通单测后再扩展。最容易踩的坑是不建矩阵直接生成。一旦 AI 开始自由发挥状态跳转后续所有维护成本都会爆炸。第二个容易踩的坑是不维护 CLAUDE.md导致新会话丢失上下文重复劳动。如果你已经跑通了订单 MVP下一步可以这么走把状态矩阵和项目规范沉淀进 CLAUDE.md然后试着让 Claude Code 在 CI 中非交互式补全测试用例接着研究 Claude Code Skills把常用提示词固化成可复用技能。如果有多套模型供应商需求再研究 cc-switch 这类配置管理工具并严格核对模型名与 Claude Code 版本的兼容性。方法不复杂但顺序很重要先用状态机把边界固定住再让 Claude Code 动手你会在下一个 MVP 里明显感受到差别。