SuperAPI AI 工具集

sdd

编程与开发

查看项目

更新于 10-26 18:53

技能介绍

用途

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" } 覆盖检测。