01-复杂项目用 AI 开发为什么总翻车?一套可复制的五步拆解法 + 原子化开发

113 阅读21分钟

复杂项目用 AI 开发为什么总翻车?一套可复制的五步拆解法 + 原子化开发

聚焦方法论核心——怎么把一个复杂项目拆成 AI 能稳定执行的标准化任务流,以及为什么原子化开发是最高效的执行模式。


一、先说痛点

你一定经历过这种场景:

一个项目功能模块十几个,接口几十个,状态枚举一堆,还要跨服务调用、兼容老代码。你想着"让 AI 来搞",结果——

  • AI 理解错需求,生成的逻辑南辕北辙
  • 漏掉边界条件,上线才发现各种异常没处理
  • 前后端数据对不上,联调时疯狂返工
  • 上下文一长,AI 开始"失忆",前面定的规则后面全忘

根本原因不是 AI 不行,而是你把一件它做不了的事丢给了它

复杂项目的核心矛盾:人擅长规划和决策,AI 擅长执行和重复——但大多数人直接把"规划"也甩给了 AI,然后指望它全包。这不叫协作,这叫许愿。


二、核心思想:人定边界,AI 做执行

一句话总结:

人来做:拆解复杂问题、划定边界、制定规则、做出关键决策。 AI 来做:根据明确的指令,快速生成代码、还原样式、编写重复逻辑。

先由人消化需求的复杂性,变成一套清晰的说明书,再把一条条明确的任务交给 AI 去实现。既避免 AI"瞎猜",又让它发挥最大效率。

这不是"AI 代替人",是"人做 AI 做不了的事,AI 做人不想做的事"。


三、三层分工:不同粒度,不同角色

"人定边界,AI 做执行"这句话听着简单,但很多人在实践时会困惑:到底哪一步该人来,哪一步该 AI 来?

答案取决于你在哪个粒度上工作。复杂项目的协作,天然分三层:

层级谁负责回答什么问题产出物
领域拆分人类大需求切成哪几个有界模块?各模块的 Scope 定义
宏观编排人类模块之间谁先谁后?何时能合?执行顺序、合并闸门、依赖关系
微观执行AI + 人 Review每个模块内部怎么实现?Code、Tests、Docs

领域拆分:人类的地盘

"这个项目要切成哪几块"——这是最核心的决策,必须由人来定。

为什么不能交给 AI?因为领域拆分需要对业务全局的理解、对团队能力的判断、对技术边界的把控。AI 不了解你的团队,不了解你的业务历史,不了解哪些模块之间有隐性的组织依赖。

比如博客项目,切成"内容消费 / 搜索发现 / 用户认证 / 互动功能"四个模块,这个决策必须由人来拍板。AI 可以建议,但不能做主。

宏观编排:人类的地盘

"这四个模块谁先做、谁后做、做到什么程度才能合到一起"——这也是人的决策。

宏观编排解决的是模块间的依赖和节奏问题:

  • 认证模块是其他模块的前置依赖,必须先做
  • 内容消费和搜索发现可以并行,但合并时需要校验数据接口一致性
  • 互动功能依赖认证和文章数据,放在后面

AI 不擅长这种跨模块的全局调度——它每次只看得到当前上下文,看不到"如果这个模块延后两周,另外两个模块的合并会不会出问题"。

微观执行:AI 主导,人 Review

"每个模块内部的代码实现"——这是 AI 的主战场。

到这个粒度,任务已经有了明确的输入(接口契约、DTO 规范、组件契约)和输出(代码、测试、文档),AI 可以高效执行。人只需要做 Review,确保产出符合预期。

三层分工的核心洞察:粒度越粗,人的决策权重越高;粒度越细,AI 的执行效率越高。

很多人翻车,是因为把"领域拆分"和"宏观编排"也交给了 AI——让一个只擅长微观执行的模型去做宏观决策,结果可想而知。


四、五步拆解法

三层分工告诉我们"谁做什么",五步拆解法告诉我们"怎么做"。下面用两个轻量案例贯穿讲解,都来自 Monorepo 全栈博客项目(React H5 前端 + NestJS 微服务后端):

  • 案例 A:点赞切换 — 用户点击红心,前端乐观更新,后端事务保证关系表和计数一致
  • 案例 B:Token 自动刷新 — 接口 401 时,axios 拦截器自动刷新 Token,用户无感知

Step 1:顶层业务域解耦——把大项目切成独立模块

对应三层分工中的领域拆分层,由人类决策。

不要一上来就让 AI 面对整个项目。先把项目按业务闭环维度切成独立、无强耦合的模块。

以博客系统为例:

模块核心职责独立性
文章内容消费首页列表、分类筛选、文章详情可独立开发
搜索发现关键词搜索、热门词UI 和逻辑独立
用户认证注册、登录、Token 刷新、登出完全独立的服务
互动功能点赞切换、点赞状态校正依赖文章和认证,但事务逻辑独立

为什么必须先切? AI 一次只能处理有限上下文。整个项目丢给它 → 上下文过载 → 逻辑混乱 → 输出不可控。切完后,AI 每次只聚焦一个模块,思维清晰,输出稳定。

Step 2:三大前置锚定——锁死硬约束,消除 AI 幻觉

对应三层分工中的宏观编排层,由人类定义模块间的规则和依赖。

每个模块开工前,必须先完成三件事,把所有"不能变的规矩"定死。

① 重要事项锚定:技术硬规范、第三方依赖参数、项目配置等不可修改的标准。

比如互动功能模块:

  • 点赞接口必须通过 RemoteJwtAuthGuard 获取 currentUserId禁止前端传 userId
  • ArticleLikesArticles.likes 必须在同一事务中更新
  • 前端 Token 使用 HttpOnly Cookie,禁止 localStorage 存储

② 影响面分析锚定:上下游依赖、数据流转规则、接口/枚举的影响范围。

比如认证模块:

  • Token 刷新涉及前端 axios 拦截器 → backend 代理转发 → auth-service 校验 → Redis 存储,整条链路必须提前理清
  • 多请求并发 401 时,只刷新一次,其他请求排队等待
  • 刷新失败需跳转登录页,并携带 redirect 参数

③ 边界规则锚定:触发条件、公用组件规则、禁止触碰的边界。

比如互动功能模块:

  • 未登录用户点击点赞 → 跳转登录页,不调用接口
  • 数据库字段下划线(cover_url),DTO 字段驼峰(coverUrl),禁止混用
  • password_hash 绝不出现在任何 DTO 中

三大锚定完成后,输出一份清单文档,AI 每次执行任务前都必须读取。这就是它的"行为边界"。

下一篇会展示这些锚定规则怎么沉淀为 .claude/rules/ 下的结构化文件(如 security-common.mdtypescript-common.md),从"人记得做"变成"系统强制加载"。

Step 3:模块内线性流程拆解——按开发流水线一步步走

对应三层分工中的微观执行层,AI 主导,人 Review。

模块内部的开发,拆成线性递进的子阶段:

阶段做什么谁主导
准备材料梳理接口入参/出参、枚举映射、mock 数据方案
静态页面还原设计稿结构、组件封装、样式实现AI 主导
动态功能接口对接、状态判断、事件处理AI 执行,人审核
上下游适配跨页面跳转、跨模块数据传递AI 执行,人审核
人工兜底复杂边界场景、体验细节打磨

关键原则:先静态后动态,先基础后复杂,先 AI 执行后人工兜底。

以"点赞功能"为例:

阶段 1(准备):梳理 POST /article/toggle-like 的请求/响应结构 + 事务规则
阶段 2(静态):实现 LikeButton 组件(红心图标 + 计数显示)
阶段 3(动态):对接接口,乐观更新 UI,后端返回后校正
阶段 4(适配):首页/详情页集成,请求 user-likes 校正点赞状态
阶段 5(兜底):未登录跳转、文章不存在提示、网络异常兜底

Step 4:原子任务颗粒度——给 AI 的指令必须"小而明确"

对应三层分工中的微观执行层,AI 主导,人 Review。

这是整套方法论中最关键的一条。交给 AI 的每个任务,必须满足三个条件:

  • 单次任务单目标
  • 有明确输入
  • 有可校验的验收标准

对比一下:

❌ 错误指令✅ 正确指令
实现点赞功能根据 POST /article/toggle-like 接口,实现 LikeButton 组件:已点赞→取消(灰色图标),未点赞→点赞(红色图标),乐观更新后端返回校正
处理 Token 过期实现 axios 401 拦截器:接口返回 401 且非刷新请求时,调用 /auth/refresh,成功重试原请求,失败跳转 /login?redirect=当前地址

禁止开放式需求。如果你自己都写不出验收标准,AI 更不可能做对。

Step 5:测试验证闭环——做完即验,不等最后

每个模块配套验证方案:测试链接 + 验证步骤 + 数据校验规则。AI 每完成一个原子任务,你都能快速验证,有问题马上改。


五、原子化开发:最高效的执行模式

五步拆解法解决了"怎么拆",但还有一个关键问题:拆完之后,怎么执行最高效?

核心论点

最好的上下文管理,就是根本不需要管理上下文。

对于 Claude Code,最高效的使用模式是:

大功能 → 拆分成原子任务 → 逐个开发 → 上下文污染时 /clear

这个模式下,你几乎永远不需要 /compact

/clear 的正确用法:按需清,不是每次清

一个常见误区:做完每个原子任务都必须 /clear

实际上,/clear 的判断标准是上下文是否被污染,而不是"任务是否完成":

场景是否 /clear原因
连续的原子任务之间有上下文关联,且 AI 表现正常❌ 不需要相关上下文反而是有用的,清掉反而丢失关键信息
上下文接近上限,AI 开始跑偏✅ 立即 /clear污染已经发生,继续只会越聊越偏
发现 AI 走了弯路、做了被否决的方案✅ 立即 /clear错误信息留在上下文中会持续干扰后续输出
切换到不同模块/不同业务域✅ /clear前一个模块的上下文对新模块是噪音

简单原则:上下文干净且相关 → 继续用;上下文脏了或跑偏了 → 立即清。

以点赞功能为例,6 个原子任务的执行节奏:

原子任务 1(Model + 索引)→ 完成,上下文干净,继续
原子任务 2(DTO)→ 完成,与任务 1 有关联,继续
原子任务 3(Controller)→ 完成,与任务 2 有关联,继续
原子任务 4(Service 事务)→ 发现 AI 理解错了事务逻辑 → 立即 /clear,重新开始
原子任务 5(前端 LikeButton)→ 切换到前端,与后端逻辑无直接上下文关联 → /clear
原子任务 6(集成校正)→ 完成

不是"做完就清",而是"需要清的时候果断清"。

为什么 /clear/compact 更好?

Claude 的最大敌人:上下文污染。

Claude 不会"忘记"错误的东西,它只是把它们压缩了。

哪怕压缩了,错误的信息依然在上下文中,潜移默化地影响输出质量。

操作污染清除程度说明
/clear✅ 100% 彻底清除完全干净,零污染残留
/compact⭐ 70% 部分清除还留"残影",被否决的方案依然存在
Autocompact⭐ 50% 保守清除尽量保留,清除最少

项目规则不依赖对话历史:

Claude 知道"Prisma Model 用 PascalCase"
    ↓
不是因为上一轮对话聊过
而是因为 CLAUDE.md 和 rules/*.md 自动加载了

所以你不用担心 /clear 会丢掉项目记忆——系统已经帮你加载好了。

跨模块的任务之间不需要上下文:

开发完"文章列表",再开发"点赞功能",这两个任务之间本就不应该有上下文关联。带着"文章列表的记忆"去开发"点赞",反而可能引入不必要的思维定势。这时候应该 /clear

实战演示

以"点赞功能"为例,完整的原子任务拆分:

点赞功能拆分为:
├─ 原子任务 1:ArticleLikes Prisma Model + 联合唯一索引
├─ 原子任务 2:ToggleLikeRequestDto / ToggleLikeResponseDto
├─ 原子任务 3:ArticleController.toggleLike(Guard + 参数校验)
├─ 原子任务 4:ArticleService.toggleLike(事务:关系增删 + 计数更新)
├─ 原子任务 5:前端 LikeButton 组件(乐观更新 + 后端校正)
└─ 原子任务 6:首页/详情页集成点赞状态校正

执行节奏——按需 /clear

任务 1-3(后端链路)→ 上下文关联,AI 正常 → 不 clear,连续推进
任务 4(Service 事务)→ 如果跑偏 → 立即 /clear,重新开始
任务 5(前端组件)→ 切换到前端,上下文切换 → /clear
任务 6(集成)→ 与任务 5 有关联 → 不 clear,继续

拆分原则:

  • ✅ 每个任务可以独立开发、独立测试
  • ✅ 每个任务预计对话不超过 30 条
  • ✅ 任务之间耦合度低
  • /clear 是按需的,不是强制的

三种模式的性能对比

模式上下文纯净度Claude 出错率心智负担适用场景
原子化 + /clear🌟 100% 纯净最低最低有明确边界的开发
连续对话 + Autocompact⭐ 80% 纯净中等探索性方案讨论
从不 clear,一直聊⭐ 50% 纯净调试、头脑风暴

什么时候 /compact 还有用?

只有两种场景:

  1. 连续探索性讨论:brainstorm 了 100 条消息讨论架构方向,最终确定后不想让被否决的想法干扰后续
  2. 超大型单体任务无法拆分:重构涉及 20 个文件,无法拆分也不能 /clear,每天结束时 /compact 一次

六、实战演练:从需求到交付的完整链路

前面的章节讲了三层分工、五步拆解法、原子化开发——方法论有了,但缺少一条从头走到尾的完整链路。这一节用博客项目的"点赞功能"走一遍全流程:接到需求 → 分析设计 → 任务拆解 → 生成提示词 → AI 执行 → 确认方案

1. 接到需求

需求通常就是这样来的——一句话,模糊,没有细节:

用户可以给文章点赞,再点一次取消,显示点赞数

接下来要做的事:把这句话翻译成 AI 能理解的结构化信息。

2. 分析设计

用"找名词→找动词→找条件"三步,把模糊需求变成结构化清单:

找名词(数据实体):

实体说明
点赞关系哪个用户对哪篇文章点了赞
文章点赞数文章的累计点赞计数

找动词(用户操作):

操作交互触发条件
点赞/取消点击红心图标已登录

找条件(业务规则):

规则前端后端
必须登录未登录点击 → 跳转登录页接口需 Guard 鉴权
防重复同一篇文章只有一个红心状态联合唯一索引防重复记录
数据一致乐观更新后用后端返回值校正关系表和计数必须在同一事务中更新
userId 来源前端不传 userId从 Token 中获取,禁止前端传参

到这一步,一句话需求已经变成前后端都能理解的结构化清单。

2.1 全栈场景:分析设计还要多想什么

上面的点赞案例偏单服务——前端直连一个后端接口。但全栈项目经常涉及跨服务链路,分析设计时要多关注三个维度:

① 同一数据在不同层的形态

同一个概念,在前端、后端、数据库的形态可能完全不同。分析设计时必须逐层映射:

数据数据库形态后端形态前端形态
刷新令牌refresh_tokens 表(id, user_id, token, expires_at, revoked)Prisma Model + Redis 缓存不可见(HttpOnly Cookie,JS 无法读取)

如果不在设计阶段把这个映射理清,AI 写前端时会把 Token 当成普通数据存在 localStorage,写后端时会把 refreshToken 直接返回给前端——都是安全事故。

② 跨服务链路追踪

全栈项目经常有多服务架构,分析设计时要画出完整的请求链路。以 Token 自动刷新为例:

前端接口返回 401
  → axios 拦截器判断:当前是否正在刷新?
    → 是:加入等待队列
    → 否:调用 /auth/refresh
      → backend 代理层(不做认证逻辑,只转发)
        → auth-service 校验 refreshToken
          → Redis 查询 + DB 校验
        → 生成新 accessToken,设置新 Cookie
      → 成功:重试队列中所有请求
      → 失败:跳转 /login?redirect=当前地址

关键:backend 只做代理,不做认证。这条规则必须在分析阶段就写死,否则 AI 可能在 backend 中写认证逻辑。

③ 事务一致性约束

涉及多表操作时,必须在分析阶段明确哪些操作必须在同一事务中:

场景事务约束
点赞/取消ArticleLikes 关系增删 + Articles.likes 计数更新,必须在同一事务
Token 刷新refreshToken 校验 + 新 Token 生成 + Redis 更新,必须原子执行

3. 任务拆解(三层分工 + 五步拆解法 + 原子化)

【领域拆分层】人类决策

点赞功能属于"互动功能"模块,依赖认证模块(获取当前用户)和文章模块(文章数据),点赞逻辑本身独立。

【宏观编排层】人类决策

执行顺序:后端 → 前端 → 集成。三大锚定:

  • 点赞接口必须通过 Guard 获取 currentUserId,禁止前端传 userId
  • ArticleLikes 和 Articles.likes 必须在同一事务中更新
  • 未登录点击跳转登录页

【微观执行层】AI 主导,人 Review

拆成 6 个原子任务:

点赞功能
├── 原子任务 1:ArticleLikes Prisma Model + 联合唯一索引
├── 原子任务 2:ToggleLikeRequestDto / ToggleLikeResponseDto
├── 原子任务 3:ArticleController.toggleLike(Guard + 参数校验)
├── 原子任务 4:ArticleService.toggleLike(事务:关系增删 + 计数更新)
├── 原子任务 5:前端 LikeButton 组件(乐观更新 + 后端校正)
└── 原子任务 6:首页/详情页集成点赞状态校正

每个原子任务满足:单目标 + 明确输入 + 可校验的验收标准。

4. 逐条生成提示词

这是最关键的转折——把原子任务翻译成 AI 可直接执行的逐条提示词。每个提示词包含四要素:目标 + 需求功能 + 完成标准 + 约束

原子任务 1:ArticleLikes Model + 索引

目标: 新增点赞关系的数据库模型 需求功能:prisma/schema.prisma 中新增 ArticleLikes 模型,字段:id(String @id @db.VarChar(36)),article_id(String),user_id(String),created_at(DateTime @default(now))。添加联合唯一索引 @@unique([article_id, user_id])。在 Articles 模型中添加 likes 字段(Int @default(0)) 完成标准: 执行 npx prisma migrate dev --name add-article-likes 迁移成功,无类型错误 约束: Model 使用 PascalCase,数据库字段使用下划线命名

原子任务 2:DTO

目标: 创建点赞接口的请求/响应数据结构 需求功能:src/article/dto/ 下创建 ToggleLikeRequestDto(articleId: string,加 IsNotEmpty + IsString 校验)和 ToggleLikeResponseDto(articleId: string, likes: number, isLiked: boolean),在 dto/index.ts 中统一导出,每个字段添加 @ApiProperty 装饰器 完成标准: DTO 类型完整,校验装饰器齐全,导出正确,tsc 编译无错误 约束: 禁止使用 any,可选字段加 @IsOptional,数字字段加 @Type(() => Number)

原子任务 3:Controller

目标: 新增点赞/取消点赞的 API 端点 需求功能: 在 ArticleController 中新增 POST toggle-like 端点,使用 @UseGuards(RemoteJwtAuthGuard) 从请求中获取 currentUserId,参数用 @Body() toggleLikeDto: ToggleLikeRequestDto 完成标准: 路由可访问,Guard 鉴权生效,参数校验正常,Swagger 文档正确显示 约束: Controller 不写业务逻辑,只做参数解析和调用 Service;显式声明返回类型 Promise;userId 从 Guard 获取,禁止前端传参

原子任务 4:Service 事务

目标: 实现点赞/取消的核心业务逻辑 需求功能: 在 ArticleService 中实现 toggleLike 方法,接收 userId 和 articleId。查询 ArticleLikes 是否存在 article_id + user_id 记录,已点赞 → 删除记录 + Articles.likes 减 1;未点赞 → 创建记录 + Articles.likes 加 1 完成标准: 点赞和取消都能走通,关系表和计数始终一致,返回正确的 ToggleLikeResponseDto 约束: 必须在 Prisma $transaction 中执行,保证关系表和计数的原子性更新

原子任务 5:前端 LikeButton 组件

目标: 实现点赞交互组件 需求功能:apps/web/src/pages/articleDetail/components/ 下创建 LikeButton 组件,Props:isLiked, likes, articleId, onToggle。点击时乐观更新(isLiked 取反,likes ±1),调用 api.article.toggleLike({ articleId }),返回后用后端数据校正 完成标准: 组件渲染正常,乐观更新流畅,后端返回后状态校正正确 约束: 使用 useObserver 包裹渲染;Props 类型必须显式定义;禁止组件内直接使用 axios

原子任务 6:集成校正

目标: 在页面中集成点赞功能并校正初始状态 需求功能: 在首页文章列表和文章详情页集成 LikeButton,页面初始化时如果用户已登录,请求用户点赞列表校正各文章的 isLiked 状态 完成标准: 首页和详情页点赞状态同步,未登录点击跳转登录页,点赞/取消后列表和详情状态一致 约束: 点赞状态校正请求在登录后才发起;LikeButton 的 onToggle 回调更新对应文章的点赞状态

四要素的作用: 目标让 AI 知道"做这个任务是为了什么",需求功能告诉 AI"具体做什么",完成标准让 AI 知道"做到什么程度算完成",约束划清"不能做什么"。四要素齐全,AI 执行基本一次到位;缺任何一个,AI 就要猜,猜就是翻车的开始。

5. 给 AI 执行

按顺序逐条给 AI 执行,结合原子化开发的 /clear 策略:

任务 1-3(后端链路)→ 上下文关联,AI 正常 → 不 clear,连续推进
任务 4(Service 事务)→ 如果跑偏 → 立即 /clear,重新开始
任务 5(前端组件)→ 切换到前端,上下文切换 → /clear
任务 6(集成)→ 与任务 5 有关联 → 不 clear,继续

6. 确认方案

每个原子任务完成后立即验收:

任务验收点
1Schema 正确 + 迁移生成成功
2DTO 类型完整 + 校验装饰器齐全 + 导出正确
3路由可访问 + Guard 生效 + 参数校验正常
4事务逻辑正确 + 点赞/取消都走通 + 计数一致
5组件渲染正常 + 乐观更新流畅 + 后端返回校正
6首页/详情页状态同步 + 未登录跳转正常

全部通过 → 提交代码。如果需要质量保障,按下一篇的审查流水线走 code-review → security-audit → test-writer。

7. 链路总结

整个流程的核心转折点在第 3→4 步:任务拆解是人的决策,生成提示词是人到 AI 的翻译。提示词四要素决定了 AI 执行的命中率——要素齐全,基本一次到位;要素缺失,AI 就要猜,猜就是翻车的开始。


七、标准操作流程总结

把三层分工 + 五步拆解法 + 原子化开发串起来:

  1. 切块 → 【领域拆分】全项目业务域拆解,输出独立模块 Scope 定义
  2. 定规 → 【宏观编排】单模块前置约束梳理,输出三大锚定清单 + 执行顺序 + 合并闸门
  3. 分步 → 【微观执行】模块内线性流程拆解,拆分开发全周期子阶段
  4. 派单 → 【微观执行】子阶段内原子任务拆分,每个任务符合颗粒度标准
  5. 执行 → 【微观执行】按顺序推进,上下文脏了或跑偏了立即 /clear
  6. 验收 → 【微观执行】单模块测试验证与闭环优化

注意第 1-2 步是人类决策层,第 3-6 步才是 AI 主导的微观执行层。


八、核心优势

  • 降低 AI 幻觉:前置硬规则锁死边界,AI 输出基本一次到位
  • 上下文按需清零:原子化 + 按需 /clear,上下文干净就继续,跑偏了果断清
  • 人机分工清晰:三层分工确保人类做决策、AI 做执行,各司其职
  • 匹配 AI 能力边界:把高耦合需求拆成单轮推理可承载的原子任务
  • 可复制可沉淀:方法论标准化,任何复杂项目都适用

九、适用场景

  • 功能多、接口多、状态码多的复杂业务系统
  • 多服务/微服务架构,需要跨服务协作的项目
  • 使用 Claude Code / Cursor / Trae 等 AI 编辑器进行规模化开发的场景