DevBooks

面向 Claude Code / Codex CLI 的代理式 AI 开发工作流

把大型变更变成可控、可追溯、可验证的闭环：Skills + 质量闸门 + 角色隔离。

为什么选择 DevBooks？

AI 编码助手很强大，但往往不可预测：

| 痛点 | 后果 | |------|------| | AI 自评"已完成" | 实际测试不过、边界条件遗漏 | | 同一对话写测试又写代码 | 测试沦为"通过性测试"，而非验证规格 | | 无验证闸门 | 伪完成悄悄进入生产环境 | | 只支持 0→1 项目 | 存量代码库无从下手 | | 命令太少 | 复杂变更不只是"spec/apply/archive" |

DevBooks 的解决方案：

• 基于证据的完成：完成由测试/构建/证据定义，而非 AI 自我评估
• 强制角色隔离：Test Owner 与 Coder 必须在独立对话中工作
• 多重质量闸门：Green 证据检查、任务完成率、角色边界检查
• 18 个 Skills：覆盖提案、设计、评审、熵度量等完整工作流

工作原理

核心约束：Test Owner 与 Coder 必须在独立对话中工作。这是硬性约束，不是建议。Coder 不能修改 tests/**，完成由测试/构建验证，而非 AI 自评。

快速开始

支持的 AI 工具

| 工具 | 支持级别 | 配置文件 | |------|----------|----------| | Claude Code | 完整 Skills | CLAUDE.md | | Codex CLI | 完整 Skills | AGENTS.md | | Qoder | 完整 Skills | AGENTS.md | | OpenCode（oh-my-opencode） | 完整 Skills | AGENTS.md | | Cursor | Rules 系统 | .cursor/rules/ | | Windsurf | Rules 系统 | .windsurf/rules/ | | Gemini CLI | Rules 系统 | GEMINI.md | | Continue | Rules 系统 | .continue/rules/ | | GitHub Copilot | 自定义指令 | .github/copilot-instructions.md |

提示：使用自然语言调用 Skills，例如："运行 devbooks-proposal-author skill..."

安装与初始化

npm 安装（推荐）：

# 全局安装
npm install -g dev-playbooks-cn

# 在项目中初始化
dev-playbooks-cn init

一次性使用：

npx dev-playbooks-cn@latest init

从源码安装（贡献者）：

./scripts/install-skills.sh

安装落点

初始化时可选择 Skills 安装位置：

| 安装范围 | 说明 | 路径示例 | |----------|------|----------| | 项目级（默认） | 仅当前项目可用 | .claude/skills/devbooks-* | | 全局 | 所有项目共享 | ~/.claude/skills/devbooks-* |

# 交互式选择
dev-playbooks-cn init

# 非交互式指定
dev-playbooks-cn init --tools claude --scope project  # 项目级
dev-playbooks-cn init --tools claude --scope global   # 全局

快速集成

DevBooks 使用两个目录根：

| 目录 | 用途 | 默认值 | |------|------|--------| | <truth-root> | 当前规格（只读真理） | dev-playbooks/specs/ | | <change-root> | 变更包（工作区） | dev-playbooks/changes/ |

详见 docs/DevBooks配置指南.md。

日常变更工作流

使用 Router（推荐）

告诉 AI 你的需求，让 Router 分析并输出执行计划：

请运行 devbooks-router skill，分析需求：<你的需求>

Skills 直达

熟悉流程后，直接调用 Skill：

1. Proposal 阶段（禁止编码）

请运行 devbooks-proposal-author skill，创建提案：添加 OAuth2 用户认证

产物：proposal.md（必需）、design.md、tasks.md

2. Apply 阶段（强制角色隔离）

必须开 2 个独立对话：

# 对话 A - Test Owner
请运行 devbooks-test-owner skill，变更 ID：add-oauth2

# 对话 B - Coder
请运行 devbooks-coder skill，变更 ID：add-oauth2

• Test Owner：写 verification.md + 测试，先跑 Red
• Coder：按 tasks.md 实现，让闸门 Green（禁止改测试）

3. Review 阶段

请运行 devbooks-code-review skill，变更 ID：add-oauth2

4. Archive 阶段

请运行 devbooks-archiver skill，变更 ID：add-oauth2

Skills 参考

Proposal 阶段

| Skill | 说明 | |-------|------| | devbooks-router | 智能路由到合适的 Skill | | devbooks-proposal-author | 创建变更提案 | | devbooks-impact-analysis | 跨模块影响分析 | | devbooks-proposal-challenger | 质疑和挑战提案 | | devbooks-proposal-judge | 裁决提案 | | devbooks-design-doc | 创建设计文档 | | devbooks-spec-contract | 定义规格与契约 | | devbooks-implementation-plan | 创建实现计划 |

Apply 阶段

| Skill | 说明 | |-------|------| | devbooks-test-owner | Test Owner 角色（必须独立对话） | | devbooks-coder | Coder 角色（必须独立对话） | | devbooks-design-backport | 回写发现到设计文档 |

Review 阶段

| Skill | 说明 | |-------|------| | devbooks-code-review | 代码评审（可读性/一致性） | | devbooks-test-reviewer | 测试质量与覆盖率评审 |

Archive 阶段

| Skill | 说明 | |-------|------| | devbooks-archiver | 规格维护与去重 |

独立技能

| Skill | 说明 | |-------|------| | devbooks-entropy-monitor | 系统熵度量 | | devbooks-brownfield-bootstrap | 存量项目初始化 | | devbooks-convergence-audit | 收敛性审计（反迷惑设计） |

编排层（支持子 Agent 的工具专用）

| Skill | 说明 | |-------|------| | devbooks-delivery-workflow | 完整闭环编排器，自动编排 Proposal→Design→Spec→Plan→Test→Code→Review→Archive 全流程 |

注意：devbooks-delivery-workflow 是编排层 Skill，专为支持子 Agent 的 AI 编程工具（如 Claude Code with Task tool）设计。它会调用子 Agent 执行各阶段 Skill，完成完整的变更闭环。

DevBooks 对比

vs. OpenSpec

OpenSpec 是轻量级规格驱动框架，用三个核心命令（proposal/apply/archive）对齐人与 AI。

OpenSpec 的局限：

• 缺乏角色隔离，AI 可能自我验证"已完成"
• 无质量闸门，伪完成难以拦截
• 只有 3 个命令，复杂变更覆盖不足

DevBooks 解决方案：

• 强制角色隔离：Test Owner 与 Coder 必须独立对话，杜绝自我验证
• 5+ 质量闸门：Green 证据检查、任务完成率、角色边界检查
• 18 个 Skills：覆盖提案→实现→归档完整闭环

vs. spec-kit

GitHub spec-kit 提供规格驱动开发工具包，有 constitution 文件和结构化规划。

spec-kit 的局限：

• 偏向 0→1 绿地项目，存量项目支持有限
• 无强制角色隔离，测试与实现可能混淆
• 依赖人工检查，缺乏运行时验证

DevBooks 解决方案：

• 存量优先：devbooks-brownfield-bootstrap 自动生成基线规格
• 强制角色隔离：测试编写与实现物理分离
• 运行时闸门：自动验证，不依赖人工检查

vs. Kiro.dev

Kiro 是 AWS 的代理式 IDE，用三阶段工作流（需求、设计、任务）。

Kiro 的局限：

• 规格与实现产物分开存储，追溯困难
• 无强制角色隔离
• 依赖特定 IDE 环境

DevBooks 解决方案：

• 变更包：proposal/design/spec/plan/verification/evidence 集中存储，完整追溯
• 强制角色隔离：Test Owner 与 Coder 硬边界
• 工具无关：支持 Claude Code、Codex CLI、Cursor 等多种工具

vs. 无规格

没有规格时，AI 从模糊提示生成代码，导致不可预测的输出、范围蔓延和"幻觉式完成"。

DevBooks 带来：

• 实现前商定规格，范围清晰可控
• 质量闸门验证真实完成
• 角色隔离防止自我验证
• 每个变更的完整证据链

核心原则

| 原则 | 说明 | |------|------| | 协议优先 | 真理/变更/归档写进项目，不只存在聊天记录里 | | 锚点优先 | 完成由测试、静态分析、构建和证据定义 | | 角色隔离 | Test Owner 与 Coder 必须在独立对话中工作 | | 真理源分离 | <truth-root> 是只读真理；<change-root> 是临时工作区 | | 结构闸门 | 优先关注复杂度/耦合/测试质量，而非代理指标 |

高级功能

DevBooks 提供质量闸门拦截"伪完成"：

| 闸门 | 触发模式 | 检查内容 | |------|----------|----------| | Green 证据检查 | archive, strict | evidence/green-final/ 存在且非空 | | 任务完成检查 | strict | tasks.md 中所有任务完成或 SKIP-APPROVED | | 测试失败拦截 | archive, strict | Green 证据中无失败模式 | | P0 跳过审批 | strict | P0 任务跳过必须有审批记录 | | 角色边界检查 | apply --role | Coder 不能改 tests/，Test Owner 不能改 src/ |

核心脚本（位于 ~/.claude/skills/devbooks-delivery-workflow/scripts/）：

• change-check.sh --mode proposal|apply|archive|strict
• handoff-check.sh - 角色交接验证
• audit-scope.sh - 全量审计扫描
• progress-dashboard.sh - 进度可视化

技术方案不确定时：

1. 创建原型：change-scaffold.sh <change-id> --prototype
2. Test Owner 用 --prototype：表征测试（无需 Red 基线）
3. Coder 用 --prototype：输出到 prototype/src/（隔离主 src）
4. 提升或丢弃：prototype-promote.sh <change-id>

原型模式防止实验代码污染主源码树。

脚本位于 ~/.claude/skills/devbooks-delivery-workflow/scripts/。

DevBooks 跟踪四维系统熵：

| 指标 | 测量内容 | |------|----------| | 结构熵 | 模块复杂度和耦合 | | 变更熵 | 变动和波动模式 | | 测试熵 | 测试覆盖率和质量衰减 | | 依赖熵 | 外部依赖健康度 |

用 devbooks-entropy-monitor 生成报告，识别重构机会。

脚本（位于 ~/.claude/skills/devbooks-entropy-monitor/scripts/）：entropy-measure.sh、entropy-report.sh

当 <truth-root> 为空时，使用 devbooks-brownfield-bootstrap 生成：

• 项目画像和术语表
• 从现有代码生成基线规格
• 最小验证锚点
• 模块依赖图
• 技术债热点

DevBooks Skills 支持 MCP（Model Context Protocol）优雅降级：在没有 MCP/CKB 的环境也能跑完整工作流；一旦检测到 CKB（Code Knowledge Base）可用，就自动启用图基能力，把"范围/引用/调用链"分析做得更准。

它有什么用？

• 影响分析更精确：从"文件级猜测"升级到"符号级引用 + 调用图"，降低漏改风险
• 审查更有重点：自动拉取热点文件，优先关注高风险区域（技术债/高变动）
• 大仓库更省心：减少手动 Grep 的噪音与反复确认

MCP 状态与行为

| MCP 状态 | 行为 | |----------|------| | CKB 可用 | 增强模式：符号级影响分析/引用查找/调用图/热点 | | CKB 不可用 | 基础模式：Grep + Glob 文本搜索（功能完整，精度降低） |

自动检测

• 需要 MCP 的 Skills 会先探测可用性（2s 超时）
• 超时/失败 → 静默降级到基础模式，不阻塞执行
• 无需手动选择"基础/增强"模式

如需启用增强能力：按 docs/推荐MCP.md 配置 CKB，并手动生成 index.scip。

严格提案审查使用独立对话的 Challenger 和 Judge：

三个角色（必须独立对话）：

1. Author：创建并捍卫提案（使用 devbooks-proposal-author）
2. Challenger：质疑假设、发现缺口、识别风险（使用 devbooks-proposal-challenger）
3. Judge：做最终决定、记录理由（使用 devbooks-proposal-judge）

重要：三个角色必须在独立对话中工作，以避免角色混淆和自我验证。

决定结果：Approved、Revise、Rejected

从其他框架迁移

DevBooks 提供迁移脚本帮助从其他规格驱动开发工具迁移。

从 OpenSpec 迁移

如果你当前使用 OpenSpec，有 openspec/ 目录：

# 使用 CLI（推荐）
dev-playbooks-cn migrate --from openspec

# 先预览变更
dev-playbooks-cn migrate --from openspec --dry-run

# 迁移后保留原目录
dev-playbooks-cn migrate --from openspec --keep-old

迁移内容：

• openspec/specs/ → dev-playbooks/specs/
• openspec/changes/ → dev-playbooks/changes/
• openspec/project.md → dev-playbooks/project.md
• 所有路径引用自动更新

从 GitHub spec-kit 迁移

如果你使用 GitHub spec-kit，有 specs/ 和 memory/ 目录：

# 使用 CLI（推荐）
dev-playbooks-cn migrate --from speckit

# 先预览变更
dev-playbooks-cn migrate --from speckit --dry-run

# 迁移后保留原目录
dev-playbooks-cn migrate --from speckit --keep-old

映射规则：

| Spec-Kit | DevBooks | |----------|----------| | memory/constitution.md | dev-playbooks/specs/_meta/constitution.md | | specs/[feature]/spec.md | changes/[feature]/design.md | | specs/[feature]/plan.md | changes/[feature]/proposal.md | | specs/[feature]/tasks.md | changes/[feature]/tasks.md | | specs/[feature]/quickstart.md | changes/[feature]/verification.md | | specs/[feature]/contracts/ | changes/[feature]/specs/ |

迁移功能

两个迁移脚本都支持：

• 幂等执行：可安全多次运行
• 断点续传：中断后可从断点恢复
• 试运行模式：预览变更再执行
• 自动备份：原文件备份到 .devbooks/backup/
• 引用更新：文档中的路径引用自动更新

迁移后步骤

迁移后：

1. 运行 dev-playbooks-cn init 设置 DevBooks Skills
2. 检查 dev-playbooks/ 中的迁移文件
3. 更新 verification.md 文件的 AC 映射
4. 如需基线规格，运行 devbooks-brownfield-bootstrap

目录结构

dev-playbooks/
├── README.md              # 本文档
├── constitution.md        # 项目宪法（GIP 原则）
├── project.md             # 项目上下文（技术栈/约定）
├── specs/                 # 当前规格（只读真理）
│   ├── _meta/             # 元数据（术语表、项目画像）
│   └── architecture/      # 架构规格（fitness-rules）
├── changes/               # 变更包（工作区）
├── scripts/               # 辅助脚本
└── docs/                  # 文档
    ├── workflow-diagram.svg   # 工作流程图
    ├── 推荐MCP.md             # MCP 配置建议
    └── DevBooks配置指南.md    # 配置指南

文档

• 工作流程图
• MCP 配置建议
• 配置指南

License

MIT