
一条 spec 驱动的 Claude Code 流水线——把模糊需求一路带到经过 review、可交付的代码,每个阶段可追溯、可断点恢复、经对抗验证。
一条 spec 驱动的 Claude Code 流水线——把模糊需求一路带到经过 review、可交付的代码,每个阶段可追溯、可断点恢复、经对抗验证。语言无关,辅以技术栈约束套件(Go / Vue + bun / TDD / Git 纪律)。
产出跟随你的工作语言:文档、注释、commit message 都用你的工作语言(标识符 / API 名 / 错误码保持英文)。每个 skill 同时响应中英文触发词。
/plugin marketplace add 0xBB2B/bb-spec
/plugin install bb-spec-core@0xbb2b
/plugin install bb-spec-workflow@0xbb2b
主流水线 6 条命令:
| 命令 | 做什么 | 何时用 |
|---|---|---|
/spec |
把需求拆成一规则一文档 | 新需求开工 |
/plan |
spec → 函数级实施计划 | spec 就绪 |
/exec |
三 Agent 隔离跑 Test→Impl→Review | plan 就绪 |
/test-webview / /test-api |
Docker 整栈起 + 验收(可选) | 前端 / 后端 e2e |
/review |
多 finder 并行 + 对抗验证 | 提 PR 前 |
/git-push-pr |
pre-review 自查 + 推 + 开 PR | 准备发版 |
三条支线随时可介入:/init-spec(存量项目反向 spec 化)、/revise(任何偏差按根因回到正确阶段)、/doc-update(全仓 spec/文档/代码一致性体检)。
可选上游:/prd(PM / 需求方头脑风暴 PRD,由 bb-spec-product 单独提供)。
spec → ship (可选) /prd ──► PRD 文档
│
/init-spec ──► /spec ──► /plan ──► /exec ──► /test-* ──► /review ──► /git-push-pr
(存量项目) 做什么 怎么做 Red→Green→Review e2e 并发+对抗 pre-review+开 PR
│
┌──────────────────────────────────────────────────────────────────────────────┘
│
▼ /revise(随时介入,按根因路由)
spec 缺陷 → /spec · 实现偏离 → /exec · review 问题 → 定向修复
/doc-update(定期 / 按需)— 扫全仓漂移 → 默认改 spec/文档,代码明显不合理才停下问 → 挂 /revise
为什么这条流水线靠得住——每次交接物都是磁盘上的文档、不是会话里的临时记忆,这是它能断点续、能换 AI 接手、能逐级追溯的根本。
/init-spec — 反向 spec 化存量项目。
/spec 一致/spec — 通过对话做需求拆解,回答**「做什么」**。
INDEX.md 统领,读者先扫索引再按需加载/plan — spec → 自包含、函数级实施计划,回答**「怎么做」**。
/exec — 三 Agent 隔离执行,核心反作弊设计。
PROGRESS.md,token 耗尽也能无损续接/test-webview — 前端 / 网页项目的交互验收。
down -v 清理),浏览器 MCP 驱动真实浏览器/revise/test-api — 后端接口 e2e,语言无关。
compose.e2e.yaml 拉起整栈,md 用例机械渲染为单文件 Bun TS runner,bun run 一次跑完/test/advance-time、/test/backdate、/test/trigger-job 协议测/test/* 路由 + ENV TESTAPI=1;生产 image 物理排除 /test/* 源码;/test/healthz 探测失败即中止、禁降级/review — Workflow 编排、对抗验证的本地 PR review。
/revise — 随时介入的异常处理。
/spec)、实现偏离(→ /exec)、需求变更/git-push-pr — 用户触发的推送 + PR 流程(单 / 多仓库)。
INDEX.md 时先跑分支规范自查(pre-review):subagent 比对 spec vs 分支 diff,违规循环修复/doc-update — 全仓 spec / 文档 / 代码一致性体检。
/revise 走 TDD/init-spec(零→有)、/revise(单点)、/review 的 review-doc-sync(PR diff)划清边界附带产物
test-engineer / impl-engineer / spec-reviewer / webview-test-runner / review-code-quality / review-security / review-simplicity / review-doc-sync / review-codex / pre-reviewer / rule-extractor向流水线灌入规则——只装你需要的层。
prd — PM / 需求方与 AI 头脑风暴:质疑前置(允许否决)→ 发散 → 收敛,产出自包含 PRD——目标 / 非目标、带优先级的用户故事(每条 P0 挂具体用例与验收标准)、留给工程师的开放问题;不依赖 git 仓库与代码上下文,/spec 直接消费PM 不用装 Claude Code:每次发版自动打包
bb-spec-prd-skill.zip,下载后在 claude.ai 网页版 / 桌面版的 Settings → Customize → Skills 上传即可单独使用(需付费计划并启用代码执行),产出的 PRD 以可下载文件交付给工程师。
tdd-workflow — Red-Green-Refactor 纪律,覆盖增 / 改 / 删三场景标准流程version-policy — 官方库 / 标准库优先,新增第三方库须经用户明确同意(plan 批准的依赖清单视为已同意);钉版本前先查依赖官方最新版,禁凭训练记忆git-workflow — 分支决策、阶段性 commit、六段式 PR 描述、合并后清理golang-constraints — Go 全生命周期:三层架构、禁过度抽象、测试服从生产设计golang-testing — Go 测试组织:table-driven、subtests、benchmark、fuzzapi-design — REST 设计:资源命名、状态码、分页、A-BBB-CCCC 结构化错误码database-constraints — 应用层 UUIDv7 主键、软删除 + 联合 UNIQUE、DB 管理时间戳、全链路 UTCauth-constraints — 认证(authN):双 token(JWT + 不透明 refresh)轮换 + 重放检测、滑动续期、argon2idauthz-constraints — 授权(authZ):默认拒绝、判定集中、粗粒度角色 + 细粒度资源 ownership 两级校验防 IDORobservability-constraints — 日志 / 链路 / 指标基于 OTel:一处装配、JSON 日志带稳定 trace_id、label 基数有限service-constraints — 运行时治理:env 注入密钥 fail-fast、优雅生命周期、写幂等、超时 + 安全重试vue-constraints — Vue 3 + TypeScript + Vite + Tailwind + bun 技术栈强约束frontend-constraints — 工程约定:统一请求 client、错误码→UI 映射集中、路由守卫仅 UX、类型来自契约BB-Spec 拆成五个可独立安装的子 plugin——只装你需要的约束层。
先添加一次 marketplace(在 Claude Code 里执行):
/plugin marketplace add 0xBB2B/bb-spec
再按需安装对应层:
| 子 plugin | 装了得到什么 | 安装命令 |
|---|---|---|
| bb-spec-core (推荐基座) | TDD / 版本策略 / Git 纪律 + 3 个被动 hook | /plugin install bb-spec-core@0xbb2b |
| bb-spec-workflow (核心功能) | spec → plan → exec → test-webview / test-api → review → revise → git-push-pr、init 反向 spec、doc-update 全仓一致性维护 + 11 个 subagent | /plugin install bb-spec-workflow@0xbb2b |
| bb-spec-product | /prd 需求头脑风暴 → 含具体用例的 PRD 文档(PM / 需求方使用) | /plugin install bb-spec-product@0xbb2b |
| bb-spec-backend | Go / REST API / 数据库 / 认证 / 授权 / 可观测性 / 服务治理约束 | /plugin install bb-spec-backend@0xbb2b |
| bb-spec-frontend | Vue 3 + TS + Vite + Tailwind + bun 技术栈与工程约定(含 bun hook) | /plugin install bb-spec-frontend@0xbb2b |
按需取用——例如只要纪律与工作流、不要技术栈意见:装 bb-spec-core + bb-spec-workflow;PM / 需求方的机器上只装 bb-spec-product;想要全套:五个全装。
或手动添加到 ~/.claude/settings.json(只 enable 你想要的):
{
"extraKnownMarketplaces": {
"0xbb2b": {
"source": { "source": "github", "repo": "0xBB2B/bb-spec" }
}
},
"enabledPlugins": {
"bb-spec-core@0xbb2b": true,
"bb-spec-workflow@0xbb2b": true,
"bb-spec-product@0xbb2b": false,
"bb-spec-backend@0xbb2b": false,
"bb-spec-frontend@0xbb2b": false
}
}
/plugin update # 检查并更新所有已装 plugin
/plugin update bb-spec-core # 仅更新某个子 plugin
五个子 plugin 共用同一条同步版本线。
每个 hook 随「负责该关注点的子 plugin」一起发布——装了对应 plugin 才有。
| Hook | 所属子 plugin | 触发时机 | 作用 |
|---|---|---|---|
block-non-bun-pm |
bb-spec-frontend | PreToolUse(Bash) | 拦截 npm / yarn / pnpm 的包管理动作,强制 bun;既有项目已存在匹配 lockfile(如 package-lock.json)时放行 |
git-workflow-guard |
bb-spec-core | PreToolUse(Bash) | 拦截 main / master 分支的 git commit;其余 git 流程动作(开分支 / push / worktree / merge / PR)放行并注入 git-workflow 纪律与实时 git 状态 |
dep-version-check |
bb-spec-core | PostToolUse(Write|Edit) | 编辑依赖文件后注入「先查官方最新版」自检提示 |
stop-self-check |
bb-spec-core | Stop | 任务结束前强制四项自检:临时文件 / 改动范围 / 孤立残留 / 历史包袱 |
bash tests/validate.sh
校验多 plugin 结构:marketplace.json 有效性与 plugin 条目一致性(每个 source 都指向真实存在、且 name 匹配的 plugin 目录)、各子 plugin 的 plugin.json 字段、agent frontmatter 完整性(必填字段、name 一致性、agent-type 合法值、安全基线段落)、skill SKILL.md 格式、hooks.json 有效性及脚本存在性、个人路径泄露检测。
CI 在 PR 和 push 到 main 时自动运行(.github/workflows/ci.yml)。
仓库根目录的CLAUDE.template.md是配套的「铁律索引」参考。不会自动安装——按需复制到你的 ~/.claude/CLAUDE.md 或项目根 CLAUDE.md,按需裁剪。
/prd、/spec 和 /plan 默认输出至 .bb-spec/docs/ 下(.bb-spec/docs/prd/、…/spec/、…/plan/);运行时瞬态产物(如 webview 截图)落在与之平级的 .bb-spec/.cache/(自动 gitignore)。在项目根创建 .bb-spec.yaml 可覆盖 bb-spec 根目录:
base_dir: my/bb # → my/bb/docs/{prd,spec,plan,test}/ 与 my/bb/.cache/;填 ./ 则直接落项目根
| 场景 | 开关 |
|---|---|
| 临时允许 npm / yarn / pnpm | 临时禁用 bb-spec-frontend |
| 临时允许 main commit | 临时禁用 bb-spec-core |
| 跳过 Stop 自检 | 当前无开关——这是核心铁律,不建议跳过 |
MIT