doc-bdd-autopilot

doc-bdd-autopilot

目的

自动化的 BDD 生成流水线。根据上游 EARS（docs/03_EARS/）、用户提示词或实现计划（IPLAN-*），分析源内容，生成完整的 Given-When-Then 场景 BDD 套件，验证就绪状态，维护 BDD-00_index.md，并推动审计↔修复循环，直至达到合格的 ADR-Ready 分数——支持单个 BDD 或批量处理。

层级：4。上游：EARS（可追溯至 BRD/PRD）/ 提示词 / IPLAN 输入。 下游：经过验证的 BDD + 索引条目。

技能依赖

技能	作用
../doc-bdd/SKILL.md	BDD 结构、YAML 场景架构和编写规则（生成）
../doc-bdd-audit/SKILL.md	质量门禁（ADR-Ready 评分 + 发现项）
../doc-bdd-fixer/SKILL.md	根据审计报告应用修复
../doc-naming/SKILL.md	元素 ID 标准

输入约定

接受：目标 BDD ID/路径；上游 EARS ID/路径；自由文本提示词；或 IPLAN 路径。可选：分数阈值（默认 90）、最大修复迭代次数（默认 3）、批次列表。如果没有显式输入，则将请求视为提示词。

智能文档检测

针对每个目标，检查 BDD 是否已存在（嵌套文件夹 docs/04_BDD/BDD-NN_{slug}/）：

• 缺失 → 生成模式（根据 EARS / 提示词 / IPLAN）。
• 存在 → 审查并修复模式（先审计，低于阈值时再修复）。

根据继承的 PRD/BRD 链确定 deliverable_type（code/document/ux/risk/process）。生成前，验证上游 EARS 是否存在。

模型预检

仅供参考，尽力提供。显示为此层推荐的模型；无法切换会话模型。调用驱动程序前：

1. 如果 .claude/aidoc-flow.config.yaml 不存在，或没有 model.* 键，则完全跳过本节（不输出任何内容）。
2. 确定推荐模型：优先使用 model.per_layer.BDD（如果已设置），否则使用 model.default。
3. 根据 model.precheck（warn | silent | block）执行：
   • warn（默认）——打印一行，然后继续调用驱动程序： ℹ BDD recommends model '<rec>'. If you're not on it, run /model <rec> (or set model.precheck: silent to hide this).
   • silent ——不打印任何内容；继续执行。
   • block ——打印上面的一行，并附加 precheck=block: confirm you want to draft on the current model, or run /model <rec> first.，然后等待用户确认后再继续。

工作流

Saga 驱动的生成循环（review_mode: team）

步骤 1 — 调用驱动程序。仅此而已。 在调用此 SKILL 前，harness 会设置 PREV_OUTPUT、 ARTIFACT_ID、ARTIFACT_PATH 环境变量。 你的第一个编排操作必须是 Bash 工具（上述 Model 预检查会先运行），并且要运行以下命令：

python3 "${CLAUDE_PLUGIN_ROOT}/tools/saga_driver.py" \
  --layer 04_BDD \
  --allow-skip-permissions

--allow-skip-permissions 可让驱动程序分派的阶段无需权限提示即可写入 文件——无人值守自动运行必须使用此参数。 移除该标志，即可使用 Claude Code 的常规提示运行相同循环。

使用充足的超时时间（≥1800s）。不要预先分析输入。不要 读取上游内容。不要分类类型/范围。驱动程序及其 分派的子进程（用于起草的 /aidoc-flow:doc-bdd、 用于审核的 /aidoc-flow:doc-bdd-audit、用于修复的 /aidoc-flow:doc-bdd-fixer） 会处理所有这些工作。驱动程序会依据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md 提前强制执行状态机；此 SKILL 的任务是调用它并报告结果。

步骤 2 — 驱动程序返回后，报告结果。 读取 .aidoc/review/04_BDD/${ARTIFACT_ID}/saga.json。最终状态必须为 CLOSED（通过）、ESCALATED（终止失败）或 PARTIAL_TIMEOUT（软截止；可恢复）。打印状态、 verdict.json 中的最终评分（如果存在），以及一行摘要。

步骤 3 — 更新索引（仅在 CLOSED 时）。 在 docs/04_BDD/BDD-00_index.md 中添加一行，引用新的 BDD；更新上游制品的 下游条目。

这就是 team 模式下的完整工作流。如果你发现自己在此处做其他任何事——起草文案、分派 Task 子代理、 调用其他斜杠命令——请立即停止，意识到自己正在绕过驱动程序，并改为调用上述 Bash 命令。

线性流水线（review_mode: single_pass）

未更改的旧版行为——当配置文件如此指定、无法分派 Task 子代理，或处于写入时（on_author，此时成本是首要考虑因素）使用。以下 5 步会话内流程会生成 BDD，但不会生成 saga.json；此时 harness 的 saga 日志 检查会导致此层失败，因此此模式仅适用于 手动试运行。

1. 输入分析 — 对输入进行分类（EARS / prompt / IPLAN），定位 上游 EARS 及其 BRD/PRD 追踪元素，并决定是生成还是审核并修复。
2. 类型与范围 — 确认引用的 EARS（及其 PRD/BRD 元素） 存在；将 EARS 陈述映射到场景类别；预留下一个 BDD-NN。
3. 生成 — 按照 ../doc-bdd/SKILL.md 生成 BDD：首先编写文档控制信息、 包含全部 5 个章节、一个 feature: 块，以及涵盖五个类别的 scenarios: YAML 列表——每个场景均为一个映射，包含 given/when/then 阶段 列表、元素级 ears: 列表、id BDD.NN.03.xxxx、type/priority、 内联 @threshold: 引用，以及 spec_trace。序列图通过 ../charts-flow/SKILL.md 生成。
4. 验证 — 从头运行 ../doc-bdd-audit/SKILL.md。
5. 审核 ↔ 修复循环 — 当评分低于阈值且迭代次数未达到上限时：运行 ../doc-bdd-fixer/SKILL.md，然后重新审核。通过后，更新 docs/04_BDD/BDD-00_index.md；迭代次数耗尽后，标记为需人工 审核。

执行模式

• 单项 — 一个 BDD（生成或审核并修复）。
• 批量 — 多个 BDD，按每批 3 个分块处理，以限制上下文； 按上游 EARS 顺序生成。
• 试运行 — 报告计划采取的操作（场景、类别、ID），但不写入 文件。

质量门槛

• 只有审核通过（ADR-Ready ≥ 阈值，Tier-1 错误为 0）或达到迭代上限（此时：标记需人工审核）后，生成才算完成。
• 仅在 BDD 通过后才更新 BDD 索引。
• 每个循环都要重新审核——不使用缓存评分。

错误处理

情况	操作
缺少引用的上游 EARS/PRD/BRD	停止；报告缺失的依赖项
达到最大迭代次数但未达到阈值	编写报告，标记为需人工审核，并继续处理批次
源输入含糊不清	回退到提示词模式；在 BDD 中记录假设
写入/权限错误	记录日志，跳过该项，并继续处理批次

适配

应用默认设置前，先读取项目适配配置文件 （.aidoc/profile.yaml），并在生成阶段和内部 审计/修复阶段应用该配置。遵循 section_toggles、active_layers、audit_threshold （只能提高阈值——只能采用更严格的设置）和 glossary。忽略任何未知或 超出适用范围的键；若没有配置文件，则使用框架默认值。 权威来源：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 创建：../doc-bdd/SKILL.md · 审计：../doc-bdd-audit/SKILL.md · 修复： ../doc-bdd-fixer/SKILL.md
• 权威来源：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-00_index.TEMPLATE.md