实际使用 Claude Code、Cursor 这类 AI 编程工具时最常遇到的问题并不是模型不会写代码而是开发者自己还没想清楚要做什么。需求越模糊AI 就越容易生成“看起来能用、一改就塌”的代码。本文要讨论的不是某个具体 API 的用法而是一条完整实践路径在 AI 编程进入编码之前先用 COLA 架构思想把系统边界划定再用 MVP 方法把需求收敛到最小可交付闭环最后才让 Claude Code 在这个约束明确的框架里生成代码。这条路径适合正在尝试把 AI 编程引入日常开发、但发现 AI 产出不稳定、返工率偏高的团队和个人开发者。1. 为什么 AI 编程的第一步不是写代码1.1 AI 编程的主要矛盾已经从“代码生成”转移到“需求约束”很多团队引入 AI 编程工具时第一反应是拿它加速写代码。但经过一段时间实践会发现真正制约产出的环节已经从键盘速度变成了需求质量和架构约束。一个没有背景说明、没有模块边界、没有验收标准的提示词到了 Claude Code 手里它会大胆地替你补全所有缺失假设。这些假设大部分时候和你的真实业务不一致等代码生成出来你需要花大量时间去做修改和返工。可以把不同提示词形式下的 AI 产出质量放在一起对比。提示词形式AI 产出表现返工风险“帮我写一个订单系统”生成大量类业务假设全来自模型默认理解高“按 COLA 分层创建订单模块提供下单接口不接数据库”结构受控范围受控代码量适中中需求文档 MVP 范围 分层边界 验收标准每段代码对应明确需求项后续可改可测低所以“AI 编程别急着写代码”真正的意思是在打开编辑器、输入提示词之前先把需求和结构两条线定下来。代码生成本身已经不再是瓶颈瓶颈是给模型的信息质量。1.2 直接让 Claude Code 写代码会发生什么先描述一个典型现象。让 Claude Code 直接实现“用户下单”这个功能它可能会同时生成实体类、枚举、工具类。数据库表结构和 JPA 或 MyBatis 映射。REST 控制器和 DTO。订单状态流转逻辑。事务和异常处理。看起来功能完整但问题也随之出现。你只想要一个 MVP 验证业务流程它却默认加上了缓存、消息队列、权限校验、分页等功能这些并不属于当前闭环。它还会基于自己的训练经验选择技术组合不一定符合你项目的现有规范。更麻烦的是一旦需求调整这些“多余能力”和“错误假设”交织在一起改动成本远比从零手写要高。这并不是 Claude Code 能力不行而是提示词里缺少三样东西需求范围、架构约束、验收标准。工具越强输入的质量就越决定输出的上限。1.3 正确顺序MVP 收敛需求COLA 划定边界AI 负责实现推荐的实践顺序是先用 MVP 方法定义“最小可交付闭环”。明确用户角色、核心动作、核心数据和验收标准。再用 COLA 架构或类似的清晰分层思想定义代码边界。哪怕只建空目录也要让 AI 知道每一层放什么。最后才进入编码阶段把每一条需求拆成 Claude Code 可以独立执行的子任务。每完成一个子任务运行验证并把这个结果反馈给 AI作为下一个任务的前置上下文。这样 AI 编程就从“猜测你的意图”变成了“执行已经清楚定义的任务”产出质量会稳定很多。这也是本文整条技术主线的核心先想清楚再让 AI 动手。2. Claude Code 环境准备与基本用法2.1 Claude Code 是什么它解决什么问题Claude Code 是 Anthropic 推出的命令行 AI 编程代理。它可以读取项目文件、执行命令、创建和修改代码并在会话中持续跟进任务。与聊天式 AI 工具的区别在于它被设计成“住在项目里”的工具能感知当前目录结构和文件内容更适合完成实际开发任务。它解决的核心问题是让 AI 从“回答问题”变成“做事情”。这带来开发效率的提升但也要求使用者在会话开始前就把项目背景、技术规范和任务目标写清楚否则它会把“做事情”变成“自由发挥”。Claude Code 本身并不理解你团队的分层约定它只理解你写在 CLAUDE.md 和提示词里的规则。2.2 安装、登录与常见前置检查常见安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后执行claude首次运行需要登录账号并确认订阅方案对 Claude Code 的访问权限。如果组织账号策略限制运行时会提示your organization has disabled claude subscription access for Claude Code这时候需要联系团队管理员开启访问权限而不是绕过限制。注意安装前先确认 Node.js 版本满足 Claude Code 的要求常见要求是 Node.js 18 及以上。版本不匹配时可能出现安装后无法启动的问题。在 VS Code 中也可以安装 Claude Code 扩展通过编辑器侧边栏直接打开会话。命令行和编辑器两种方式底层走的是同一套能力选择哪种主要看个人习惯。实际项目里命令行适合快速执行任务编辑器集成适合边看代码边修改。2.3 CLAUDE.md项目的长期上下文Claude Code 会读取项目根目录下名为CLAUDE.md的文件把它当作项目的长期说明。这个文件非常适合存放四类信息项目技术栈和目录结构。代码风格约定。构建、测试、运行命令。团队约定的架构规则。例如一个 Java 项目可以这样写# 项目说明 本模块采用 COLA 分层的简化结构 - 适配层: controller 包只负责参数接收和响应封装 - 应用层: service 包负责用例编排和事务边界 - 领域层: domain 包负责核心业务逻辑 - 基础设施层: infrastructure 包负责数据库、缓存等外部依赖 代码风格 - 方法名使用驼峰命名 - 禁止在 controller 中写业务逻辑 - 所有对外接口返回统一 Result 结构 常用命令 - 构建: mvn clean package - 测试: mvn test这个文件的作用是让每一个新会话都能继承项目约定减少每次对话前重复交代背景的成本。它也是解决 AI 编程“会话切换丢失上下文”问题的最基础手段。2.4 用最小命令跑通一次生成在项目目录下启动会话cd /path/to/project claude在会话中输入类似下面的指令在当前项目 src/main/java 下创建一个 COLA 分层目录结构 包括 adapter、app、domain、infrastructure 四个包包名前缀 com.example.order。 每个包先只放一个包说明类暂时不写业务代码。这条指令明确给出了路径、结构、包名和范围Claude Code 生成的代码更可控。生成完成后用下面命令检查目录find src/main/java -type f | sort如果目录结构符合预期说明这一轮的任务定义是有效的。如果不符合不要急着继续生成业务代码先修正目录结构或 CLAUDE.md因为后续所有任务都依赖这个基础。3. COLA 架构AI 生成代码的边界护栏3.1 COLA 是什么为什么和 AI 编程有关COLAClean Object-oriented and Layered Architecture是阿里开源的整洁面向对象分层架构核心思想是让业务代码与技术实现解耦通过清晰的分层让系统更容易理解和演进。对于 AI 编程而言COLA 的价值不是理论层面的“优雅”而是实操层面的“约束”。AI 模型在没有约束时倾向于把代码写成一个大杂烩控制器里写数据库查询、工具类里藏业务逻辑、实体直接暴露给前端。COLA 分层之后模型每生成一段代码都能明确知道它属于哪一层、能依赖谁、不能依赖谁。约束越清楚模型的默认行为越接近团队规范。3.2 四层结构与依赖方向COLA 的经典分层可以理解为四层实际项目中常会做裁剪。层名主要职责典型包或目录允许依赖适配层接收外部输入处理 HTTP、DTO、Controlleradapterapp 层应用层用例编排、事务、参数校验app/servicedomain 层领域层核心业务规则、实体、领域服务domain基础设施层接口基础设施层数据库、缓存、外部服务实现infrastructure无上层依赖在 MVP 阶段不需要把 COLA 全部机制都引进来。可以只保留分层目录和依赖方向让 AI 生成代码时遵循“controller 不写业务、service 编排用例、domain 放核心逻辑、infrastructure 处理技术细节”这条规则就已经能避免大量结构性问题。3.3 为什么分层约束能提升 AI 生成质量原因在于 AI 生成代码时上下文越清晰决策质量越高。COLA 分层的目录结构本身就是一种强上下文。当提示词里出现“请在 app 层实现下单用例”时模型会下意识选择创建 service 类、调用 domain 层接口、在方法上标记事务注解而不是把所有代码塞进 controller。反过来如果提示词只说“实现下单”模型就需要自己决定类放在哪里、数据库怎么访问、请求怎么接收选择一多出错概率就成倍上升。这等于把架构师的经验固化成了 AI 可以读取的约束文件。即使开发者没有为每个类写详细设计只要分层和依赖方向清楚了AI 的默认行为也会更接近工程规范。3.4 MVP 阶段不需要完整落地 COLA强调一点MVP 阶段不要为了架构而架构。一个最小闭环可能只有几个类和一张表这时候引入整套 COLA 的扩展点反而会增加复杂度。推荐做法是“分层意识先行、完整机制后补”MVP 阶段建立 controller、service、domain、infrastructure 四个包结构。在 CLAUDE.md 中写清楚依赖方向和典型职责。让 Claude Code 严格按分层生成代码。等到业务复杂度上升、多个模块出现公共逻辑时再逐步引入资源库抽象、领域事件、扩展点等 COLA 完整机制。这样既能享受分层约束带来的稳定产出又不会让 MVP 变成重流程的样板工程。4. 先做 MVP需求收敛和任务拆分4.1 MVP 不是功能阉割而是最小可交付闭环很多团队把 MVP 理解为“少做功能”这是片面的。MVP 的核心是找到一条能验证业务假设的最小路径它必须是一个闭环而不只是一堆删减后的碎片。以一个电商订单模块为例错误理解MVP 就是不做支付、不做物流、不做售后先写个下单接口。正确理解MVP 是“用户选商品 - 提交订单 - 校验库存 - 扣减库存 - 生成订单记录”这个完整闭环其他非核心功能先不进入范围。这个闭环的价值在于它包含了输入、业务规则、数据持久化和输出可以完整验证系统骨架和业务流程。AI 在这个闭环内生成的代码既能跑通又能暴露出架构和接口设计问题。闭环保留得越完整验证越有效。4.2 用用户故事和验收标准代替模糊描述给 AI 的需求描述不建议写成大段散文建议使用结构化格式例如用户故事加验收标准用户故事 作为一个消费者 我希望提交订单时系统能校验库存并扣减库存 以便我完成购买。 验收标准 - 库存充足时订单状态为已创建库存数量减少对应购买数量 - 库存不足时下单失败返回明确错误信息库存不变 - 订单数据写入数据库包含用户 ID、商品 ID、数量、状态、创建时间这种格式对 AI 非常友好因为每一条验收标准都可以直接映射到测试用例或代码逻辑减少歧义。注意验收标准要写“可观察、可验证”的行为不要写“性能好、代码规范”这类无法自动判断的表述。4.3 把 MVP 拆成 AI 可执行的任务清单一个完整的 MVP 往往包含多个步骤不要一次性塞给 Claude Code。推荐按任务粒度拆分任务编号任务内容输出T1创建项目结构和分层目录目录、pom.xmlT2实现领域层订单实体和库存校验规则Java 类、单元测试T3实现基础设施层数据库访问Repository、SQLT4实现应用层下单用例编排Service 类T5实现适配层下单接口Controller、DTOT6编写集成测试并跑通闭环测试报告每个任务完成后立即验证再进入下一个任务。这样可以避免 AI 在一次生成长任务时产生大量错误假设也让排错范围从“整个项目”缩小到“当前任务”。这个拆分方式也是 AI 编程实践中最值得养成的习惯。4.4 给 AI 的上下文颗粒度给 Claude Code 的上下文不需要面面俱到但要包含四类信息项目背景这是什么系统为什么做用户是谁。技术约束语言、框架、构建工具、数据库、包名。架构约束分层结构、依赖方向、统一返回结构。范围约束本次任务包含什么明确不包含什么。其中“明确不包含什么”最容易遗漏却最重要。AI 一旦不知道边界就会自行扩大范围生成一堆不属于 MVP 的代码。例如可以明确写“不引入缓存组件”“不做登录鉴权”“不创建测试数据之外的表”模型就不会往那个方向扩展。5. 实战用 COLA 加 Claude Code 完成一个订单 MVP5.1 业务场景和 MVP 范围定义下面用一个最小订单场景演示完整流程。技术栈选择 Spring Boot 3、Java 17、Maven为了演示保持精简。业务范围是用户提交订单系统校验商品库存校验通过后生成订单并扣减库存。MVP 明确不包含不做用户登录和权限。不做支付。不做订单状态流转的复杂状态机。不做消息队列和缓存。这个范围足够小却覆盖了“外部请求 - 应用服务 - 领域规则 - 持久化”的完整链路。5.2 目录结构设计按 COLA 简化分层目录结构如下order-demo ├── pom.xml ├── CLAUDE.md └── src/main/java/com/example/order ├── adapter │ └── web │ ├── OrderController.java │ └── dto │ ├── CreateOrderRequest.java │ └── CreateOrderResponse.java ├── app │ └── service │ └── OrderServiceImpl.java ├── domain │ ├── model │ │ ├── Order.java │ │ ├── OrderItem.java │ │ └── enums │ │ └── OrderStatus.java │ ├── repository │ │ ├── OrderRepository.java │ │ └── ProductRepository.java │ └── service │ └── InventoryService.java └── infrastructure ├── persistence │ ├── OrderRepositoryImpl.java │ └── ProductRepositoryImpl.java └── config └── DatabaseConfig.java这个结构不是 COLA 的完整形态但已经具备“适配层、应用层、领域层、基础设施层”的基本边界。AI 生成代码时可以明确知道每个类的归属。5.3 给 Claude Code 的工单示例在 CLAUDE.md 中写入项目说明后会话中提交第一个任务时可以这样描述工单 T1 在目录 order-demo 中初始化 Spring Boot 3 Java 17 的 Maven 项目。 依赖只保留 spring-boot-starter-web、spring-boot-starter-data-jpa、h2、 lombok、spring-boot-starter-test。 同时创建 COLA 分层目录 com.example.order.adapter.web com.example.order.app.service com.example.order.domain.model com.example.order.domain.repository com.example.order.domain.service com.example.order.infrastructure.persistence 不要创建其他配置文件和业务代码。这条指令的优点是依赖范围明确目录明确还明确说了“不要创建其他内容”。范围约束写得越清楚AI 越不会自由发挥。5.4 核心层代码生成要点第二批任务是生成核心代码。以领域层为例工单可以这样写工单 T2 在 com.example.order.domain.model 下实现 1. Order 实体字段包括 id、userId、status、totalPrice、createTime、items。 2. OrderItem 实体字段包括 id、productId、quantity、price。 3. OrderStatus 枚举枚举值 CREATED、PAID、CANCELLED。 在 com.example.order.domain.service 下实现 InventoryService 接口 CheckResult checkStock(Long productId, Integer quantity); void deductStock(Long productId, Integer quantity); 领域层不依赖 Spring Data不使用任何注解。这里刻意强调“领域层不依赖 Spring Data”是为了让 AI 生成的领域对象保持技术无关这也是 COLA 架构的关键实践。领域层一旦被 JPA 注解、Spring Bean 注解污染后续做单元测试和架构调整都会很吃力。应用层负责用例编排工单 T4 在 com.example.order.app.service 下实现 OrderService 接口和 OrderServiceImpl。 OrderServiceImpl 负责下单用例编排 1. 根据商品 ID 查询商品。 2. 校验库存。 3. 创建订单和订单项状态为 CREATED。 4. 调用库存服务扣减库存。 5. 保存订单。 事务边界放在应用层使用 Transactional。 不在应用层写 SQL不直接操作数据库。适配层只做接口暴露工单 T5 在 com.example.order.adapter.web 下实现 OrderController。 提供 POST /api/orders 接口接收 CreateOrderRequest 调用应用层 OrderService 下单返回 CreateOrderResponse。 Controller 中不写业务逻辑只做参数接收、调用和响应封装。每个工单都限制了任务边界和代码归属层Claude Code 在单点任务上的表现会稳定很多。5.5 运行验证与预期结果全部任务执行完毕后运行项目mvn spring-boot:run在另一个终端调用下单接口curl -X POST http://localhost:8080/api/orders \ -H Content-Type: application/json \ -d {productId:1,quantity:2,userId:100}预期看到返回结果{ orderId: 1, status: CREATED, message: 下单成功 }再验证库存不足场景curl -X POST http://localhost:8080/api/orders \ -H Content-Type: application/json \ -d {productId:1,quantity:9999,userId:100}预期返回明确错误信息且订单不落库。这两个测试分别覆盖了正常分支和异常分支是 MVP 闭环验证的基本要求。注意不要只验证程序能启动还要验证正常输入、异常输入和数据库状态是否符合预期。只有启动成功但接口行为错误的项目在 AI 编程场景里非常常见。6. 常见问题与排查路径6.1 Claude Code 安装、版本与账号问题Claude Code 常见问题集中在这几类问题现象常见原因检查方式处理建议安装后执行 claude 提示命令不存在npm 全局目录不在 PATH执行 npm config get prefix把全局 bin 目录加入 PATH启动时提示模型版本不识别客户端版本和模型配置不一致执行 claude --version 确认版本更新 Claude Code并检查模型配置是否指向受支持版本提示组织禁用访问组织账号未开放 Claude Code 权限查看完整提示文本联系团队管理员开启权限不要绕过限制提示区域不可用当前环境不在支持范围内结合部署环境判断确认部署环境支持情况不要尝试绕过限制npm 安装缓慢或失败网络或 registry 配置问题检查 npm config get registry切换为团队维护的镜像源后重试排查顺序建议从输入命令是否正确开始再检查路径和权限然后看版本和配置最后看网络环境。不要一上来就认为模型能力有问题。6.2 新开会话丢失上下文记忆这是 AI 编程工具最常见的困扰之一。Claude Code 的上下文保存在会话内新建会话后之前的对话内容不会自动继承。解决办法不是让工具记住而是把关键信息外置化把项目技术栈、架构规则、常用命令写入 CLAUDE.md。把当前任务拆成工单并在每个工单描述中写明前置任务编号。关键决策写进项目的设计文档目录作为后续会话的输入。这样即使会话中断也能在新会话中快速恢复上下文。把这个机制理解成“给 AI 写交接文档”而不是依赖模型记忆。6.3 Token 消耗过大AI 编程工具消耗大量 token 通常有三种原因一次交给模型的任务范围过大让它反复生成和回退。项目文件太多模型每次读取上下文都非常昂贵。会话中反复让模型重新读文件、重新生成。对应处理方式任务拆小一次只完成一个可验证单元。在 CLAUDE.md 中明确告诉模型忽略哪些目录例如 target、node_modules、build。频繁使用新会话并结合 CLAUDE.md 重建上下文。在提示词中限制输出范围例如“只输出 Java 代码不输出解释”。其中“不输出解释”对控制 token 消耗非常有效因为模型默认会输出大段说明文字。6.4 AI 生成代码不符合分层要求即使写了 CLAUDE.mdAI 仍可能在生成代码时越过边界例如在 Controller 里写业务逻辑。处理方式检查是否在任务描述中明确了该文件的层级归属。检查 CLAUDE.md 中的依赖方向是否被模型准确读取。让 AI 重新生成该文件并明确要求遵循分层规则。在代码评审阶段增加一条分层检查规则人工或脚本检查依赖方向。更推荐的做法是在工单描述中直接写“这个文件属于 domain 层禁止引用 Spring、禁止操作数据库”把约束前置到生成阶段而不是在生成后补救。7. 最佳实践与可复用检查清单7.1 需求文档检查清单[ ] 是否只有一个明确的用户角色和核心动作[ ] 是否每一条验收标准都可观察、可测试[ ] 是否明确本次包含的内容[ ] 是否明确不包含的范围[ ] 是否给出了输入输出样例需求文档是给 AI 的第一道约束这五项都满足后AI 的返工率会明显下降。7.2 任务拆分检查清单[ ] 每个任务是否有独立输出物[ ] 每个任务完成后是否能运行验证[ ] 任务之间是否有清晰的前置依赖关系[ ] 单个任务的控制范围是否足够小[ ] 是否避免了“一次性完成整个模块”的巨型任务推荐把任务控制在“一个文件或一组强相关文件”的粒度最坏情况也能快速定位问题。7.3 COLA 分层代码检查清单[ ] Controller 是否只做参数接收和响应封装[ ] Service 是否只做用例编排不写 SQL[ ] Domain 层是否保持技术无关不依赖 Spring Data[ ] Infrastructure 层是否实现了领域层定义的接口[ ] 依赖方向是否从外向内没有反向依赖[ ] 是否没有在工具类里堆积不属于当前用例的业务逻辑这六项可以做成人工评审模板也可以写成脚本检查 import 方向作为 AI 生成代码后的自动防线。7.4 从 MVP 走向生产环境MVP 跑通后进入生产环境前还需要补齐这些能力数据库连接池、日志、监控是否配置完整。异常处理是否区分业务异常和系统异常。是否补充了权限校验、请求限流、参数校验等安全能力。是否把配置外置化而不是硬编码在代码中。是否准备回滚方案和发布检查单。是否为核心流程补充了集成测试和回归测试。MVP 解决的是“业务闭环能否成立”生产化解决的是“系统能否稳定运行”。两者不要混在一起做这也是“先做 MVP”的另一个原因先解决正确性问题再解决健壮性问题。AI 编程的产出质量本质上由你给它的约束质量决定。COLA 提供架构约束MVP 提供范围约束CLAUDE.md 提供项目约定工单描述提供任务边界。四层约束叠加起来Claude Code 才能从“大胆猜测者”变成“可预期执行者”。下一步可以从两个方向扩展一是把订单场景升级为完整状态机引入 COLA 的状态机机制和领域事件二是把单模块的 MVP 实践复制到多个模块形成团队统一的 AI 编程协作规范。对新手来说最好的练习不是去研究更复杂的提示词技巧而是把一个非常小的 MVP按本文的工单方式完整跑一遍感受约束前后 AI 产出质量的差异。
