prd-workflow-cli 1.4.0 → 2.0.0

package/GUIDE.md

@@ -1,341 +1,248 @@
-# PRD Workflow CLI - 使用指南
+# PRD Workflow CLI - 快速使用指南
+
+> 本指南帮助你快速上手 PRD-CLI 工具
+
+---
 
 ## 目录
-- [快速上手](#快速上手)
-- [完整工作流示例](#完整工作流示例)
+
+- [核心概念](#核心概念)
+- [完整工作流](#完整工作流)
 - [与 AI 协作](#与-ai-协作)
 - [常见问题](#常见问题)
 
-## 快速上手
+---
 
-### 第一次使用
+## 核心概念
 
-```bash
-# 1. 安装
-npm install -g prd-workflow-cli
+### 术语表
 
-# 2. 初始化项目
-prd init my-product
-cd my-product
+| 术语 | 全称 | 说明 |
+|------|------|------|
+| **IT** | INVEST User Story | 符合 INVEST 原则的用户故事 |
+| **BIZ** | Business Specification | 业务需求规格（给业务方看） |
+| **DEV** | Development Specification | 技术规格说明（给开发看） |
+| **R1** | Review 1 | 规划审视（B 阶段结束时） |
+| **R2** | Review 2 | 版本审视（IT 完成后） |
+| **PM** | Product Manager | 产品经理 |
 
-# 3. 查看项目结构
-tree -L 2
-```
+### 什么是 INVEST？
+
+IT 代表 INVEST 用户故事，必须满足：
+
+- **I**ndependent（独立的）- 每个 IT 可独立交付
+- **N**egotiable（可协商的）- 细节可讨论
+- **V**aluable（有价值的）- 对用户有明确价值
+- **E**stimable（可估算的）- 开发可评估工作量
+- **S**mall（小的）- 可在一个迭代内完成
+- **T**estable（可测试的）- 有明确验收标准
+
+### 流程总览
 
-你会看到:
 ```
-my-product/
-├── 00_项目总览/
-│   └── P0_项目基本信息.md
-├── 01_产品基线/
-├── 02_迭代记录/
-├── 99_归档区/
-├── .agent/workflows/
-└── README.md
+A 阶段（基线）→ B 阶段（规划）→ IT 阶段（用户故事）→ C 阶段（版本冻结）
+     ↑               ↑                   ↑                    ↑
+   AI 生成       PM+AI 对话          PM+AI 对话            AI 自动生成
 ```
 
-## 完整工作流示例
+---
+
+## 完整工作流
 
-### 阶段一: 建立基线(首次必做)
+### 阶段一：建立基线（首次必做）
 
 ```bash
-# 1. 创建 A0 - 产品基础与范围说明
-prd baseline create A0
+# 1. 初始化项目
+prd init my-product
+cd my-product
 ```
 
-打开 `01_产品基线/A0_产品基础与范围说明.md`,填写:
+#### A0 - 产品定义（PM 手动填写）
+
+打开 `01_产品基线/A0_产品基础与范围说明.md`，填写：
+
 - 产品是什么
 - 目标用户
 - 核心场景
 - **重点**: 当前不支持什么
 
-```bash
-# 2. 创建 A1 - 已上线功能清单
-prd baseline create A1
-```
-
-列出所有**已存在**的功能和用户路径,不要写"期望有的"。
+#### A1 - 代码功能快照（AI 自动生成）
 
-```bash
-# 3. 创建 A2 - 存量反馈汇总
-prd baseline create A2
 ```
-
-整理用户反馈、数据异常、已知问题。
-
-```bash
-# 4. 创建 R0 - 基线审视
-prd baseline create R0
+💡 使用 /prd-a1-scan 让 AI 自动扫描代码生成
 ```
 
-从头到尾走一遍系统,确认基线稳定。
+> ⚠️ A1 禁止手动维护！由 AI 根据代码自动生成。
 
-✅ **基线完成后,可以开始第一轮迭代**
+---
 
-### 阶段二: 启动迭代(每轮必做)
+### 阶段二：需求规划（B 阶段）
 
 ```bash
-# 开始新迭代
+# 1. 开始新迭代
 prd iteration new
-```
 
-这会在 `02_迭代记录/第01轮迭代/` 下创建 `R1_规划启动条件检查.md`。
-
-**重要**: 填写并确认三个条件:
-
-1. ✅ 问题真实存在
-   - 在 A1 中能找到对应的功能或路径断点
-   - 或在 A2 中有用户反馈/数据支撑
-
-2. ✅ 值得单独规划
-   - 不是"顺手改一下"
-   - 会显著影响核心路径
+# 2. 创建规划文档
+prd plan create B
+```
 
-3. ✅ 问题已理解清楚
-   - 知道是哪个用户
-   - 知道在哪个场景
-   - 边界清晰
+#### B 规划文档结构
 
-⚠️ **如果任何一条不满足,不要继续!**
+`B_规划文档.md` 包含以下部分（由 PM 与 AI 对话完成）：
 
-### 阶段三: 需求规划(B 阶段)
+| 章节 | 内容 | 填写方式 |
+|------|------|---------|
+| 1. 启动检查 | 问题真实？值得做？边界清？ | PM 确认 ✅ |
+| 2. 核心问题 | 要解决什么、期望结果、不做什么 | PM 回答 AI 提问 |
+| 3. 需求拆解 | 需求列表、优先级、首版范围 | PM 决策 |
+| 4. PM 确认 | 签名确认 | PM 签字 |
 
 ```bash
-# 1. 创建 B1 - 规划草案
-prd plan create B1
+# 3. 冻结规划（自动执行 R1 审视）
+prd plan freeze
 ```
 
-在 `B1_需求规划草案.md` 中描述:
-- 规划目标(一句话)
-- 使用场景(基于 A 类现状)
-- 核心需求
-- **重点**: 明确不做什么
+✅ `freeze` 命令会自动：
+1. 检查文档完整性
+2. 执行 R1 审视
+3. 通过后生成 `B3_规划冻结归档.md`
 
-```bash
-# 2. 创建 B2 - 规划拆解
-prd plan create B2
-```
+---
+
+### 阶段三：IT 用户故事
 
-在 `B2_规划拆解与范围界定.md` 中:
-- 拆解需求项
-- 排优先级
-- 划边界
+v1.5.0 引入 INVEST 原则的 **IT 用户故事**，严格区分 BIZ 与 DEV。
 
 ```bash
-# 3. 执行 R1 规划审视
-prd review r1
+# 1. 创建 IT（自动生成 BIZ + DEV 两个文件）
+prd it create "批量导出功能"
 ```
 
-这会:
-1. 显示 AI 审视指令
-2. 生成 `R1_规划审视报告.md` 模板
-
-**与 AI 协作**:
+生成：
 ```
-请按照刚才显示的 R1 审视指令,
-审查 B1、B2 文档是否有资格冻结为 B3。
-
-请在 R1_规划审视报告.md 中填写审视结果。
+IT/IT-001-批量导出功能/
+├── IT-001-BIZ.md   # 业务需求
+└── IT-001-DEV.md   # 技术规格
 ```
 
-AI 会检查 5 个维度并给出结论:
-- [ ] 通过
-- [ ] 有条件通过
-- [ ] 不通过
+#### IT-BIZ（业务需求）
+
+| ✅ 只写 | ❌ 不写 |
+|---------|---------|
+| 用户是谁 | API 接口 |
+| 做什么 | 数据库设计 |
+| 价值 | 按钮位置 |
+| 验收标准 (AC) | 技术实现细节 |
 
-```bash
-# 4. 如果通过,冻结规划
-prd plan freeze
+```
+💡 使用 /prd-it-biz 工作流让 AI 引导你填写
 ```
 
-生成 `B3_规划冻结归档.md`,**此后规划不可随意修改**。
+#### IT-DEV（技术规格）
 
-### 阶段四: 版本需求(C 阶段)
+| ✅ AI 会做 | ❌ AI 不会做 |
+|------------|-------------|
+| 生成模板 | 编造 API |
+| 分析影响范围 | 编造 SQL |
+| 记录技术问答 | 编造算法细节 |
 
-```bash
-# 1. 创建 C0 - 版本范围
-prd version create C0
 ```
-
-在 `C0_版本范围声明.md` 中:
-- 版本目标(基于 B3)
-- 本版包含什么
-- 本版不包含什么
-
-```bash
-# 2. 创建 C1 - 版本需求清单
-prd version create C1
+💡 技术细节需要通过对话询问技术负责人，AI 只记录答案
 ```
 
-在 `C1_版本需求清单.md` 中:
-- 逐条列出需求
-- 每条说明目的
-- 关键规则
-
-```bash
-# 3. 执行 R2 版本审视
-prd review r2
-```
+---
 
-AI 会检查:
-- C0/C1 是否忠于 B3
-- 有没有"顺手加戏"
-- 需求粒度是否成熟
+### 阶段四：版本冻结（C 阶段）
 
 ```bash
-# 4. 如果通过,冻结版本
+# 冻结版本（自动执行 R2 审视）
 prd version freeze
 ```
 
-生成 `C3_版本冻结归档.md`,**标志产品需求阶段完成**。
+✅ `freeze` 命令会自动：
+1. 执行 R2 审视（检查 IT 是否忠实于 B3）
+2. 汇总所有 IT 文档
+3. 生成 `C3_版本冻结归档.md`
+4. PM 只需签名确认
+
+---
 
 ## 与 AI 协作
 
-### 场景一: R1 审视
+### 场景一：IT-BIZ 编写
 
 ```
-我已经完成了 B1、B2 文档。
-
-请你扮演【产品规划审视官】,按照以下 5 个维度审视:
-1. 目标清晰性
-2. 场景真实性
-3. 现状一致性
-4. 范围收敛性
-5. 版本化准备度
-
-请参考:
-- 01_产品基线/ 下的 A 类文档
-- 当前迭代的 B1、B2 文档
-- .agent/workflows/prd-r1-review.md 中的详细指令
-
-请在 R1_规划审视报告.md 中填写审视结果,
-并给出明确的通过/不通过结论。
-```
-
-### 场景二: R2 审视
+用户: 我想写"批量导出"的业务需求
 
-```
-请你扮演【版本一致性审视官】,检查:
-C0、C1 是否忠实执行了 B3 的规划。
-
-审视维度:
-1. 版本目标一致性
-2. 版本范围偏移检查
-3. 规划覆盖完整性
-4. 需求粒度成熟度
-5. 进入执行准备度
-
-参考 .agent/workflows/prd-r2-review.md 中的详细指令,
-在 R2_版本审视报告.md 中填写结果。
-```
+AI: 好的，请告诉我：
+    1. 谁使用这个功能？
+    2. 在什么场景下使用？
+    3. 期望达到什么效果？
 
-### 场景三: 规划协作
+用户: 运营人员...
 
+AI: (根据回答生成 IT-xxx-BIZ.md)
 ```
-我想为产品添加一个新功能。
 
-先帮我检查 R1 启动条件:
-1. 这个问题是否在 A1/A2 中有依据?
-2. 是否值得单独规划?
-3. 问题边界是否清楚?
+### 场景二：IT-DEV 填充
 
-然后我们一起完成 B1 规划草案。
 ```
+用户: 现在写 DEV 文档
 
-## 常见问题
+AI: 好的，已生成模板。请技术负责人确认：
+    1. 涉及哪些 API 变更？
+    2. 需要修改哪些数据表？
+    3. 异常情况如何处理？
 
-### Q1: 必须严格按顺序吗?
+用户: 需要新增一个 /api/export 接口...
 
-**A**: 是的。这是强制流程:
+AI: (记录回答，不编造细节)
 ```
-A → R1 启动检查 → B1/B2 → R1 审视 → B3 → C0/C1 → R2 审视 → C3
-```
-
-任何跳过都可能导致:
-- 规划膨胀
-- 需求蔓延
-- 反复返工
-
-### Q2: R1 不通过怎么办?
-
-**A**: 有三种情况:
-
-1. **不通过**: 说明这个问题不该开启规划
-   - 可能是小修小补,不需要独立迭代
-   - 可能问题还没想清楚
-   - 建议: 先解决启动条件问题
-
-2. **有条件通过**: 补充指定内容后可通过
-   - 修改 B1/B2
-   - 重新执行 `prd review r1`
 
-3. **通过**: 执行 `prd plan freeze`
+### 场景三：A2UI 可视化
 
-### Q3: 基线文档一定要做吗?
-
-**A**: 第一轮迭代前必须做,后续迭代可以:
-- 直接使用(如果产品稳定)
-- 更新(如果有重大变化)
+```
+用户: 这个页面顶部有个搜索栏，下面是列表
 
-**不做基线的风险**:
-- AI 会假设不存在的能力
-- 规划会"从零重建"
-- 失去现状约束
+AI: 收到，我为您生成界面原型图...
+    (自动生成并提示刷新预览)
+```
 
-### Q4: 可以同时进行多个迭代吗?
+---
 
-**A**: 每个项目同时只能有一个活跃迭代。
+## 常见问题
 
-原因:
-- 每个迭代都需要审视
-- 并行会导致冲突和混乱
+### Q1: 为什么废弃了 B1/B2？
 
-如果有多个需求:
-- 在 B2 中全部列出
-- 排优先级
-- 分批进入版本
+**A**: 为了简化流程。v1.5.0 将规划、拆解、审视整合到一个 `B_规划文档` 中，减少文件切换。
 
-### Q5: B3 冻结后还能改吗?
+### Q2: 为什么一定要分 BIZ 和 DEV？
 
-**A**: 不建议,除非:
-- 外部约束变化(如合规要求)
-- 发现重大风险
+**A**: 
+- **BIZ** 是给老板、业务方看的，承诺"做什么"
+- **DEV** 是给开发看的，指导"怎么做"
+- 混合在一起会导致逻辑混乱，且容易让 AI 产生幻觉
 
-修改流程:
-1. 说明变更原因
-2. 更新 B3
-3. 重新执行 R1 审视
-4. 如果已进入 C 阶段,需要同步更新
+### Q3: AI 为什么不帮我写 SQL 了？
 
-### Q6: 与传统 PRD 的区别?
+**A**: v1.5.0 增加了严格的防幻觉限制。AI 不了解你的私有数据库结构，编造 SQL 只会误导开发。AI 的角色转变为"引导者"和"记录员"。
 
-**A**: 
+### Q4: 必须每个 IT 都写吗？
 
-| 传统 PRD | 本工具 |
-|----------|--------|
-| 一次写完 | 分阶段,有闸门 |
-| 想到哪写到哪 | 强制基于现状(A 类) |
-| 需求容易膨胀 | R1/R2 审视控制 |
-| 规划和版本混在一起 | B/C 严格分离 |
-| 人工审查 | AI 可执行审视 |
+**A**: 是的。每个独立的功能点（User Story）都应该由 BIZ + DEV 组成。微小改动可以合并，但必须保持结构。
 
-### Q7: 适合什么规模的项目?
+### Q5: C0 和 C1 去哪了？
 
-**A**: 
+**A**: 已废弃。C0/C1 的功能被 IT 用户故事替代。C3 由 `prd version freeze` 自动生成。
 
-- ✅ **适合**: 需要多轮迭代的产品
-- ✅ **适合**: 团队需要规范约束
-- ✅ **适合**: 与 AI 协作开发
-- ⚠️ **可选**: 一次性项目
-- ⚠️ **可选**: 原型验证阶段
+---
 
 ## 下一步
 
-1. 📖 阅读 [文档结构说明](/原始资料素材/2、产品输出文档结构.md)
-2. 🔍 理解 [R1 启动条件](/原始资料素材/5、R1进入B1的条件.md)
-3. 🤖 学习 [R1、R2 审视指令](/原始资料素材/7、R1、R2审视指令.md)
-4. 📊 查看 [B3 与 C 的边界](/原始资料素材/8、B3 与 C0 、 C1 的边界定义.md)
+1. 📖 阅读 [README.md](./README.md) 了解完整功能
+2. 🤖 体验 `/prd-a1-scan`、`/prd-it-biz`、`/prd-it-dev` 工作流
+3. 📝 查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本历史
 
 ---
 
-**记住**: 这个工具的核心价值不是"写更多文档",而是"防止写错误的文档"。
+**记住**: 这个工具的核心价值不是"写更多文档"，而是"防止写错误的文档"。