用途
sdd 是 bro 的规格驱动开发策略技能,用于在仓库中落实“先写规格、再写代码”的规则。它只承载策略,具体机制(钩子注入、门禁、命令)由 bro CLI 承担。当仓库在 bro.config.json 中启用 sdd 段,或需要解释 bro 为何提示缺少规格时使用。
主要能力
- 策略注入:sdd 连接器的 hook probes 会把策略注入 session-start 和 prompt-submit 上下文。
- 门禁控制:gate 模式下,stop gate 在会话自身认领的任务缺少规格时阻断一次。
- 规格判定:以下任一形式视为规格:
<sdd.dir>/<bead-id>.md(非空,默认specs/,使用配置目录);随功能分支一起评审。- 目录规格
<sdd.dir>/<bead-id>/,其非空spec.md(或README.md)为索引;嵌套.md和带索引子目录为其子项,嵌套即规格树(无索引目录内的.md是内容而非规格)。 - bead 描述中的
spec:链接(外部文档)。
- 优先级:同时存在
spec:链接与发现的规格文件时,声明的链接优先;check 报告 link,drift 审计链接文件。check 只统计声明本身,不解析目标。 - 覆盖范围:读取工作树,未提交的规格文件已计入;drift 新鲜度仍需规格在 ref 上的提交。
- 豁免:
issue_type: chore或molecule(ship-beads 是 convoy 脚手架,非设计工作),以及标记为trivial或debt的 bead。
使用方式
命令:
bro spec check [id…]:对 in_progress beads 做覆盖检查(--all加上 open),输出 spec / link / exempt / MISSING;任一 MISSING 退出码 1,可用于 CI。bro spec drift [id…]:对已写规格的 closed beads 做新鲜度检查(--all扫描所有已写规格 bead),基于规格与范围提交在 origin/HEAD 上的新旧(回退顺序:本地 main/master、远程跟踪 origin/main/master、HEAD;--ref覆盖),输出 STALE / fresh / no-scope / unverifiable;任一 STALE 退出码 1。bro spec new <id>:从 bead 标题脚手架生成<sdd.dir>/<id>.md,不覆盖;--parent <id>链接规格树。bro spec tree:显示规格层级——根、子项、已认领但无规格的 MISSING。bro spec init:引导 SDD:检测.specify//openspec/,写入connectors.specs与sdd.mode: remind;裸仓库则脚手架原生specs/根;--tool覆盖检测。
适用场景与限制
适合希望以规格驱动开发、将规格与代码同 PR 评审、并可在 CI 中自审计的仓库。仅当前会话自身的认领会被判定(.task 标记,与并行工作提示同范围),其他会话未写规格的 bead 不会成为你的阻断项。
策略建议:认领后执行 bro spec new <id>,填写 Problem/Design/Plan,再实现,规格随同一 PR 落地;无需设计体量的小改动应标记 trivial 而非写空规格文件;bro spec check 作为自审计接入 CI;bro spec drift 审计已发布规格,代码已超越的规格属于待重新安排的债务,unverifiable/no-scope 行只报告覆盖缺口、不会使运行失败。
配置示例:"sdd": { "mode": "gate", "dir": "specs" }。mode 取值:off(默认,缺少该段即退出)、remind(会话开始策略行 + 自身认领缺规格时的提交提示)、gate(在 remind 基础上,在任务方面下 stop gate 阻断一次;重复停止则放行,是门禁而非循环)。规格工具检测:native(默认,<sdd.dir>/ 存在或无其他)、speckit(.specify/,规格为 specs/<NNN>-<slug>/spec.md,经 spec: 链接)、openspec(openspec/,规格为 openspec/changes/<id>/proposal.md)、agent(仅显式,无文件,spec: 链接即证据);可通过 "connectors": { "specs": "openspec" } 覆盖检测。