PID Vibe Code Framework

把 AI 开发从“想到就写”的 vibe coding，升级成“可讨论、可评审、可验收、可复盘”的工程流程。

本仓库主要提炼自原项目 bot_civ 中已经实战跑出来的流程体系、角色体系、错题本体系和规格体系。它不是业务代码模板，而是一套可以迁移到新项目里的开发框架。

一眼看懂这套流程

flowchart LR
    A["需求输入"] --> B["五方脑暴"]
    B --> C["用户拍板"]
    C --> D["IR 需求原型"]
    D --> E["五方评审 IR"]
    E --> F["SR 系统需求"]
    F --> G["AR 架构设计"]
    G --> H["测试设计 / UI 设计"]
    H --> I["开发实施"]
    I --> J["独立 Code Review"]
    J --> K["ST / 集成测试"]
    K --> L["上线总结"]
    L --> M["错误落盘 / 更新错题本"]

Loading

这套框架的核心不是“让流程变多”，而是把最容易失控的几个点钉死：

• 需求没聊透，不能直接写
• 用户没拍板，不能默认替用户做决定
• 设计没成文，不能直接大规模开发
• 代码没经过独立 CR，不能算完成
• 测试没闭环，不能进入下阶段
• 错误没落盘，下次大概率还会再犯

普通 Vibe Coding vs PID Flow

维度	普通 vibe coding	PID flow
开始方式	想到就写	先分类任务，再进流程
需求处理	靠上下文临时理解	先脑暴，再用户拍板，再成文
方案确认	往往边写边改	IR -> 评审 -> SR -> AR 逐层收敛
角色分工	一个 Agent 包打一切	Architect / Tech Lead / QA / Dev / PM 分视角
Code Review	常常自己审自己	强调独立 CR
测试	往后补，容易漏	测试设计前置，ST 闭环
复盘	问题过了就算	错题本沉淀，回灌 checklist
结果	快，但容易乱	也快，但更稳、更可接力

完整流程

阶段	名称	主要参与者	目标	产物
0	需求输入	用户 / 主 Agent	明确问题、范围、目标	任务描述、背景、边界
1	五方脑暴	Architect / Tech Lead / QA Lead / Developer / Human Proxy PM	把方向、风险、边界先聊透	候选方案、分歧点、待拍板问题、脑暴纪要
2	用户拍板	用户	对关键问题做明确选择	决策结果
3	IR 草稿	设计终端	把方向写成需求原型	IR 文档
4	五方评审 IR	五方角色	检查 IR 是否漏项、跑偏、不可验收	评审纪要、修订 IR
5	SR 系统需求	设计终端	把需求拆成系统可执行项	SR 文档
6	AR 架构设计	设计终端	补齐异常、时序、安全、边界、风险	AR 文档
7	UI 设计稿	设计终端	锁定界面与交互验收标准	UI 设计稿
8	正向串讲	Developer -> QA Lead	开发把方案讲给 QA	串讲记录、补充测试点
9	反向串讲	QA Lead -> Developer	QA 复述方案，确认理解一致	测试场景列表、补充修订
10	测试设计	QA Lead	在编码前设计验证路径	TEST 文档
11	开发实施	Developer / 多 Agent	按 SR/AR 实施，不临场漂移	代码、单测、进度记录
12	独立 Code Review	独立 CR Agent	独立找出 P0/P1/P2 风险	CR 结果、修复记录
13	UI 审美验收	独立审查 Agent	前端功能额外检查视觉和交互质量	UI review 文档
14	ST / 集成测试	QA Lead / Developer	验证真实链路是否闭环	测试报告
15	上线总结	多方确认	确认可交付、更新阶段状态	RELEASE / progress 更新
16	错误落盘	主 Agent / 相关角色	把错误沉淀进错题本和清单	error-book 更新、checklist 更新

五方脑暴到底脑暴什么

这一步不是“大家随便聊聊”，而是把同一个需求拆成五种视角，避免单一 Agent 一路自洽到底。

角色	关注点	会提出什么问题	典型产出
Architect	架构边界、模块关系、长期演进	这件事是否符合当前架构？会不会把系统做脏？	架构约束、模块拆分建议、技术红线
Tech Lead	技术可行性、复杂度、依赖顺序	真做下来难点在哪？先做什么后做什么？	技术方案、依赖顺序、工作量判断
QA Lead	可测试性、边界条件、失败路径	这个方案怎么测？哪里最容易漏？	测试风险、异常场景、验收条件
Developer	实施成本、改动范围、联动风险	需要改哪些文件？哪些点最可能出 bug？	落地路径、代码改动面、实现疑问
Human Proxy PM	用户价值、范围控制、优先级	这是不是用户真正要的？有没有更小可交付版本？	范围约束、优先级建议、待拍板议题

五方脑暴后的标准产出

产出	说明
候选方案列表	至少比较主方案和备选方案，不是一条路走到底
关键分歧点	哪些点团队内部判断不一致，需要显式展开
风险清单	架构风险、测试风险、实现风险、体验风险
用户待拍板问题	哪些决策必须让用户明确拍板，不能 AI 代拍
脑暴纪要	让讨论过程可追溯，不随着会话结束而丢失

每个阶段为什么必须有

阶段	为什么必须有	如果跳过，常见后果是什么
需求输入	防止所有后续工作建立在误解上	做了很多，但不是用户要的
五方脑暴	提前把方向、风险、边界摊开	一上来就开写，返工巨大
用户拍板	AI 不能替用户做关键决策	团队默认方向，最后用户不认
IR	把想法变成可讨论的需求原型	讨论停留在口头，没有稳定输入
五方评审 IR	检查需求原型有没有漏项和伪需求	看似清楚，落地时到处是洞
SR	把需求拆成系统可执行项	开发只能靠猜，不知道具体改什么
AR	补齐异常、边界、安全、时序	happy path 能跑，边界一碰就炸
UI 设计稿	提前锁定视觉和交互标准	做完能用，但丑、乱、不统一
正向串讲	开发把自己的理解说出来	QA 不知道开发实际打算怎么做
反向串讲	QA 用自己的话复述，查理解偏差	双方都以为对齐了，实际没对齐
测试设计	编码前先想清楚怎么验证	写完才补测，漏测严重
开发实施	严格按 SR/AR 执行	规格和实现慢慢分叉
独立 CR	避免自己审自己	很多问题会被“合理化”掉
UI 审美验收	前端不仅要能用，还要有质量	界面功能没错，但体验差
ST / 集成测试	验证真实链路闭环	单测都绿，系统一跑就断
上线总结	做完要留下可交付痕迹	下次回看，不知道做到哪
错误落盘	让错误变成资产	同类错误反复发生，没有学习效应

这套流程的卖点

强门禁，不靠自觉

很多团队不是没有流程，而是流程只是“建议”。

这套框架把关键节点做成硬门禁：

• 任务入口门禁
• 里程碑门禁
• Phase 完成门禁
• 错误落盘门禁

它的直接价值是减少这些常见失控场景：

• 还没分析完就直接写代码
• 设计没锁定就边写边改
• 只测几个 happy path 就宣布 done
• CR 没收口就推进到下一阶段
• 一个坑来回踩很多次

多角色制衡，降低单 Agent 幻觉

普通 vibe coding 的常见问题，是一个 Agent 同时扮演 PM、架构师、开发、测试和 reviewer，最后一路自洽，一路跑偏。

这套框架通过角色拆分，把不同视角强制拉进来，减少这种幻觉。

错题本驱动，越做越稳

docs/runbooks/error-books/ 是这套体系的核心资产之一。

这里记录的是实战中真实发生过的错误，包括：

• 流程错误
• 工具使用错误
• 前后端接口错误
• React / UI 错误
• Agent / 后端 / 数据库错误

这意味着：

• 新任务开始前可以预读
• 出错后可以快速归因
• 做完后还能反向更新 checklist
• 项目经验不会只存在于聊天记录里

独立评审，把“差不多”变成“真的过了”

这套流程强调：

• 设计评审和代码评审分开
• 编码 Agent 和 CR Agent 分开
• 前端实现和 UI 验收分开

核心目的是把“我觉得没问题”换成“独立检查确认过没问题”。

仓库结构

路径	作用
CLAUDE.md	全局协作规则、门禁、流程总控
docs/workflows/	完整流程、清单、协作规范
docs/personas/	五方角色和其他角色定义
docs/runbooks/error-books/	错题本、流程教训、常见失败模式
docs/runbooks/	模型选择、团队管理、进度分层等手册
docs/templates/	文档模板
docs/specs/	规格样例，可按项目替换
docs/tests/	测试文档样例
claude-progress.txt	关键决策和阶段进度记录

建议怎么开始

1. 先读 CLAUDE.md
2. 再读 docs/workflows/development-workflow.md
3. 看 docs/personas/roles.md 理解角色分工
4. 开工前读 docs/runbooks/error-books/_index.md
5. 把你自己的 PRD、spec、progress 替换进去，保留流程骨架

来源

本仓库当前内容主要提炼自 bot_civ。

可以把它理解成：

• bot_civ 是业务项目
• pid-vibe-framework 是把其中已经跑通、踩坑、复盘过的流程系统独立抽出来，变成更通用的开发框架