PIV - Plan Implement Validate

核心用法

PIV (Plan-Implement-Validate) 是一个系统化的多阶段软件开发工作流编排器，设计用于将大型特性拆解为可管理的阶段并自动化执行。

工作流程

启动方式：

• PRD路径模式：piv /path/to/feature.md [起始阶段] [结束阶段]
• 项目路径模式：piv /project/path [起始阶段] [结束阶段]

七阶段循环：
1. PIV初始化 - 创建PRDs/PRPs目录结构，复制模板文件
2. PRP检查/生成 - 通过子Agent执行代码库分析并生成阶段PRP（产品需求计划）
3. 执行器派遣 - 调用piv-executor子Agent执行PRP，输出执行摘要
4. 验证器派遣 - 调用piv-validator子Agent独立验证，输出验证报告
5. 调试循环（如需要）- 最多3轮调试迭代修复问题
6. 智能提交 - 生成语义化Git commit，带Built with FTW标识
7. 阶段迭代 - 更新WORKFLOW.md并进入下一阶段

架构特点

• 纯编排器设计：自身不执行代码，通过sessions_spawn创建独立子Agent
• 上下文隔离：每个子Agent获得100%新鲜上下文，避免污染
• 模板驱动：PRP基于标准化模板生成，确保一致性

显著优点

1. 系统化分阶段开发：将复杂特性拆解为可验证的阶段，降低认知负荷
2. 自动化验证闭环：每个阶段强制经过执行→验证→调试→提交的完整周期
3. 质量门禁机制：验证失败自动触发调试循环，3次失败后人工介入
4. 可追溯文档流：WORKFLOW.md记录完整执行历史，PRPs/目录保留所有计划
5. 零执行风险：自身仅含Markdown指导文档，无实际代码执行

潜在缺点与局限性

1. 依赖外部模板：需要{baseDir}/assets/prp_base.md等模板文件存在
2. Git依赖硬性要求：必须安装git，且项目需在版本控制下
3. 子Agent可靠性：实际执行质量取决于piv-executor/piv-validator等子Agent实现
4. 调试深度受限：固定3轮调试上限，复杂问题可能需人工接管
5. PRD前置要求：无PRD时无法启动，不支持从零创建项目
6. 平台限制：仅支持Darwin/Linux（metadata声明）

适合人群

• 开发复杂多阶段特性的软件团队
• 需要PRD→代码可追踪流程的合规场景
• 采用多Agent协作开发模式的技术团队
• 希望自动化验证减少人工代码审查的工作流

常规风险

• 子Agent超时：执行或验证Agent可能超时，需人工检查部分成果
• PRP与代码脱节：若代码库变化快，生成的PRP可能过时
• 验证标准不一致：不同Validator Agent可能对"通过"定义有差异
• 提交污染风险：自动化Git commit若配置不当可能影响主干历史
• 维护依赖：个人开发者项目(T3来源)，长期维护稳定性需关注

核心用法

piv 是一款面向复杂软件项目的 多阶段工作流编排器，采用 Plan-Implement-Validate（计划-执行-验证）循环模型。用户可通过两种模式启动：

• PRD 路径模式：直接指定 .md 格式的 PRD 文件路径，自动推导项目根目录与阶段范围
• 项目路径模式：指定项目根目录，自动发现 PRDs/ 文件夹中的需求文档

支持 1-4 阶段（或 PRD 自定义阶段数）的渐进式开发，每个阶段包含：PRP（阶段计划）生成 → Executor 执行 → Validator 验证 → Debugger 调试（最多 3 轮循环）→ 智能提交与文档更新。

显著优点

1. 系统化分阶段开发：强制将大型功能拆解为可独立验证的阶段，降低单点失败风险
2. 多代理架构：通过 sessions_spawn 创建专用子代理（Researcher/Executor/Validator/Debugger），每个代理拥有独立上下文，避免上下文污染
3. 自动化验证闭环：每个阶段执行后强制验证，失败自动进入调试循环，确保 "First Try Works" 质量承诺
4. 代码库感知：内置 codebase-analysis 能力，生成 PRP 时自动考虑现有代码结构
5. 可追溯性：自动生成 WORKFLOW.md 与阶段性提交，保留完整开发轨迹

潜在缺点与局限性

• T3 来源风险：维护者为个人开发者（SmokeAlot420），缺乏企业级维护承诺
• 依赖子代理生态：实际效果高度依赖底层 LLM 子代理的执行质量，对模型能力要求较高
• 调试循环上限：3 轮调试后强制人工介入，复杂重构场景可能需频繁人工参与
• 仅支持 Markdown PRD：未集成 Jira/Linear 等主流项目管理工具
• 缺乏可视化：无内置看板或进度仪表盘，依赖 WORKFLOW.md 文本追踪

适合人群

• 采用 AI 辅助编程的独立开发者或小型团队
• 需要严格阶段验收的咨询/外包项目
• 希望通过 PRD/PRP 文档强制规范开发流程的技术负责人
• 多模块并行开发、需频繁验证集成点的复杂项目

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 子代理失控 | 子代理可能误解 PRP 产生偏离预期的实现 | 严格 PRD 评审，保留人工检查点 |

| 验证标准漂移 | Validator 与 Executor 对"完成"定义可能不一致 | 明确可测试的验收标准 |

| 循环依赖死锁 | 阶段间未解耦可能导致调试循环无法收敛 | 阶段边界设计时保持独立可测试 |

| 上下文窗口压力 | 大型代码库分析可能触发 token 限制 | 配合 codebase-analysis 的切片策略 |

使用建议

首次使用建议先用 --start-phase 1 --end-phase 1 单阶段试运行，验证 PRD/PRP 模板与项目结构匹配度，确认子代理行为符合预期后再扩展至多阶段。