# bworkflow

**Repository Path**: being_xyk/bworkflow

## Basic Information

- **Project Name**: bworkflow
- **Description**: 适合于中小型产品、项目，复杂领域工具落地的研发工作流
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-04
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BWorkflow 简介

> 一句话：BWorkflow 是一套面向「人 + AI 编程助手」团队的项目交付规则层，通过显式 gate、可验证的退出标准和最小化的人为决策点，让中小规模项目在高速迭代中仍保持可控。

## 版本说明：v1 → v2

- **v1（分支 `v1`，发行包 1.0.0）**：为上一代 model + harness 工程能力设计，规则定得较死，用细粒度约束兜底 Agent 的不稳定。
- **v2（当前方向，发行包 2.0.0）**：面向更强的 Coding Agent 重新设计——规则层只告诉 Agent **流程**（一条自由的管道），让 Agent 在管道指引下尽可能发挥自身能力，不再用过细的规则约束挤占上下文、分散有效注意力。规则做护栏，不做车道。

Agent 工作指南统一收口在 [`AGENTS.md`](AGENTS.md)；[`CLAUDE.md`](CLAUDE.md) 仅通过 `@AGENTS.md` 导入它，不再单独维护内容。

## BWorkflow 与“剩余判断权”

BWorkflow 把交付中最难守住的环节，看成一类特殊的决策：**在不完备的信息之后，必须有人为不确定的未来拍板，并承担后果**。我们把这类决策概括为五件事——**定题、立尺、下注、授权、改判**——它们都是高耦合、低可逆的“单向门”决策，也是 BWorkflow 要工程化的核心对象。

BWorkflow 把这五件事翻译成一套可执行的 gate 系统：

| 五件事 | BWorkflow 中的 gate / 阶段 | 为什么必须显式裁决 |
|---|---|---|
| **定题** | S0 项目定级（[H] `mode-chosen`） | 决定“这项目值不值得进入流程、用哪种模式”，定错则后续全错 |
| **立尺** | S0 的定级标准（Q1–Q5）+ S2 的 `constitution.md` / 验收标准 | 目标函数、优先级、回滚成本、验收尺度必须事先写下 |
| **下注** | S2 设计锁定（[H] `design-approved`） | 技术栈、架构方向、范围取舍是互斥战略，必须有人拍板 |
| **授权** | S2 / SL `design-approved`（含执行边界的授权） | 一线可自主决策的范围由设计锁定划出；执行结果由 S4 机器门禁验证 |
| **改判** | S3 Spike（Go/No-Go）+ S5 用户验证（`value-accepted`）+ S6 循环熔断 | 预设证据出现时必须认错、止损或改向 |

这套映射不是为了把人的职责“外包”给流程，而是把**单向门决策从“靠自觉”变成“靠结构”**。AI 不会累、不会侥幸，但也不能替人承担后果；BWorkflow 让机器 gate 守住可裁决的部分，让人只在必须拍板的位置拍板。

---

这套流程不是发明，而是复原——复原软件工程面对复杂交付时本该有的样子。以下各个阶段都不是创新，只是忠实地遵循了这条早已被反复验证的路：分阶段是为了把复杂性拆开、让它可被逐段消化，而每一个阶段，都在回答一个具体的质量问题。

问题从来不是"没人知道该这么做"——TDD、代码审查、设计先行，这些是写进教科书的常识。真正的问题是人守不住：在实现落地的疲惫里、在赶工的压力下、在"就这一次先跳过"的侥幸中，纪律恰恰在最该坚持的地方被一点点磨掉。这份不可控，过去没有好的解法，只能靠自觉和意志力去扛。

Agent Coding 第一次让它有了确定性的解法：AI 不会累、不会为赶进度而偷工，而明确的 gate 让"跳过"在结构上就不可能——机器门禁不绿就进不去，人该拍板的地方机器代不了。它把"人会跳过"这个最大的不可控，降到了最低。

所以，哪怕你不使用 BWorkflow 的规则与 runtime，这套流程本身依然成立、依然是一份值得依循的指导；BWorkflow 做的，只是借着 AI 与 gate，把这份人人认同却难以坚持的纪律，第一次变得可执行、可裁决、不可绕过。

---

## 一、BWorkflow 不是什么

在理解它之前，先排除几个常见误解：

- **它不是项目管理软件**。没有看板、没有甘特图、没有任务派发。
- **它不是一套提示词模板**。虽然它已沉淀为 Claude Code skill（`skills/` 目录），但它的核心是可验证的规则，而不是一段好 prompt。
- **它不是替代你做决定的 AI**。AI 负责执行与事实核查，但方向、资源、风险接受必须由人拍板。
- **它不是万能流程**。复杂系统、多团队耦合、需求极度模糊的项目，本流程明确不适用；正确做法是先拆分领域，再分别进入 BWorkflow。

---

## 二、它解决什么问题

当团队里有一个或多个 Claude Code 这类 AI 助手时，常见的问题不是"AI 不会写代码"，而是：

- **决策责任模糊**：AI 应该继续推进还是停下来问人？
- **完成标准含糊**："看起来可以了"算不算阶段结束？
- **错误方向拖到太晚**：需求理解错了、设计有重大漏洞，往往到验收才发现。
- **人在不该介入的地方被反复打断**：每个小决定都要人确认，反而拖慢节奏。
- **人在该介入的地方被跳过**：AI 悄悄做了不可逆承诺，事后才发现。

BWorkflow 用规则把这些问题显式化：每个阶段开始前要什么、结束后交付什么、谁来做最终裁决，都写清楚。

---

## 三、它是一套 Agentic Engineering 的质量地图

介绍 BWorkflow 时如果只讲"有哪些阶段、哪些 gate"，听起来像流程官僚。要讲清它的价值，得先立一个前提：

> **Agent 让"写代码"变得又快又便宜，于是瓶颈从"产出"移到了"控制方向"和"验证正确”。**

Vibe coding 之所以是 Vibe，是因为它默认接受 Agent 产出的"看起来对"的东西——在瓶颈还是产出速度的年代，这没问题。但当产出接近免费，**质量的全部战场就转移到了两个问题上：方向对不对、成果真不真**。BWorkflow 的价值，就是把这两个问题**落进一套可被机器裁决、被人拍板的 gate 系统**。

它的方法不是发明新工程理论，而是把**行业公认、可独立验证的软件工程手段**，钉进具体阶段，并给出明确的裁决方式：

| 工程手段 | 在哪个阶段落地 | 怎么被裁决（确定性锚点） |
|---|---|---|
| **设计文档先行纪律**：spec / plan / constitution 先行，编码后置 | S2 产出并锁定设计包；S4 严格按锁定 design 实现 | 设计包版本一致 + 用户显式批准（**硬 gate**）；实现偏离必须走 S6 proposal |
| **DDD 领域驱动设计**：统一语言、核心域/支撑域、限界上下文 | S2 的 `constitution.md` 三节 + 条件性 `domain-model.md` | 用领域原语与限界上下文帮 AI 理解复杂领域；多模块且有共享领域概念时必须先出 `domain-model.md`；术语改动按 Type-B 设计变更同步所有引用 |
| **TDD 测试驱动**：先写失败测试 → 最小实现 → 重构保持绿 | S4 开发落地 | `test` 命令退出码 0（[M-cmd]），覆盖率由命令自身判定，不靠 AI 解读 |
| **质量门禁**：测试 / 构建 / 项目声明的质量组合 | S4 | `tests` / `build` / `quality-gates-passed` 全绿，[M-cmd] 无例外放行；`quality-gates-passed` 由 `bworkflow.yaml` 定义，**建议以关键路径行为验收为主** |
| **每一轮代码审查**（审查只读、不改代码） | S4 每个 plan 落地即审；S6 每个变更回归通过后审查 | 落成 `verify.code-review-passed`（[M-cmd]）：S4 按 plan 分节进审查报告、S6 写入 proposal「代码审查」小节并卡住 IMPLEMENTED；S4 全部 plan 审查通过且无阻塞问题后自动进入 S5，发现问题由 Agent 回 S4 修复或转 S6 |
| **端到端测试的专业建议** | S4 的 e2e 必要性 | 工具给出是否需要 E2E 的**建议**，结论写入报告正文「Agent 自检」——如实标注、不阻塞推进 |
| **集成测试** | S2 必须产出集成类 `plan-integration.md` | 覆盖开发环境、前置资源、接口交互、集成测试 |
| **变更可追溯 + 回归 + 审查 + 归档**：Delta Spec / proposal 审批 / 旧版 design 文档版本化 | S6 需求变更 | 变更先分类 + proposal 批准 + `verify.regression` 退出码 0 + 每个变更只读代码审查（`verify.code-review-passed`，卡 IMPLEMENTED）+ 文档同步 + Type-A/B/0 调用 `bwf.js archive` 归档 |

关键不在于"用了这些实践"——很多团队都知道该做 TDD 和 code review。关键在于，**BWorkflow 把每一项都翻译成了一条机器可裁决、或人必须显式拍板的 gate**：TDD 落成 `test` 退出码，代码审查落成 `code-review-passed`，回归落成 `verify.regression`，端到端则如实落成一条不阻塞的专业建议。行业最佳实践因此从"应该做"变成"过不了就进不了下一阶段"。

这些 gate 一起挡住了 Vibe 最常见的六种失效：

| Vibe 下会发生的事 | BWorkflow 的规则 | 它换来的质量 |
|---|---|---|
| "看起来好了"就算完成，标准可协商 | **[M-cmd] 退出码 0 即过 / `result=pass`** | **完成从主观变成可裁决**——done 的定义不再随人的疲惫和 Agent 的乐观而漂移 |
| 需求理解错、设计有洞，拖到验收才炸 | **S0/S2/S5 硬 gate 强制停顿** | **错误在最便宜的时刻被拦下**——把人最贵的判断前移到改起来还便宜的位置 |
| 每个小决定都问人 / 或 Agent 偷偷替人拍板 | **两轨 + 三档判定（[V]/[H] 不可被机器跳过）** | **人的注意力只花在机器真的决定不了的地方**，且这些地方机器无法悄悄越过 |
| "我们现在到哪了"各人记忆不一致 | **`result` 块 + `state.yaml` 机器独占** | **单一事实源**——决策被记录、可审计、被下游门禁消费，不被反复重议 |
| 同一个 bug 反复修不过，空转到有人放弃 | **S4-S6 循环熔断 + [H] 升级** | **循环有收敛保证**——要么修好，要么强制升级为一次显式决策，不允许无声空转 |
| 让模型给自己的作业打分 | **机器门禁走 `bwf.js` 脚本执行、退出码裁决；变更分类与人轨提问由 agent 按确定性规则执行，runtime 记录并校验** | **Agent 的确定性被最大化、不确定性被隔离**——LLM 无权用自己的理解判定 gate，只能按规则执行命令或向人呈现选择题 |

最后一行是**最反 Vibe 的一招**：**你不信任模型给自己判卷**。机器门禁的裁决权交给确定性脚本（退出码、`result.status`）；变更分类、人轨提问则由 agent 按 `rules/` 与 `Agent执行契约` 中的确定性规则执行，runtime 负责记录与校验。这一刀把"AI 说它做完了"和"事实上做完了"在机器可验证的层面上劈开了。

对 Claude Code 这样的 Harness 而言，BWorkflow 提供的正是一张 **Agentic Engineering 的质量地图**：它告诉 Agent 在每一步该调用哪种工程实践、产物长什么样、由哪条命令或哪个人来裁决。Agent 不再"凭感觉写完就交"，而是沿着这张地图，把设计文档先行纪律、DDD、TDD、代码审查、端到端验证这些确定性手段一站一站落实——这才是 Agentic Coding 从 Vibe 走向工程的实际路径。

> 大多数团队的"工程规范"是一篇没人读的 wiki。BWorkflow 的规则（`rules/`）是 skill 与 runtime 的**共同权威来源**：skill 按规则生成产物与 `verify / human_verify` 块，runtime 按规则约定的 schema 执行命令、维护状态。它在工具层被执行，不在文档层被朗诵——靠 gate 而不是靠自觉。

### 规则是护栏，不是车道

BWorkflow 的规则只规定"到下一站必须满足什么条件"，不规定"必须以什么顺序、什么方式到达"。Agent 在护栏内拥有**方法自治权**：可以自主决定实现顺序、可以写 `spike/` / `explore/` 一次性代码验证设计、可以选择最佳路径——只要最终通过机器门禁和硬 gate。

这让规则层成为**兜底系统**而不是**操作手册**：它挡住不可接受的结果，但不压缩 Agent 的解题空间。最强模型的价值，正是在护栏内高速行驶。

---

## 四、每一步都在把不可控拉回正轨

BWorkflow 的每个阶段都不是"又一道手续"，而是**针对一种特定的失控，把它拉回可控轨道**。用一句话理解每一步的意义：

| 阶段 | 一句话意义：它把什么不可控拉回正轨 |
|---|---|
| **S0 项目定级** | 把"这项目到底该怎么做"的模糊，拉回到一个确定的模式档位——不让流程用得过轻或过重。 |
| **S1 调研** | 把零散、口头、隐含的输入，拉回成一份结构化、可设计的清单——不让人带着未言明的假设开工。 |
| **S2 设计锁定** | 把"边做边想"的设计漂移，拉回到一份被显式批准、锁定的设计包——不让设计在开发中被无声改写。 |
| **S3 核心难点 Spike** | 把"不知道能不能做"的技术风险，拉回成一个已验证的 Go/No-Go 事实——不让未验证的假设当地基。 |
| **SL 轻量设计锁定** | （轻量模式）把小项目的方向一次性拉定——不让小工具背上重流程，也不让它连方向都不锁就开工。 |
| **S4 开发落地** | 把实现拉回到锁定的设计边界内，任何偏离都得走 S6——不让范围在编码中悄悄蔓延。 |
| **S5 用户验证** | 把"我以为做对了"，拉回到"用户按验收场景确认对了"——不让自证清白式验收蒙混过关。 |
| **S6 需求变更** | 把任何变更（bug / 新需求 / 设计缺口）拉回统一的 proposal 通道，并在 Type-A/B/0 批准后归档旧版 design 文档——不让人绕过审批直接改代码或设计，也不让变更在历史中蒸发。 |

> 串起来看：**方向失控在 S0/S2 拉回，技术失控在 S3 拉回，实现失控在 S4 拉回，认知失控在 S5 拉回，变更失控在 S6 拉回。** 每一道 gate 都是一次"重新对齐正轨"的机会，而硬 gate（S0/S2/S5）是其中错了就回不去的那几次，所以必须由人拍板。

一句话收口：

> **BWorkflow 不让 Agent 变得更聪明，它让“错的东西过不了 gate”。** 在产出近乎免费的时代，这才是工程质量的杠杆——不是提高单次产出的下限，而是让交付链上的每一个错误，都必须在最便宜的时刻、由该负责的人显式面对。

---

## 五、流程 harness 与三层防护

BWorkflow 不是技术层面的 harness（子代理隔离、上下文管理、Skills 机制），而是**流程层面的 harness**。它的目标不是让 Agent 变聪明，而是让“错的东西过不了 gate”。把它放进完整的技术-组织图景里，它属于中间层：

| 层级 | 管什么 | 在“人 + AI”团队中的对应 |
|---|---|---|
| **技术 harness** | Agent 执行能力：稳、不失控 | Claude Code / 子代理 / 上下文 / Skills |
| **流程 harness** | 决策边界：哪些 gate 必须过、谁拍板、路径不能跳 | BWorkflow 的 `rules/`、`runtime/bin/bwf.js`、阶段报告机器块 |
| **组织 harness** | 剩余判断权：在不完备信息后设定主观战略并承担责任 | 项目负责人 / 用户本人在 [H] 硬 gate 上的最终裁决 |

BWorkflow 负责把中间层做厚：把**定题、立尺、下注、授权、改判**翻译成可执行的 gate，让 Agent 在护栏内高速行驶，同时保留人对不可结构化判断的最终裁决权。

---

## 六、核心模型：两轨 + 三档判定

### 5.1 两轨

| 轨道 | 谁主导 | 目标 |
|---|---|---|
| **机器轨** | Claude Code / 脚本 | 确定性执行最大化：检查、运行、记录、推进 |
| **人轨** | 项目负责人 / 领域专家 | 不可替代判断最小化：只在硬 gate 和语义不清处拍板 |

设计原则：**假设人是最不可控的元素**。规则为 AI 而写，同时吸收人的不确定性。

### 5.2 三档判定

每个完成标志只归入三类之一：

- **[M-cmd] 机器命令裁决**  
  由 `node .b_workflow/bin/bwf.js verify <stage>` 执行报告中的命令。约定：**退出码 0 即过**。阈值内建于命令本身，不依赖 AI 解读。

- **[V] 人查证回报**  
  工具说不清语义时，不下结论。AI 生成选择题请人确认，再调用 `bwf.js result` 记录。

- **[H] 人专业判断**  
  发愿、给资源、判断风险——这类事工具永不代答。必须由 `by: user` 记录才生效。

这种分类的实质是：**把"人必须出现"的节点压缩到最少，同时确保这些节点无法被机器跳过。**

---

## 七、硬 gate 与软 gate

BWorkflow 根据项目规模提供两种进入模式：

| 模式 | 路径 | 适用场景 |
|---|---|---|
| **完整模式** | S0 → S1 → S2 → S3 → S4 → S5 | 独立中小项目，需求可锁定；价值验收通过即交付完成 |
| **轻量模式** | S0 → SL → S4 → S5 | 小型独立工具 / 脚本 / 实验，无分发形态，变更成本低 |

**硬 gate** 是那些"错了代价不可逆"的节点：

- 完整模式：**S0 项目定级**、**S2 设计锁定**、**S5 价值确认**
- 轻量模式：**S0 项目定级**、**SL 轻量设计锁定**、**S5 价值确认**

其余阶段为软 gate：它们也有明确完成标准，但错误相对容易在后续循环中修正。

> **术语提示**：BWorkflow 里“硬 gate / 软 gate”指**阶段层面是否必须由人拍板且代价不可逆**；而 gate 内部到底是机器裁决（[M-cmd]）还是人判断（[H]/[V]），由“三档判定”进一步区分。机器可裁决的 [M-cmd] 对应“硬标准”，必须由人拍的 [H] 对应“硬判断”，二者共同构成“跳过在结构上不可能”。

> 复杂项目（多系统、多团队、需求高度不确定、模块耦合极重）**不属于可进入模式**。正确做法是拆分领域或子系统，每个子系统作为独立项目重新定级。

---

## 八、人在哪里决策

作为负责人，你只在以下位置被要求拍板：

1. **S0 / 项目定级**：选择完整模式、轻量模式，还是拒绝/拆分项目。
2. **S2 或 SL / 设计锁定**：确认设计文档包是否被接受，是否进入开发。
3. **S5 / 价值确认**：确认验收结果，决定是否接受当前产出。
4. **[V] 查证项**：当工具无法判断语义或事实时，回答 AI 提出的选择题。
5. **[H] 专业判断项**：涉及资源、风险接受、方向选择时，做出判断。
6. **S4-S6 循环熔断**：同一验收项反复修复不过时，选择"接受风险 / 回退设计 / 中止 / 扩大范围"。

把以上拍板点放回“剩余判断权”的五件事里，它们分别对应：

- **定题**：S0 模式选择 / 拆分接受；
- **立尺**：S0 定级标准（Q1–Q5）+ S2 验收标准确认；
- **下注**：S2 / SL 设计锁定批准；
- **授权**：S2 / SL `design-approved`（划定 Agent 可自主决策的执行边界；S4 机器门禁验证执行结果）；
- **改判**：S3 Go/No-Go、S5 `value-accepted`、S6 `proposal-approved` / `loop-escalation`。

此外，当某个 gate 被未预设情形卡死时，人可以**显式覆盖** Agent 的默认结论并通过 `result` 记录，这是流程的“人工超控”安全阀——不是缺陷，而是给剩余判断权留的通道。

其余时候，AI 按照规则推进，并在每次推进前调用 `bwf.js` 校验门禁。

---

## 九、质量怎么保证

BWorkflow 的质量观不是"最后检查一遍"，而是**把质量内建于每个阶段**：

- **阶段内 verify 命令**：机器用命令触达事实，退出码说话。
- **跨阶段 requires 门禁**：进入下一阶段前，必须读取上游报告的 `result` 块，确认 status 为 pass。
- **硬 gate 强制停顿**：在不可逆投入前必须得到人的确认。
- **循环熔断机制（规则层已定义）**：`rules/S6-需求变更.md` 已定义 S4 → S5 → S6 验收-修复小循环中按 `acceptance_item_id` 的同根因失败计数、同一根因判定与 `loop-escalation` 人工升级，防止同一验收项无声空转。
- **状态机只读/写机器块**：`.b_workflow/state.yaml` 与报告末尾的 `verify / human_verify / result` 块由 `bwf.js` 独占维护，避免手工状态漂移。

> 当前 `runtime/bin/bwf.js` 已实现状态维护、`verify` 执行、跨阶段 `requires` 校验与 proposal 状态推导。**2026-07 起 runtime 不再维护循环熔断的 cycle 计数与动态注入**——循环熔断改由规则 + Agent 承载：Agent 在 S5 报告中按 `acceptance_item_id` 标记同根因失败次数，N≥2 且同根因时自行生成 `[V] same-root-cause` / `[H] loop-escalation`，并在 `transition S4/S5` 时由规则阻塞未解决的 escalation（详见 `rules/S6-需求变更.md`）。

一句话：**质量不是靠人盯着每一步，而是靠规则让错误过不了 gate。**

---

## 十、对团队意味着什么

如果你是项目负责人：

- 你不需要 micromanage 每一次提交，但要认真对待硬 gate。
- 你的"是/否"会被记录为 `result` 块，成为后续阶段的唯一可信依据。
- 你可以信任机器门禁的结果，但不能让 AI 替你承担不可逆决策。

如果你是使用 Claude Code 的开发者：

- 每个阶段开始前读对应的 skill / rules 文档。
- 只写报告正文，不动 `state.yaml` 和机器块。
- 遇到 [V] / [H] 项就停下来请人确认，不要自己猜。

---

## 十一、适用边界

BWorkflow 最适合：

- 需求可以在合理时间内锁定或分片的中小项目。
- 团队里有 AI 编程助手承担大量执行工作。
- 项目有明确的交付物（代码、文档、可运行产物）。
- 负责人愿意在关键节点做不可推卸的判断。

BWorkflow 不适合：

- 需求极度模糊、方向本身还在探索的产品。
- 大型复合系统，包含多个独立子系统或团队。
- 模块间耦合极重，单模块变更会级联影响多个系统。
- 变更频率高到无法在任何时刻锁定设计。

对于以上场景，正确做法是：先拆分，再进入 BWorkflow。

---

## 十二、下一步

如果你刚接触 BWorkflow，建议按这个顺序阅读：

1. [reference/KEY-ELEMENTS.md](reference/KEY-ELEMENTS.md) —— 总览速查。
2. [rules/S0-项目定级.md](rules/S0-项目定级.md) —— 决定你的项目该走哪条路。
3. [runtime/README.md](runtime/README.md) —— 如何在目标项目中启用 `.b_workflow/` 运行时。
4. 打开 [reference/BWorkflow-diagram.html](reference/BWorkflow-diagram.html) —— 查看完整流程与循环路径。

> BWorkflow 的权威层永远是 `rules/` 目录。[reference/introduction.md](reference/introduction.md) 是给人看的叙述层；若有冲突，以 `rules/` 为准。