doc-adr-autopilot

doc-adr-autopilot

目的

自动化的 ADR 生成流水线。从上游产物 （BRD §8 / PRD §14 / EARS / BDD）、用户提示词或实施计划 （IPLAN-*）出发，分析来源、界定决策范围、生成完整的上下文-决策-后果记录、验证准备情况、维护 ADR-00_index.md，并推动审计↔修复循环，直到达到合格分数——支持单个 ADR 或批量处理。

层级：5。上游：BRD → PRD → EARS → BDD（或提示词/IPLAN）。 下游：经过验证的 ADR + 索引条目。

技能依赖

技能	作用
../doc-adr/SKILL.md	ADR 结构和编写规则（生成）
../doc-adr-audit/SKILL.md	质量关卡（评分 + 发现项）
../doc-adr-fixer/SKILL.md	根据审计报告应用修复
../doc-naming/SKILL.md	元素 ID 标准
../adr-roadmap/SKILL.md	规划项目所需的 ADR 集合

输入约定

接受：目标 ADR ID/路径；上游 ID（BRD-NN/PRD-NN/EARS-NN/ BDD-NN）或主题元素 ID；自由文本提示词；或 IPLAN 路径。可选项： 分数阈值（默认值为 90）、最大修复迭代次数（默认值为 3）、批处理列表。如果没有 明确输入，则将请求视为提示词。

智能文档检测

对于每个目标，检查 ADR 是否已存在（嵌套文件夹 docs/05_ADR/ADR-NN_{slug}/）：

• 不存在 → 生成模式（根据上游内容综合生成决策）。
• 已存在 → 审查并修复模式（先审计，若低于阈值则修复）。

根据来源内容确定 deliverable_type（code/document/ux/risk/process， 继承自上游）以及起始主题（PRD §14，追溯至 BRD §8）。一份 ADR 记录一个决策。

模型预检查

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

1. 如果不存在 .claude/aidoc-flow.config.yaml，或其中没有 model.* 键，则完全跳过 本节（不输出任何内容）。
2. 确定推荐模型：若已设置 model.per_layer.ADR，则使用该值；否则使用 model.default。
3. 根据 model.precheck（warn | silent | block）执行操作：
   • warn（默认）——打印一行，然后继续调用驱动程序： ℹ ADR 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 precheck），并严格运行：

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

--allow-skip-permissions 可让驱动程序调度的各阶段在无需权限提示的情况下写入 文件——无人值守自动运行需要此参数。 移除此参数，即可使用 Claude Code 的常规提示运行相同的循环。

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

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

步骤 3 — 更新索引（仅在 CLOSED 时）。 在 docs/05_ADR/ADR-00_index.md 中添加一行，引用新 ADR；更新上游工件的 下游条目。

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

线性流水线（review_mode: single_pass）

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

1. 输入分析 — 对输入分类（上游 ID / 提示词 / IPLAN）， 找出源主题（PRD §14 → BRD §8），并决定是生成还是 审核并修复。
2. 决策范围 — 确认决策恰好有一项；预留下一个 ADR-NN；验证所引用的上游工件确实存在。
3. 生成 — 按 ../doc-adr/SKILL.md 生成 ADR：先写文档控制 信息（状态为 Proposed/Accepted），再写 §2–§10、术语表和附录；在 所选方案旁列出 2–3 个备选方案，并为每个方案注明不予选择的因素（成本和 契合度可选）；内部元素 ID 使用 ADR.NN.SS.xxxx；累积标签为 @brd @prd @ears @bdd；添加 @adr: ADR-NN 自身标签；通过 ../charts-flow/SKILL.md 绘制架构流程图。
4. 验证 — 从头开始运行 ../doc-adr-audit/SKILL.md。
5. 审核 ↔ 修复循环 — 当分数低于阈值且迭代次数低于上限时：运行 ../doc-adr-fixer/SKILL.md，然后重新审核。通过后，更新 docs/05_ADR/ADR-00_index.md；达到迭代上限时，标记为需要人工 审核。

执行模式

• 单个 — 一个 ADR（生成或审核并修复）。
• 批量 — 多个 ADR，按每批 3 个处理，以控制上下文大小； 先生成其他 ADR 所依赖的 ADR（@depends: ADR-NN）。
• 试运行 — 报告计划执行的操作（决策范围、章节、ID）， 不写入文件。

质量门槛

• 审核通过（SPEC-Ready ≥ 阈值、Tier-1 错误为 0）或达到迭代上限（此时标记为 需要人工审核）后，生成流程才算完成。
• 只有 ADR 通过后才更新 ADR 索引。
• 每轮都要重新审核，不得使用缓存分数。

错误处理

情况	操作
引用的上游工件缺失（BRD/PRD/EARS/BDD）	停止；报告缺失的依赖项
源内容描述了多个决策	拆分为多个 ADR（每个 ADR 一个决策）
达到最大迭代次数但未达到阈值	编写报告，标记为需要人工审查，并继续批次处理
源输入含糊不清	回退到提示词模式；在 ADR 中记录假设
写入/权限错误	记录错误，跳过该项，继续批次处理

适配

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

相关资源

• 创建：../doc-adr/SKILL.md · 审计：../doc-adr-audit/SKILL.md · 修复： ../doc-adr-fixer/SKILL.md
• 决策规划：../adr-roadmap/SKILL.md
• 权威来源：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md