跳到主要内容

第二十六节 — 审计点

这一节回答:每个里程碑的 review gate 具体审计什么?审计动作的标准动作是什么?谁来执行?

三检审计 + 四类断言

ADR-001 定义"每个里程碑过三检 review gate"。本章把"三检"展开为可执行的具体审计动作。

三检

检查项含义
战略保真度审计工程产物未引入战略禁入概念 / 未违反战略边界
契约回归审计与上一里程碑的接口契约向后兼容(major 升级除外)
认知质量审计当前里程碑范围内的认知输出符合质量目标

四类断言

每检由若干可执行断言组成,分四类:

类别检查方式自动化程度
机械断言脚本 / grep / 静态分析完全自动(CI 跑)
结构断言schema 校验 / 类型检查 / 依赖图完全自动
样本断言在评估数据集上跑 + 指标阈值半自动(运行自动,判断需人复核)
语义断言人工审查(PR / spec / 文档一致性)人工

战略保真度审计动作

机械断言

断言实现通过条件
禁词不命中verify-kb.mjs 含 banned-concept grep全部 0 命中(或仅在拒绝清单列举段)
战略原句存在grep 关键句(如"FinBayes 不直接下单"在文档中存在)至少一处命中
凭证字段不在数据 schemagrep private_key / mnemonic / api_secret 等字段名0 命中(白名单:边界 hook 测试 fixture)
执行类工具 category 不在 Capability Registry静态分析工具注册代码0 个 category=execution 的工具
TLS 强制grep http://(非 localhost)在 Provider 配置0 命中

结构断言

断言实现
综合层输出 schema 含反方 / 风险 / 失效条件三字段Pydantic schema 校验
工具 schema 含 category 字段 + 严格枚举OpenAPI / JSON Schema 校验
审计 trail 字段无凭证类列DB schema 静态检查

语义断言

断言谁做
同义改写未绕过禁词(如"行动判断"改写为"行动倾向")Claude Code Review
输出契约语义未偷偷弱化Claude Code Review + 工作流维护者复核
战略不变量未被"工程方便"理由削弱工作流维护者裁决

战略保真度阻断条件

战略保真度审计任何一条机械断言失败 = 阻断 merge。语义断言失败 = 进 review 反馈循环。


契约回归审计动作

机械断言

断言实现
既有接口的字段未被删除OpenAPI diff
既有字段类型未变更Pydantic schema diff
既有错误码语义未变错误码字典 diff
contract_version 正确递增Git diff + 版本规则校验

结构断言

断言实现
数据库 schema 仅增加字段或新表SQL DDL diff
State Store schema_version 与代码期望版本匹配启动期检查
删除字段前的 deprecated 标记存在至少一个 minor 版本Git 历史扫描

样本断言

断言实现
上一里程碑的样例请求在当前里程碑仍能正常处理跑上一里程碑的端到端测试 fixture
既有审计 trail 在新版本下可读加载历史审计文件 + 校验

契约回归阻断条件

契约回归审计任何机械 / 结构断言失败 = 阻断 merge。样本断言失败 = 看是否有合理升级路径(如已 deprecated 一版本)。


认知质量审计动作

详细方法见 CHAP-21。这里聚焦里程碑级的审计动作

样本断言

断言实现
当前里程碑范围的冒烟集全过评估运行器跑 + 阈值校验
回归集无新增失败评估运行器跑 + 对比上一里程碑结果
抗扰集(边界 case)无新增失败评估运行器跑
Self-consistency 高风险任务的分歧度未上升指标对比

语义断言

断言谁做
输出反方覆盖未削弱(如"反方质量"维度未下滑)工作流维护者 + 跨 Agent 模拟视角
表达密度匹配画像(不过密 / 不过疏)工作流维护者抽样
信息缺口处理诚实(没数据时不硬编)工作流维护者抽样

认知质量阻断条件

  • 回归集失败 = 阻断 merge(硬阈值)
  • 抗扰集失败 = 阻断 merge(边界相关,等同硬阈值)
  • 冒烟集软阈值下降 >5% = warn + 必须 PR 描述里说明原因
  • 语义断言不通过 = 进 review 反馈循环

各里程碑的审计点

M0 走通骨架审计

审计项通过条件
战略保真度全部机械断言 + 全部结构断言通过
契约回归建立基线(M0 是基线 → 无前置对比)
认知质量5 条样例跑通 + 包含反方 + 失效条件 + 题眼命中
边界5 类凭证样式输入 100% 拒收
审计 trailtask_id 贯穿 + Provider 调用链完整

M1 状态化审计

审计项通过条件
战略保真度同 M0 + 用户主权 5 维度全部可用
契约回归M0 baseline 100% 兼容
认知质量候选 → 已确认两步路径可被评估观测
状态机5 个状态机的所有转移都有测试

M2-M7 审计

每个里程碑的具体审计点在 OpenSpec 提案中由 Claude Code 起草,遵循"机械 + 结构 + 样本 + 语义"四类断言模板。


审计执行模型

这张图表达什么:每个 PR 走机械 + 结构断言(CI 自动)+ 样本断言(评估运行器)→ 人工 review 语义断言 → merge。所有审计结论进入审计记录。

这张图特意不表达什么:每条审计的具体工具实现(在工程实施仓 CI 配置);审计争议的仲裁流程(在 governance/change-protocol.md)。


审计的可观测性

审计自身需要可观测:

维度实现
每次审计的结论进 release notes + 审计 trail
责任人PR review 字段 + 审计记录
时间自动记录
阻断历史哪些断言曾经阻断过 + 解决路径
审计 SLA每个里程碑的 review 应在 X 工作日内完成(不是软指标,是流程承诺)

审计 vs 测试 vs 评估的关系

维度测试(CHAP-20)评估(CHAP-21)审计(本章)
触发每次 PR + nightly周期 + release每个里程碑
对象业务正确性 / 协作 / 边界认知质量 / 趋势里程碑产物整体
通过assert + 覆盖率指标 + 阈值三检通过
负责工程实施 Agent评估运行器 + 工作流维护者Claude Code Review + 工作流维护者

测试与评估是审计的输入证据。审计是更高层的"这一刻这一切是否能合并到主分支"的综合判定。


审计的边界

审计不替代

  • 战略层的决策(战略变更走 governance/change-protocol.md)
  • 工程实施的细节决定(PR 描述中说明)
  • 用户的真实使用反馈(在线评估信号)

审计就只做三件事:

  1. 这次里程碑产物是否符合战略边界(保真度)
  2. 这次里程碑产物是否破坏既有用户(契约回归)
  3. 这次里程碑范围内认知质量是否未退化

与其他章节的关系

  • 三检 review gate 来源 → ADR-001
  • 工程协作模式 → ADR-003
  • 战略不变量与禁入概念 → CHAP-02 / CHAP-17
  • 契约版本化策略 → CHAP-19
  • 评估测试方法 → CHAP-21
  • 里程碑切片 → CHAP-25 与里程碑/任务的对应
  • 代码层审计点的物理位置 → CHAP-27 代码仓位置映射