需求文档怎么写（三）实战技巧：状态机，TDD，上下文管理等

掌握了业务骨架（PRD/User Story/Schema/API）和项目规范（Rules/Types）后，你其实已经击败了 90% 的 AI 编程新手。

但是在实际面对大型项目时，要真正让 AI 像一个高级工程师一样听话，还有 3 个极具含金量的高阶实战技巧 可以传授给你：

1. 业务逻辑的"状态机化"（State Machines）

大型项目最容易出 Bug 的地方不是简单的 CRUD（增删改查），而是复杂的业务流程（如：订单流程、退款流程、审批流、多步骤表单）。

AI 经常会漏掉某些特殊状态的判断（例如：未支付订单过期了怎么办？退款申请中又点了取消怎么办？）。

教给你的技巧 ：在写复杂业务时，先画一个/写一个状态图（State Diagram） ，用文本定义好"允许从哪个状态跳转到哪个状态"。

示例（直接写在需求里给 AI） ：

Plaintext

scss 复制代码

【订单状态机定义】
- PENDING (待支付) -> CANCELLED (通过：取消操作/超时)
- PENDING (待支付) -> PAID (通过：支付成功)
- PAID (已支付) -> REFUNDING (通过：申请退款)
- PAID (已支付) -> COMPLETED (通过：确认收货)
* 禁止任何非法状态跳转（例如：CANCELLED 不能直接变成 COMPLETED）。

效果：AI 拿到这个逻辑后，写出来的后端代码会自动补全绝大多数防止越权和非法状态更新的安全校验。

2. 用"测试驱动开发"（TDD）来约束 AI 的代码质量

对于大需求，如果你只跟 AI 说"帮我实现这个功能"，AI 写完代码你只能手动去点界面验证，费时费力且容易遗漏隐蔽 Bug。

教给你的技巧 ：先让 AI 写测试用例，再让 AI 写业务代码。
实战 Prompt 流程：
1. 第一步（生成测试） ："基于 04-API_SPEC.md 中'购物车结算'的接口定义，请先使用 $Jest/Vitest$ 帮我写出单元测试用例。需要覆盖正常结算、库存不足、余额不足、优惠券过期这 4 种情况。"
2. 第二步（运行测试） ：此时测试运行肯定全部失败（因为还没有业务代码）。
3. 第三步（实现功能） ："现在请编写'购物车结算'的后端逻辑代码，直到上面所有的单元测试全部绿灯（通过）为止。"
效果：测试用例成为了 AI 的硬性指标，代码逻辑没写对，AI 自己就会不断修正，直到跑通测试。

3. 上下文记忆管理与"Context 瘦身"技巧

大型项目开发往往长达数周，如果上下文管理不好，AI 会开始出现"幻觉"或者"胡言乱语"。

教给你的技巧：
- 建立 CHANGELOG.md 或 PROGRESS.md（进度看板） ：
  
  每完成一个模块，让 AI 在这个文件里记一笔，例如：
  
  - [x] 2026-09-08: 完成用户鉴权模块 (API: /api/auth/*, Schema: User, Session)
  
  - [ ] 下一步：开发商品搜索模块
- 开启新对话时的"极简冷启动" ：
  
  当一个窗口对话太长导致 AI 变傻时，直接开启全新的对话窗口，只发送这句话：
  
  "我是这个项目的开发者。项目规则在 .cursorrules，目前进度参考 PROGRESS.md，数据库定义见 SCHEMA.sql。现在我们开始开发 PROGRESS.md 中下一个未完成的功能： $具体功能$ 。"
  
  这样可以用极少的 Token 让全新的 AI 迅速进入状态，且不会受到旧对话垃圾信息的干扰。

💡 总结你的"大项目 AI 编程工作流全景图"

准备阶段 ：整理 PRD.md -> USER_STORIES.md -> SCHEMA.sql -> API_SPEC.md。
环境搭建 ：配置 .cursorrules（规范）+ 全局类型 Types + PROGRESS.md（进度表）。
开发循环（每个微型模块） ：
- 喂给 AI 当前模块的 User Story + API 定义。
- 让 AI 先写测试用例 / Types -> 再写代码。
- 本地跑通 -> Git Commit -> 更新 PROGRESS.md。
- 开启新对话，重复下一轮。

这套体系也是目前很多顶级独立开发者（Indie Hackers）和全栈工程师用 AI 高效产出大中型项目的标准工程化路径。

除了前面讲到的业务设计（Schema/API/PRD）、规范约束（Rules/Types）以及状态机、TDD 和上下文管理这些方法论，最后还有 4 个涉及实际工程落地、重构与实战心态的高阶"杀手锏" 可以补充给你：

1. 善用"伪代码/流程图"进行算法与复杂逻辑对齐

在处理涉及复杂计算、权限判断、数据流转的业务（比如：分销佣金计算、多重优惠叠加扣减、大数据量导入拆分）时，直接用自然语言描述，AI 很容易理解偏差。

实战技巧 ：在把需求交给 AI 写真实代码前，先用 Mermaid 流程图 或 伪代码（Pseudocode） 让 AI 确认逻辑。
做法示例：
"我想实现优惠券叠加逻辑。逻辑如下，请先用伪代码/Markdown 流程图列出每一步判断，不要写实际代码，确认无误后我再让你写：
1. 先计算商品满减；
2. 再叠加品类折扣券（不可叠加跨店券）；
3. 最后扣减积分。
  
  请列出每一步的判断条件和边界边界。"
效果：先在"思维层面"把逻辑理顺，避开了直接生成数百行错误代码再慢慢重构的巨额成本。

2. 重构与 Bug 排查："隔离诊断"与"小步快跑"

当项目变大后，AI 改 Bug 经常出现"修好 A 却弄坏了 B"的现象。

实战技巧：
- 不要让 AI 盲目猜测 ：遇到报错时，把报错信息（Stack Trace）+ 相关的单文件代码 + 期望输出 一起发给 AI，并明确要求："只修改引起该报错的代码块，不要重构其他无关函数。"
- 让 AI 扮演 Code Reviewer：在你或 AI 完成一个模块后，开启新对话，把代码发给 AI 并问：
  
  "请作为高级安全/性能专家审查这段代码。重点寻找：1) 是否存在 SQL 注入或 N+1 查询问题；2) 是否有内存泄漏风险；3) 边界条件（如 null/undefined）是否都有处理。"

3. 让 AI 生成 Mock 数据与 API 文档（反向利用 AI）

在大项目开发中，前后端并行非常常见。手写 Mock 数据和 Swagger/OpenAPI 文档极其耗时，而这恰恰是 AI 最擅长的事情。

实战技巧：
- 生成测试数据 ：当你写好了 SCHEMA.sql，直接跟 AI 说："基于这个表结构，给我生成 50 条逼真的测试数据（SQL 插入语句/JSON 格式），需要包含各种边缘情况（如极长用户名、特殊字符、空字段等）。"
- 反向生成接口文档：当后端代码写好后，直接把 Controller 扔给 AI："请根据这个文件，自动生成标准的 OpenAPI 3.0 JSON / Swagger 格式文档。"

4. 建立你自己的" Prompt / 组件记忆库"

随着你用 AI 写的项目越来越多，你会发现很多通用的东西（比如：JWT 认证拦截器、图片上传到 OSS/S3、标准 API 错误响应格式、通用分页组件）在每个项目里几乎是一样的。

实战技巧：
- 在你本地或 GitHub 上建立一个 my-ai-snippets 知识库。
- 每次 AI 写出了一个特别完美、结构优雅的通用模块（例如带防抖的搜索框、通用的 Redis 缓存封装），就把这段代码和对应的 Prompt 存起来。
- 下次开发新大项目时，直接把这些优秀模板投喂给 AI："请参考我提供的这个经典 JWT 鉴权逻辑 $附带代码片段$ ，为当前新项目实现类似的鉴权。"

🎯 终极心法总结

需求清晰度决定代码上线质量：AI 是你手下速度极快但毫无业务经验的"超级实习生"。你给的指令越结构化、数据模型越精准，它的产出就越惊人。
掌控主导权，小步 Git Commit ：永远保持自己对代码库的掌控，不要让 AI 一次性改动太多文件。每跑通一个功能点就 git commit 一次，随时准备回滚。

结合之前为你梳理的 PRD/User Story/Schema 准备流程 、6 大核心需求要素 以及 多阶段拆解策略，你现在已经掌握了一套非常完整且立竿见影的现代 AI 辅助软件工程（AI-Assisted Software Engineering）工作流。