SuperAPI AI 工具集

doc-adr-audit

编程与开发

查看项目

更新于 10-16 04:33

技能介绍

用途:对已有 ADR 执行统一审计,把结构检查与内容质量评审合并为一次运行,产出单一合并报告供 ../doc-adr-fixer/SKILL.md 消费。框架本身不含运行时代码,因此本技能充当校验器,由 Claude 依据规范直接对 ADR 逐项检查。层级为第 5 层(ADR 质量门),上游是 ADR 文件,下游输出 .aidoc/audit/05_ADR-audit.md 并可选触发修复循环。适用于 ADR 已存在、生成 SPEC 之前,或 autopilot 的审计↔修复循环中;不用于创建 ADR。每次必须从零审计,不复用旧分数或缓存结果。

输入与流程:输入 ADR 路径(docs/05_ADR/ADR-NN_*/...)与可选分数阈值(默认 90)。顺序为:结构检查 → 记录发现 → 内容评审 → 合并归一化 → 写入 .aidoc/audit/05_ADR-audit.md → 若存在可自动修复项则交给 doc-adr-fixer。评审模式从 .aidoc/profile.yaml 的 review_mode 解析,未设置则按优先级链回退框架默认。

两种模式:team 模式下内容评审由按视角的 Task 子代理在黑板目录 .aidoc/review/05_ADR/<ADR-id>/ 上扇出执行,六视角权重合计 100(architect 35、tech_lead 25、chaos_engineer 8、security_engineer 12、operator 10、auditor 10),随后由 synthesizer 汇总为 verdict.json 与 report.md;若 coverage.quorum_met 为 false,审计标为低置信度交人工评审,绝不静默通过。single_pass 模式在同一上下文中顺序执行各视角,无子代理与黑板。两种模式下结构门为确定性执行,不委托。视角须忽略作者自评字段(如 *_ready_score、audit_score 等)。

结构检查:先枚举 ADR-TEMPLATE.yaml 中所有必需章节,缺失即为阻断项。Tier 1 阻断项包括元素 ID 格式(ADR.NN.SS.xxxx 四十六进制哈希)、单一决策、结构完整非空、累积标签 @brd @prd @ears @bdd、质量门分数达阈值。Tier 2 为警告项,如前置元数据、被拒备选的原因、权衡后果、链接可解析、下游编号引用、架构流程图等;写作风格检查在达到条件时升级为阻断。

Saga 交互与限制:由 doc-adr-autopilot 触发时会读写 .aidoc/review/05_ADR/<ADR-id>/saga.json,并在合成器调度前做断链检查,SOFT_DEADLINE 为 1500 秒,超时以 PARTIAL_TIMEOUT 干净退出;单独调用或 single_pass 模式不生成 saga.json。迭代上限 MAX_ITERATIONS=3 由 saga 驱动强制,本技能把 PARTIAL_TIMEOUT 视为失败但不重试。其余细节(具体仓库配置、运行环境要求、收费方式、价格、平台支持与效果数据)资料未提供。