大项目拆解

你真正开始用 AI 写项目时，最容易踩的坑不是“模型不会写代码”，而是你把一个还没拆开的需求直接丢给它。

比如：

帮我做一个带登录、注册、Todo 列表、筛选、持久化和部署的 Web 应用。

这句话对人来说能理解方向，对 AI 来说却太大了。它需要自己猜技术栈、猜目录结构、猜鉴权方案、猜数据存在哪里，还要一次性改很多文件。等它输出一大堆代码之后，你很难判断第一处错误从哪里开始。

大项目拆解要解决的，就是把这种“完整需求”变成一串 AI 可以稳定处理的小任务。这里的重点不是写项目计划书，而是让每一轮编码都足够小、足够清楚、足够容易验证。

为什么大需求会让 AI 失控

AI 在大需求里经常会做三类猜测。

它会猜范围。你只说“加登录”，它可能顺手加注册页、用户中心、权限中间件、样式系统和 mock 数据。它不是故意乱改，而是在用自己的常识补空白。

它会猜架构。项目里可能已经有 api/、services/、hooks/ 的分层，但如果上下文没给到，它会另起一套 utils/request.ts 或 authClient.ts。代码能跑一会儿，后面却越来越不像同一个项目。

它还会猜验证方式。没有告诉它“做完后跑什么命令、点哪个页面、看哪个接口”，它就容易停在“代码已经修改完成”的状态。你继续往下推进，错误会被带到下一轮。

拆解的作用，就是减少这些猜测。

按功能边界拆，而不是按时间拆

写给 AI 的任务，最好按“功能边界”拆。功能边界指的是：这一小段改动有自己的输入、输出和验证方式。

不要这样拆：

第一天：做项目基础
第二天：做业务逻辑
第三天：做优化

这种拆法适合排日程，不适合交给 AI。AI 不知道“项目基础”具体包含哪些文件，也不知道“优化”到底是样式、性能、可维护性还是错误处理。

更适合 AI 的拆法是：

任务 1：搭建 Todo 页面骨架，只包含输入框、列表和空状态，不接后端。
任务 2：实现 Todo 的新增、完成、删除，数据先存在浏览器 localStorage。
任务 3：加入登录页和登录态存储，先用本地 mock 用户验证。
任务 4：把 Todo 数据从 localStorage 切换到后端 API。
任务 5：补充加载态、错误态和基础测试。

每个任务都能单独完成，也能单独验证。任务之间有顺序，但不会要求 AI 同时理解整个产品。

示例：把带登录的 Todo 应用拆开

假设你现在要做一个“带登录的 Todo 应用”。完整需求可能长这样：

用户可以注册和登录。登录后进入 Todo 页面，可以新增、编辑、删除、完成 Todo。
Todo 需要按未完成和已完成筛选。刷新页面后数据不能丢。后续希望接入真实后端。

直接让 AI “完整实现”会很危险。更稳的方式是先写一份拆解文档，可以叫 PLANNING.md，也可以放在项目已有的任务文档里。

# Todo App 拆解

## 当前目标
先做一个单用户版本，保证页面、状态流转和基本交互稳定，再接登录和后端。

## 任务 1：Todo 页面静态骨架
- 新增页面：`/todos`
- 包含输入框、添加按钮、列表区域、空状态
- 不实现登录，不接 API，不做复杂样式
- 验证：启动项目后访问 `/todos`，能看到页面结构

## 任务 2：本地 Todo 交互
- 支持新增、完成、删除
- 数据存在 React state
- 不做编辑，不做筛选
- 验证：手动添加三条 Todo，刷新前交互正常

## 任务 3：持久化与筛选
- 使用 localStorage 保存 Todo
- 增加“全部 / 未完成 / 已完成”筛选
- 验证：刷新页面后 Todo 仍然存在，筛选结果正确

## 任务 4：登录态外壳
- 新增登录页
- 使用 mock 用户登录
- 未登录访问 `/todos` 时跳转登录页
- 验证：退出登录后不能直接访问 Todo 页面

## 暂不做
- 注册
- 多用户数据隔离
- 真实后端 API
- 部署

这份文档看起来比一句 Prompt 麻烦，但它能帮你控制 AI 的工作范围。你每次只让 AI 执行其中一个任务，并且把“暂不做”也告诉它。尤其是“暂不做”，很重要。AI 经常会主动补全它认为完整的产品形态，你要提前把边界写出来。

拆到什么粒度比较合适

一个好用的任务粒度，大概有几个特征。

AI 不需要读半个仓库才能开始。它可能需要看路由、组件目录、状态管理方式，但不应该同时理解登录、支付、部署、测试框架和样式规范。

任务完成后，你能在几分钟内验证。比如打开一个页面、跑一次测试、调用一个接口、看一个错误态。验证时间太长，说明任务可能还是太大。

改动文件数量可控。不是说只能改一个文件，而是你能解释为什么要改这些文件。如果一个任务预计会碰十几个文件，最好再拆一次，或者先让 AI 做方案，不要直接动手。

还有一个实用判断：如果你没法用两三句话说清楚“这轮做完算完成”，这个任务就还没拆好。

每个小任务都要有验证点

拆解不是把需求切碎就结束了。每个任务旁边都要写验证点，因为 AI 写代码最怕的是“看起来完成了，但没人确认它真的完成”。

验证点可以很简单：

运行 `pnpm dev` 后访问 `/todos`，页面没有报错。
新增一条 Todo 后，列表出现新内容。
刷新页面后，localStorage 中的数据还能恢复。
未登录访问 `/todos`，会跳到 `/login`。

如果你在真实项目里，还可以加上测试命令、接口请求、浏览器操作路径。不要追求验证点完美，先保证它具体。

让拆解文档成为对话的锚点

当项目超过几轮对话后，AI 很容易忘记最初边界。PLANNING.md 的价值就在这里：它不是给老板看的计划，而是你和 AI 共享的项目记忆。

你可以在每一轮开始时这样给任务：

请读取 `PLANNING.md` 中的任务 3，只实现“持久化与筛选”。
不要处理登录、注册、后端 API。
完成后告诉我改了哪些文件，以及我应该怎么验证。

如果中途发现任务拆错了，也可以改文档。比如做到登录时发现需要先抽出 auth 状态管理，那就新增一个前置任务，而不是让 AI 在当前轮里顺手完成。

拆解不是为了让项目显得专业，而是为了让 AI 每次只做一件你能检查的事。只要你能持续做到这一点，大需求就不会一下子压到模型和你自己身上。