项目规划与 AI 协作

这一课你将能做到

1. 把一个模糊想法拆成 AI 可执行的分阶段计划
2. 写出让 AI 不跑偏的项目级上下文文档（需求、技术栈、约束）
3. 用「先规划后生成」的流程，避免 AI 自由发挥导致的大规模返工

为什么要学

初学者用 AI 编程最常踩的坑：一句话「帮我写一个电商网站」，AI 真给了你一个电商网站——用你不熟的技术栈、不符合你需求的字段、跑不起来的依赖。然后你花三天修一个本来不该存在的东西。

人话：AI 是个能力极强但完全不了解你处境的远程外包。你不写需求文档，它就按自己的想象干活。规划不是形式主义，是把「你想要什么」翻译成「AI 能执行什么」的过程。

真实开发中，先有规划再动手，返工率能降一个数量级。这一课教你写两种东西：给人看的计划（TODO 清单），和给 AI 看的上下文（项目说明文件）。

先建立图像

没有规划的协作：
想法 → 一句话提示词 → AI 自由发挥 → 大量返工 → 推倒重来

有规划的协作：
想法 → 拆解需求 → 确定技术栈 → 写项目上下文 → 分阶段生成
     → 每阶段验收 → 增量迭代 → 可控交付

跟着做

步骤 1：把想法写成需求清单

假设你要做一个「团队内部的技术文章收藏夹」。先别打开 AI 工具，打开备忘录写：

目标用户：10 人左右的开发团队
核心功能：
  1. 提交文章链接，自动抓取标题和摘要
  2. 按标签分类浏览
  3. 点赞和评论
非目标（明确不做）：用户系统先用最简单的账号密码、不做移动端 App、不做推荐算法
约束：后端用 Java Spring Boot（团队现有技术栈）、数据库用 MySQL

注意「非目标」部分——明确不做什么，和做什么同样重要，这是防止 AI 过度设计的最有效手段。

步骤 2：把需求拆成阶段

阶段 1（骨架）：项目脚手架 + 数据库表结构 + 文章提交/列表接口
阶段 2（核心）：链接抓取（标题/摘要） + 标签 CRUD
阶段 3（交互）：点赞、评论
阶段 4（打磨）：错误处理、参数校验、部署脚本

每个阶段是「可独立验收」的：阶段 1 完成后，接口能用 Postman 调通，就算过。

步骤 3：写项目上下文文件

在项目根目录建一个 PROJECT.md（不同工具叫法不同：Cursor 用 .cursor/rules，Claude Code 用 CLAUDE.md，本质相同）：

# 项目：技术文章收藏夹

## 技术栈
- 后端：Java 17 + Spring Boot 3 + MyBatis-Plus
- 数据库：MySQL 8，表名小写下划线，主键统一叫 id
- 前端：无（纯 API 项目，前端另开仓库）

## 代码约定
- 包结构：controller / service / mapper / entity 分层
- 接口返回统一用 Result<T> 包装：{ code, message, data }
- 日期时间统一用 LocalDateTime，Jackson 序列化为 yyyy-MM-dd HH:mm:ss

## 当前进度
阶段 1 进行中：已完成表结构设计，待生成脚手架

## 明确不做
- 不做用户权限（先硬编码一个管理员）
- 不做缓存（阶段 4 后再评估）

步骤 4：按阶段喂给 AI

打开 AI 工具，第一轮提示词：

这是我们的项目上下文（粘贴 PROJECT.md 内容）。
请完成阶段 1：生成 Spring Boot 项目脚手架，
包含文章表的建表 SQL（字段：id, url, title, summary, created_at）、
对应的 entity / mapper / service / controller，
接口两个：POST /articles 提交、GET /articles 分页列表。
先只给文件清单和建表 SQL，我确认后再生成代码。

注意最后一句「先只给文件清单」——这是规划心态的延伸：让 AI 先输出方案，你确认方向后再让它写代码，比直接要代码省 80% 的返工。

步骤 5：每阶段结束更新上下文

阶段 1 验收通过后，回到 PROJECT.md 更新「当前进度」部分，再开始阶段 2。AI 每次开会话都读这个文件，永远不会问「我们上次做到哪了」。

同时把踩过的坑记进文件：

## 已知坑
- MyBatis-Plus 3.5.7 的分页插件必须手动注册，不注册会内存分页
- 前端传的日期格式是 ISO 8601，后端需要自定义反序列化

这些坑是人花时间趟出来的，记下来让 AI 绕开，团队协作时尤其值钱。

讲清楚要点

1. 规划的核心产物是「上下文」，不是甘特图：AI 不需要你的排期，它需要知道技术栈、约定、进度和禁区。
2. 阶段要按「可验收」切分：每个阶段结束都有一个能跑、能测的东西，而不是「写了 30% 的代码」这种没法验收的状态。
3. 先方案后代码：让 AI 先给设计（文件结构、表结构、接口定义），确认后再生成实现，返工成本最低。
4. 非目标清单是刹车片：AI 默认倾向「功能做全」，你明确说不做的部分，它才不会擅自加缓存、加权限、加消息队列。
5. 上下文文件是活文档：进度、决策、踩过的坑都写进去，它是你和 AI 的共享记忆。

你可能会懵的地方

• 规划要做到多细？会不会过度设计？ 细到「AI 不会问出你不确定的细节」为止。表结构、接口路径、返回格式这种确定性的东西写死；具体实现细节留给 AI。判断标准：如果一个决策错了你要返工，就提前定；如果错了改两行就行，就不用定。

• 小项目也要写 PROJECT.md 吗？ 超过一天的项目就值得写。它不止给 AI 看，也是给你自己的——三天后你回来看「当前进度」，比重读代码快得多。

• AI 不遵守我的约定怎么办？ 用工具的规则机制强制注入：Cursor 的 .cursor/rules、Claude Code 的 CLAUDE.md 会在每次对话自动携带，比在聊天里重复说有效得多。后续工具课会详细讲。

• 阶段切分按功能还是按层级？ 按功能垂直切（一个功能从表到接口一次做完），不要按层级横切（先写完全部 entity 再写全部 service）。垂直切片每个阶段都能端到端验收，横切到最后一天才发现接不起来。

• 计划赶不上变化，中途改需求怎么办？ 改 PROJECT.md，标出变更点，开新会话把变更点告诉 AI，让它评估影响面（「改动 X 会影响哪些已有文件」）再动手。不要在旧会话里直接改需求，上下文里的旧决策会污染新输出。

错法对照

错法	问题	正解
「帮我写个电商网站」	需求全留给 AI 脑补	写清功能清单、非目标、技术栈约束
一口气要全部代码	几千行没法审，错误藏在中间	分阶段生成，每阶段可验收
口头约定「记得用 MyBatis」	下个会话就忘	约定写进规则文件，自动注入
边做边想下一步	AI 跟着你摇摆，代码风格漂移	阶段内不动计划，变更走「改文档→新会话」
没有验收标准	「差不多行了」积累成技术债	每阶段定义可执行的验收（接口调通/测试通过）

卡点急救

1. AI 生成的方案方向就不对：不要纠正代码，回到方案层。说「停下，这个方向不对，我要的是 X，重新给方案」，省得在错误方向上精修。
2. 需求自己都没想清楚：让 AI 反问你。提示词：「我要做 X，在开始之前，列出你需要我确认的 5 个关键问题」。被问倒的问题就是你想漏的地方。
3. 做着做着上下文文件过时了：每阶段结束的最后一个动作固定为更新 PROJECT.md，写进你的开发节奏，不靠自觉。

面试常问

• 你怎么把 AI 工具引入团队开发流程？ 高分回答：从规划层切入——先建立团队级的上下文文件（技术栈、代码规范、禁区清单），用工具的规则机制自动注入；流程上强制「先方案后代码、分阶段验收」；用提交频率和返工率做前后对比验证效果。

• AI 协作开发中如何做需求变更管理？ 变更先落到上下文文档（单一事实来源），评估影响面时利用 AI 的代码检索能力，变更在独立分支和新会话中执行，避免旧上下文污染。

• 怎么防止 AI 过度设计？ 在上下文中明确「非目标」和「当前阶段范围」，提示词里限定「只做本次要求的功能，不要添加未要求的抽象层、配置项或依赖」。

自测三问

1. 为什么「非目标清单」对 AI 协作特别重要？
2. 阶段切分为什么要按功能垂直切而不是按技术层横切？
3. 你的项目上下文文件至少应该包含哪四个部分？

小结一句话

规划不是耽误写代码，是给 AI 画施工图——图纸越清楚，返工越少；上下文文件是你和 AI 的共享记忆，它越准，协作越顺。

延伸

• Claude Code 官方文档：CLAUDE.md 记忆文件
• 下一课：Cursor 与 Windsurf——编辑器级 AI 工具的 rules 与 Composer/Cascade 实战。