AI-driven spec-based development workflow
npm install dev-playbooks-cn
让 AI 写代码从"说完成就完成"变成"有证据才算完成"。
DevBooks 是一套面向 AI 的工程协议，通过上游真理源（SSOT）、可执行闸门、证据闭环，把 AI 编程从"对话式猜测"升级为"可审计的工程交付"。
---
软件工程的本质是在不可靠的组件之上构建可靠的系统。传统工程用 RAID 对抗不可靠的硬盘，用 TCP 重传对抗不可靠的网络，用 Code Review 对抗不可靠的人类程序员。AI 工程同样需要用闸门与证据闭环约束不可靠的 LLM 输出。
DevBooks 不是提示词优化，而是工程约束。
---
DevBooks 的核心是上游真理源（Single Source of Truth）——所有关键知识落盘并版本化，跨对话、跨变更稳定。
``
你的需求文档（如果有）
↓ 提取约束，建立索引
specs/（术语、边界、决策、场景）← 跨变更稳定的"项目记忆"
↓ 派生变更包
changes/
↓ 归档回写
specs/（更新真理）
SSOT 解决的问题：
| 问题 | 根因 | SSOT 如何解决 |
|-----|------|--------------|
| 每次都要从头教 | 对话是临时的，知识没有持久化 | 术语、边界、约束写在文件里，不依赖对话记忆 |
| 改着改着就忘了之前说的 | 上下文窗口有限，早期信息被挤出去 | 真理工件持久化，强制注入关键约束 |
| 不知道改了什么 | 没有可审计的变更记录 | 每次变更有完整记录——提案、设计、任务、证据 |
---
DevBooks 通过完成合同（Completion Contract）和需求索引（Requirements Index）持续追踪交付状态。
`yaml`
obligations:
- id: O-001
describes: "用户可以通过邮箱登录"
severity: must
checks:
- id: C-001
type: test
covers: [O-001]
artifacts: ["evidence/gates/login-test.log"]
不是"大概做完了"，而是"这 5 条义务都有证据"。
`yaml`
set_id: ARCH-P3
source_ref: "truth://specs/architecture/design.md"
requirements:
- id: R-001
severity: must
statement: "所有 API 必须支持版本化"
- id: R-002
severity: should
statement: "响应时间 < 200ms"
当变更包宣称"已完成上游任务"时，系统可以裁判这个宣称——不是口头确认，而是机器校验。
---
大需求直接交给 AI 会怎样？改了 A 忘了 B，修了 B 又破坏了 C。
Knife 协议通过复杂度预算和拓扑排序，把 Epic 切成可独立验证的原子变更包队列。
`
Score = w₁·Files + w₂·Modules + w₃·RiskFlags + w₄·HotspotWeight
| 信号 | 权重 | 说明 |
|-----|------|-----|
| files_touched | 1.0 | 每个文件计 1 分 |
| modules_touched | 5.0 | 跨模块风险高 |
| risk_flags | 10.0 | 每个风险旗标计 10 分 |
| hotspot_weight | 2.0 | 高 churn 区域加权 |
超预算必须再切——禁止"硬做"。
1. MECE 覆盖：所有切片的验收点并集等于 Epic 的完整验收点集合，且不重叠
2. 可独立 Green：每个切片至少一个确定性验证锚点，不允许"中间态不可编译"
3. 拓扑可排序：依赖图必须无环，执行顺序必须为拓扑序
4. 预算熔断：超预算必须递归切分，或回流补信息
当 Knife Plan 包含多个 Slice 时，可以生成并行执行清单：
`bash`
knife-parallel-schedule.sh
输出内容：
- 最大并行度：可同时启动的最大 Agent 数量
- 分层执行清单：Layer 0（无依赖）→ Layer 1 → Layer N
- 关键路径：串行依赖深度
- 启动命令模板：每个 Slice 的 Agent 启动命令
#### Autoflow（Beta）：调度控制面 + tmux/worktree 脚本生成
为降低“开窗口/复制粘贴/续跑指令”的人工成本，可以使用 CLI 生成控制面与脚本（默认安全，不执行 AI）：
`bash生成调度清单 + Dashboard + Runbook（派生缓存，可丢弃可重建）
dev-playbooks-cn autoflow --epic
说明：
- Autoflow 只生成指引与脚本：不自动执行外部 AI CLI、不绕过权限、不自动合并。
- Test Owner 与 Coder 仍必须隔离实例/会话；并行时建议配合 worktree（脚本会一并生成）。
---
7 道闸门：全链路可裁判检查点
| 闸门 | 检查什么 | 失败后果 |
|-----|---------|---------|
| G0 | 输入就绪了吗？基线工件齐全吗？ | 回流到 Bootstrap |
| G1 | 该有的文件都有吗？结构正确吗？ | 阻断 |
| G2 | 任务都完成了吗？绿证据存在吗？ | 阻断 |
| G3 | 切片正确吗？锚点齐全吗？（大需求） | 回流到 Knife |
| G4 | 文档同步了吗？扩展包完整吗？ | 阻断 |
| G5 | 风险覆盖了吗？回滚策略有吗？（高风险） | 阻断 |
| G6 | 证据完整吗？合同满足吗？可以归档吗？ | 阻断 |
任何一道失败，流程阻断。不是警告，是阻断。
---
角色隔离：防止 AI 自己验证自己
| 角色 | 职责 | 硬约束 |
|-----|------|-------|
| Test Owner | 从设计推导验收测试 | 禁止看实现代码 |
| Coder | 按任务实现功能 | 禁止修改 tests/ |
| Reviewer | 审查可读性与一致性 | 不改测试不改设计 |
Test Owner 和 Coder 必须在不同上下文执行——不是"不同人"，而是"不同对话/不同实例"。两者之间只能通过落盘工件交接。
---
快速开始
bash
npm install -g dev-playbooks-cn
dev-playbooks-cn init
`然后在你的 AI 工具对话里输入（唯一入口）：
text
/devbooks:delivery
`> 说明：
映射到 Router Skill：devbooks-start。它会先执行“需求对齐 → SSOT 分阶段推进”，再路由 request_kind 并编排最小充分闭环。
>
> 可选：在终端查看入口指引（不执行 AI）：dev-playbooks-cn delivery
你的需求
↓
Start（需求对齐 → SSOT 分阶段推进 → 路由 request_kind → 生成 RUNBOOK）
↓
┌─────────────────────────────────┐
│ 小改动 → 直接执行 │
│ 大需求 → 先切片再执行 │
│ 不确定 → 先研究再决策 │
└─────────────────────────────────┘
↓
闸门检查（7 道关卡，任何一道失败都会阻断）
↓
证据归档（测试日志、构建输出、审批记录）
---
目录结构
project/
├── .devbooks/config.yaml # 配置入口
└── dev-playbooks/
├── constitution.md # 硬约束（不可绕过的规则）
├── specs/ # 真理源（SSOT）
│ ├── ssot/ # 项目级 SSOT 包（需求层）
│ │ ├── SSOT.md
│ │ ├── requirements.index.yaml
│ │ └── requirements.ledger.yaml # 派生缓存（可丢弃可重建）
│ ├── _meta/
│ │ ├── glossary.md # 统一语言
│ │ ├── boundaries.md # 模块边界
│ │ ├── capabilities.yaml # 能力注册表
│ │ └── epics/ # Knife 切片计划
│ └── ...
└── changes/ # 变更包
└── /
├── proposal.md # 为什么做、做什么
├── design.md # 怎么做、验收标准
├── tasks.md # 拆成可执行的步骤
├── completion.contract.yaml # 完成合同
├── verification.md # 怎么证明做对了
└── evidence/ # 测试日志、构建输出
---
- 存量项目接入：自动索引现有文档，提取可裁判约束，建立最小 SSOT 包
- 新项目启动：引导补齐术语、边界、场景、决策，建立基线
- 日常变更：最小充分闭环，可复现验证锚点 + 证据归档
- 大型重构：Knife 切片 + 迁移范式（Expand-Contract / Strangler Fig / Branch by Abstraction）
---
---
MIT