最佳实践：清晰描述、检查点利用、范围控制与迭代技巧

学完你能做什么

学完本课，你将掌握：

• 如何编写高质量的产品描述，让 AI 理解你的想法
• 如何利用检查点机制控制每个阶段的输出质量
• 如何通过非目标明确范围边界，防止项目膨胀
• 如何通过逐步迭代，快速验证想法并持续优化

你现在的困境

你是不是也遇到过这些情况：

• "我说的很清楚了，为什么生成的不是我想要的？"
• "一个地方不满意，后面全错了，改起来很痛苦"
• "做着做着功能越来越多，完全没法收尾"
• "想一次性把所有功能都做出来，结果什么都没做出来"

什么时候用这一招

无论你是第一次使用 AI App Factory，还是已经有过几次经验，这些最佳实践都能帮你：

• 提高输出质量：让生成的应用更符合预期
• 节省修改时间：避免错误累积，早期发现问题
• 控制项目规模：聚焦 MVP，快速交付
• 降低开发成本：分阶段验证，避免无效投入

🎒 开始前的准备

前置要求

• 已阅读 快速开始 了解 AI App Factory 的基本概念
• 已阅读 7 阶段流水线概览 了解完整流程
• 已完成至少一次完整的流水线执行（这样你对每个阶段的输出有直观感受）

核心思路

AI App Factory 的最佳实践围绕四个核心原则：

1. 输入质量决定输出质量：清晰、详细的产品描述是成功的第一步
2. 检查点是质量防线：每个阶段完成后仔细确认，避免错误累积
3. MVP 聚焦：明确非目标，控制范围，快速交付核心功能
4. 持续迭代：先验证核心想法，再逐步扩展功能

这些原则来自源码和实战经验的总结，遵循它们能让你的开发效率提升数倍。

跟我做

技巧 1：提供清晰的产品描述

为什么

AI 理解你的想法时，只能依赖你提供的文本信息。描述越清晰，生成的产物越符合预期。

怎么做

好的产品描述包含以下要素：

• 目标用户：谁会使用这个产品？
• 核心问题：用户遇到了什么困难？
• 解决方案：产品如何解决这个困难？
• 关键功能：必须包含哪些功能？
• 使用场景：用户在什么情况下使用？
• 约束条件：有什么限制或特殊要求？

对比示例

❌ 差的描述	✅ 好的描述
做一个健身应用	帮助健身新手记录训练的应用，支持记录运动类型、时长、消耗卡路里，并查看本周训练统计。目标用户是刚开始健身的年轻人，核心功能是快速记录和查看进度，不包含社交分享或付费功能
做一个记账应用	帮助年轻人快速记录日常支出的移动端记账应用，主要功能是记录金额、选择分类（饮食、交通、娱乐、其他），查看本月总支出和分类统计。支持离线使用，数据仅保存在本地
做一个任务管理工具	帮助小团队管理任务的简单工具，支持创建任务、分配成员、设置截止日期、查看任务列表。团队成员之间可以共享任务状态。不需要复杂的工作流或权限管理

检查点 ✅

• [ ] 描述中明确了目标用户
• [ ] 描述中说明了用户遇到的核心问题
• [ ] 描述中列出了关键功能（不超过 5 个）
• [ ] 描述中包含了约束条件或非目标

---

技巧 2：在检查点仔细确认

为什么

流水线的每个阶段完成后都会暂停检查点，等待你确认。这是质量防线，能让你早期发现问题，避免错误传播到后续阶段。

如果在这个阶段发现问题，只需重跑当前阶段；如果等到最后才发现，可能需要回滚多个阶段，浪费大量时间和 Token。

怎么做

每个检查点确认时，检查以下内容：

Bootstrap 阶段检查点：

• [ ] input/idea.md 中的问题定义准确
• [ ] 目标用户画像清晰具体
• [ ] 核心价值主张明确
• [ ] 假设条件合理

PRD 阶段检查点：

• [ ] 用户故事清晰，包含接受条件
• [ ] 功能列表不超过 7 个（MVP 原则）
• [ ] 明确列出了非目标（Non-Goals）
• [ ] 未包含技术细节（如 React、API、数据库）

UI 阶段检查点：

• [ ] 页面结构合理，不超过 3 页
• [ ] 可以在浏览器中预览原型
• [ ] 交互流程清晰
• [ ] 审美风格鲜明（避免常见的 AI 风格）

Tech 阶段检查点：

• [ ] 技术栈选择合理，符合 MVP 原则
• [ ] 数据模型设计简单，表数量不超过 10 个
• [ ] API 端点列表完整
• [ ] 未引入微服务、缓存等过度设计

Code 阶段检查点：

• [ ] 前后端代码结构完整
• [ ] 包含测试用例
• [ ] 无明显的 any 类型
• [ ] 包含 README.md 说明如何运行

Validation 阶段检查点：

• [ ] 验证报告中无严重安全问题
• [ ] 测试覆盖率 > 60%
• [ ] 依赖安装无冲突
• [ ] TypeScript 类型检查通过

Preview 阶段检查点：

• [ ] README.md 包含完整的运行说明
• [ ] Docker 配置可正常构建
• [ ] 本地可启动前后端服务
• [ ] 包含环境变量配置说明

检查点确认流程

在每个检查点，系统会提供以下选项：

• 继续：如果输出符合预期，继续下一阶段
• 重试：如果输出有问题，提供修改意见并重跑当前阶段
• 暂停：如果需要更多信息或想要调整想法，暂停流水线

决策原则：

• ✅ 继续：所有检查项都符合要求
• ⚠️ 重试：小问题（格式、遗漏、细节），可以立即修正
• 🛑 暂停：重大问题（方向错误、范围失控、无法修正），需要重新规划

踩坑提醒

常见错误

不要为了"赶紧完成"而跳过检查点确认！

流水线设计成"每阶段暂停确认"就是为了让你及时发现问题。如果你习惯性地点击"继续"，等到最后才发现问题，可能需要：

• 回滚多个阶段
• 重新执行大量工作
• 浪费大量 Token

记住：检查点确认的时间投入，远小于回滚重做的时间成本。

---

技巧 3：利用非目标控制范围

为什么

非目标（Non-Goals）是 MVP 开发的核心武器。明确列出"不做什么"，能有效防止范围蔓延。

很多项目失败的根源不是功能太少，而是功能太多。每个新功能都会增加复杂度、开发时间和维护成本。明确边界，聚焦核心价值，才能快速交付。

怎么做

在 Bootstrap 阶段，明确列出非目标：

## 非目标（本版本不做的功能）

1. 不支持多人协作
2. 不支持实时同步
3. 不支持第三方服务集成（如支付、地图）
4. 不提供数据分析或报表功能
5. 不包含社交分享功能
6. 不需要用户认证或登录功能

在 PRD 阶段，将非目标作为独立章节：

## 非目标（本版本明确不做）

以下功能虽然有价值，但不在本次 MVP 范围内：

| 功能 | 理由 | 未来规划 |
| --- | --- | --- |
| 多人协作 | 聚焦个人用户 | v2.0 考虑 |
| 实时同步 | 增加技术复杂度 | 用户反馈强烈后再考虑 |
| 支付集成 | 非核心价值 | v1.5 考虑 |
| 数据分析 | MVP 不需要 | v2.0 考虑 |

非目标的判断标准

如何判断是否应该作为非目标：

• ❌ 这个功能对验证核心想法不是必需的 → 作为非目标
• ❌ 这个功能会大幅增加技术复杂度 → 作为非目标
• ❌ 这个功能可以通过手动方式替代 → 作为非目标
• ✅ 这个功能是产品存在的理由 → 必须包含

踩坑提醒

范围蔓延陷阱

常见的范围蔓延信号：

1. "反正很简单，顺手加一个..."
2. "竞品都有这个功能，我们也要..."
3. "用户可能会需要，不如先做出来..."
4. "这个功能很有趣，能提升产品亮点..."

遇到这些想法时，问自己三个问题：

1. 这个功能对验证核心想法有用吗？
2. 如果不做这个功能，产品还能用吗？
3. 加这个功能会推迟交付时间吗？

如果答案是"不需要"、"能用"、"会推迟"，那就果断划到非目标。

---

技巧 4：逐步迭代，快速验证

为什么

MVP（最小可行产品）的核心理念是快速验证想法，而不是一次性做完美。

通过迭代开发，你可以：

• 早期获得用户反馈
• 及时调整方向
• 降低沉没成本
• 保持开发动力

怎么做

迭代开发的步骤：

第一轮：核心功能验证

1. 使用 AI App Factory 生成第一版应用
2. 只包含最核心的 3-5 个功能
3. 快速运行并测试
4. 向真实用户展示原型，收集反馈

第二轮：基于反馈优化

1. 根据用户反馈，确定优先级最高的改进点
2. 修改 input/idea.md 或 artifacts/prd/prd.md
3. 使用 factory run <stage> 从对应阶段重新执行
4. 生成新版本并测试

第三轮：功能扩展

1. 评估是否达到核心目标
2. 选择 2-3 个高价值功能
3. 通过流水线生成并集成
4. 持续迭代，逐步完善

迭代实战示例

场景：你想做一个任务管理应用

第一轮 MVP：

• 核心功能：创建任务、列表查看、标记完成
• 非目标：成员管理、权限控制、提醒通知
• 交付时间：1 天

第二轮优化（基于反馈）：

• 用户反馈：想给任务加标签
• 修改 PRD，增加"标签分类"功能
• 从 UI 阶段重新执行流水线
• 交付时间：半天

第三轮扩展（验证成功后）：

• 增加成员管理功能
• 增加截止日期提醒
• 增加任务评论功能
• 交付时间：2 天

检查点 ✅

每次迭代前，检查：

• [ ] 新功能是否与核心目标一致
• [ ] 新功能是否有用户需求支撑
• [ ] 新功能是否会大幅增加复杂度
• [ ] 是否有明确的验收标准

---

高级技巧

技巧 5：利用分会话节省 Token

为什么

长时间运行流水线会导致上下文累积，消耗大量 Token。分会话执行可以让每个阶段独享干净上下文，大幅降低使用成本。

怎么做

在每个检查点，选择"新建会话继续"：

# 在新的命令行窗口中执行
factory continue

系统会自动：

1. 读取 .factory/state.json 恢复状态
2. 启动新的 Claude Code 窗口
3. 从下一个待执行阶段继续
4. 仅加载该阶段所需的输入文件

对比：

方式	优点	缺点
同一会话继续	简单，不用切窗口	上下文累积，Token 消耗大
新建会话继续	每阶段独享干净上下文，节省 Token	需要切换窗口

推荐做法

对于大型项目或 Token 预算有限的情况，强烈推荐使用"新建会话继续"。

详细说明见 上下文优化 教程。

---

技巧 6：处理失败和重试

为什么

流水线执行过程中可能会遇到失败（输入不足、权限问题、代码错误等）。了解如何处理失败，能让你更快恢复进度。

怎么做

失败处理的最佳实践（参考 failure.policy.md:267-274）：

1. 早期失败：尽早发现问题，避免在后续阶段浪费时间
2. 详细日志：记录足够的上下文信息，便于排查问题
3. 原子操作：每个阶段的输出应该是原子的，便于回滚
4. 保留证据：失败产物归档后再重试，便于对比分析
5. 渐进重试：重试时提供更具体的指导，而非简单重复

常见失败场景：

失败类型	症状	处理方案
输出缺失	input/idea.md 不存在	重试，检查写入路径
范围蔓延	功能数量 > 7 个	重试，要求精简到 MVP
技术错误	TypeScript 编译失败	检查类型定义，重试
权限问题	Agent 写入未授权目录	检查能力边界矩阵

失败恢复检查清单：

• [ ] 失败原因已明确
• [ ] 修复方案已实施
• [ ] 相关配置已更新
• [ ] 从失败的阶段重新开始

失败是正常的

不要害怕失败！ AI App Factory 设计了完善的失败处理机制：

• 每个阶段允许自动重试一次
• 失败产物自动归档到 artifacts/_failed/
• 可以回滚到最近的成功检查点

遇到失败时，冷静分析原因，按照失败策略处理即可。

---

本课小结

本课介绍了 AI App Factory 的六大最佳实践：

1. 清晰的产品描述：详细描述目标用户、核心问题、关键功能和约束条件
2. 检查点仔细确认：每个阶段完成后检查输出质量，避免错误累积
3. 利用非目标控制范围：明确列出不做的功能，防止范围蔓延
4. 逐步迭代：先验证核心想法，再基于用户反馈逐步扩展
5. 分会话节省 Token：在每个检查点新建会话，降低使用成本
6. 正确处理失败：利用失败处理机制，快速恢复进度

遵循这些最佳实践，能让你的 AI App Factory 使用体验更顺畅，生成的应用质量更高，开发效率提升数倍。

---

下一课预告

下一课我们将学习 CLI 命令参考。

你会学到：

• factory init 命令的所有参数和选项
• factory run 命令如何从指定阶段开始
• factory continue 命令如何新建会话继续
• factory status 和 factory list 如何查看项目信息
• factory reset 如何重置项目状态

---

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-29

功能	文件路径	行号
产品描述技巧	README.md	186-210
检查点机制	agents/orchestrator.checkpoint.md	98-112
非目标控制	README.md	199-203
失败处理策略	policies/failure.policy.md	267-274
上下文隔离	policies/context-isolation.md	10-42
代码规范	policies/code-standards.md	全文

关键常量：

• MAX_RETRY_COUNT = 1：每个阶段默认允许自动重试一次

关键规则：

• Must Have 功能数量 ≤ 7 个（MVP 原则）
• 页面数量 ≤ 3 页（UI 阶段）
• 数据模型数量 ≤ 10 个（Tech 阶段）
• 测试覆盖率 > 60%（Validation 阶段）