ax-audit

AX Audit

适用于由 Agent 代表用户执行操作的应用的功能级审查。只问一个问题：它是否赢得了信任，又会在哪些地方失灵？

• **是：**针对 Agent 化界面（聊天、工具执行、配置、仪表板）的基于规则的审查，覆盖架构（rules-arch/）和信任（rules-ax/），最终给出发布就绪判定和 AX Relationship Summary。
• **不是：**传统前端 UX（使用 ui-design Audit mode）；面向开发者的 API、CLI 或类型易用性（使用 dx-audit）；公共网站或文档的 Agent 评分（使用 agent-ready）；Agent 指令文件（使用 agents-md）；产品尚未存在时对其功能的构想（使用 product-design）。

没有纳入范围的 Agent 化功能？请停止。针对表单和列表应用 AX 规则只会产生噪声。

目录

• 审查工作流
• 两层规则
• 等级与判定
• AX Relationship Summary
• 参考文件
• 注意事项
• 审查自检
• 相关技能

审查工作流

AX Audit progress:
- [ ] Step 1: Scope, via the diff against the PR base merge-base (PR mode) or explicit path (full sweep)
- [ ] Step 2: Detect agentic features per references/feature-playbooks.md
- [ ] Step 3: Run each detected feature's playbook in order, plus the diff-wide checks (PR mode only)
- [ ] Step 4: For each check, load the rule file and follow its detection recipe
- [ ] Step 5: Tier each finding per references/ship-readiness.md (rule override table wins)
- [ ] Step 6: Render verdict + findings + AX Relationship Summary per references/output-format.md
- [ ] Step 7: Run the audit self-check and report its evidence counts

PR 模式的审查范围是差异，以及它涉及的工具定义和编排器。未修改文件中的问题属于全面审查范围，不应纳入本次判定。操作手册中的注释是扫描副本；规则文件才是权威来源。每次 PR 模式审查都会运行 parity-orphan-ui-action，全面审查则绝不运行，因为没有差异供其读取。

规则 grep 会列出最常见的标识符，而非每个框架中的所有写法。如果 grep 未能在明显实现了相关功能（门控、流式传输、工具结果）的代码中找到匹配项，请先查看 references/framework-signals.md，确认该技术栈对该功能的命名，再记录为 unknown。

两层规则

层级	文件夹	规则数	操作手册指定时加载
1：架构	rules-arch/	11	rules-arch/<category>-<slug>.md
2：体验	rules-ax/	13	rules-ax/<category>-<slug>.md

类别：arch = parity、granularity、context、comm；ax = trust、control、context、comm。相同前缀可能对应不同规则：rules-arch/comm-no-approval-gate.md（执行路径上没有门控）不同于 rules-ax/control-no-approval-gate.md（存在门控，但所对应的风险级别不合理）。

首先运行第 1 层的 comm/parity 和第 2 层的 control/trust。这些规则涵盖阻断项。类别映射：rules-arch/_sections.md、rules-ax/_sections.md。

优先级	层级	类别	前缀	规则数
1	arch	Communication	comm-	3
2	arch	Parity	parity-	4
3	ax	Control	control-	4
4	ax	Trust	trust-	3
5	arch	Context	context-	2
6	ax	Communication	comm-	4
7	ax	Context	context-	2
8	arch	Granularity	granularity-	2

等级与判定

分为三个等级：release-blocker、fix-this-sprint、backlog。定义、通用界面等级上调规则和判定逻辑见 references/ship-readiness.md。

优先级：规则自身的界面覆盖表 > 通用上调规则 > defaultTier。最多应用一项调整。

判定：✅ READY（0 项阻断问题，≤3 项需本迭代修复）· ⚠️ READY WITH FOLLOW-UP（0 项阻断问题，≥4 项需本迭代修复）· ❌ NOT READY（≥1 项阻断问题）· 🚫 INCOMPLETE（自检未通过）。

阻断问题的优先级高于审查不完整。如果有 ≥1 项发布阻断问题且自检未通过，应报告 ❌ NOT READY，并在其下注明自检未通过：阻断问题是已确认的发现，仍需采取行动；而 🚫 会给人“什么也没发现”的印象，并让读者离开。只有在没有阻断问题且无法保证审查覆盖范围时，才使用 🚫。

AX Relationship Summary

检测到任何 Agent 化功能后，在发现结果之后呈现此摘要。发现结果面向工程师；此摘要面向设计师和 PM。包含四个字段：发展阶段（描述行为，而非标签）、信任信号（高/中/低，并说明一句理由）、关键缺口（一句可采取行动的陈述）、信任问题（只能提出一个、只有研究才能回答的问题）。

参考文件

文件	何时阅读
references/feature-playbooks.md	步骤 2-3：检测启发式规则、各功能的有序检查、全差异检查
references/framework-signals.md	步骤 4：当代码使用 AI SDK、MCP、Claude Agent SDK 或 AG-UI 时：各框架中门控、流、完成信号和结构化结果的位置，以及规则所依据的规范默认值
references/ship-readiness.md	步骤 5：层级定义、优先级、通用界面升级、判定逻辑
references/output-format.md	步骤 6：发现项 JSON 架构、摘要架构、终端呈现
references/ax-evolution-curve.md	编写 AX 关系摘要：阶段、操作深度、伪装与智能，以及那些没有对应规则、应纳入 keyGap 的论点
rules-arch/_sections.md	第 1 层类别、默认层级、共同触发组合
rules-ax/_sections.md	第 2 层类别、默认层级、共同触发组合

注意事项

• 先确定范围，再应用规则。 在一个包含 3 个文件的 PR 上对整个仓库运行全部 24 条规则，会让新的发布阻断项淹没在已有待处理问题的噪声中；最终判定也就不再能回答“这个 PR 能否合并”。
• 规则的覆盖表具有权威性。 comm-no-intent-handshake 默认级别为 fix-this-sprint，但其表中规定，工具执行时为 release-blocker。在明确覆盖的基础上再叠加通用的“工具执行时提升 1 级”，会把待处理问题重复升级为阻断项。
• 未连接到 AbortController.abort() 的停止按钮只是假象。 control-no-escape-hatch 仍然不通过：要验证是否调用了 abort()，而不是看按钮标签，否则审计会让一个欺骗用户的 UI 通过。
• 只关闭流的客户端 stop() 不会停止执行器。 useChat().stop() 会中止 fetch。除非路由把 req.signal 传给 streamText({ abortSignal })，且工具 execute 会读取它，否则用户按下 Stop 后，服务器仍会完成所有剩余的工具调用。要追踪信号是否传到循环，而不是只看按钮。
• 工具注解只是提示，不代表风险等级。 MCP 告知客户端，应将来自不受信任服务的 annotations 视为不受信任；如果某个门禁依据第三方服务的 readOnlyHint: true 自动批准，就等于把门禁交给了该服务。comm-no-approval-gate 会判定其不通过。规范默认值（destructiveHint: true、readOnlyHint: false）是默认拒绝的基线。
• 框架的审批标志是门禁的输入，而不是门禁本身。 AI SDK 的 toolApproval: "user-approval" 会发出 tool-approval-request 部分并等待。如果 UI 从不渲染 state === "approval-requested"，或在收到请求时就用 addToolApprovalResponse({ approved: true }) 作答，那么类型系统里有门禁，用户面前却没有。要检查渲染逻辑和响应调用，而不是选项。
• 检查缺失项需要记录文件列表。 “查找缺少 X 的组件”这类 grep 查询，在所有内容都符合要求和完全没有扫描任何内容时都会返回空结果。先列出候选文件（rg -l <feature-pattern>），逐一检查是否存在相反模式，并将文件列表作为证据引用。
• 仅凭 grep 证据，detection: observational 规则不能判定失败。 granularity-static-api-mapping、control-over-conversational、comm-no-generative-momentum，以及 trust-no-confidence-cues 中关于不确定性梯度的部分，都需要依据交互流程进行判断；仅有静态证据时，应返回 unknown 并说明原因，而不是 fail。
• 门禁会在三个不同环节失效。 路径中完全没有门禁（comm-no-approval-gate）、有门禁但与风险等级不匹配（control-no-approval-gate），或门禁设置正确但内容难以理解（control-thin-approval-payload）。报告第一个符合的情况，并按此顺序修复。
• 交互式门禁无法覆盖无人值守运行。 Cron、webhook 和队列入口会在无人提示的情况下，进入同一个执行器。comm-unrequested-action-no-consent 审计的就是这条路径；证据应指出入口，而不是执行器。
• ax-audit-ignore:<slug> 注释应计为 suppressed，而不是 pass。 在判定摘要块中报告其数量；没有理由的抑制本身就是 warn。
• 不要夸大等级。 comm-no-generative-momentum 和 granularity-static-api-mapping 的默认级别为 backlog。只要有一项发现被提升为 release-blocker，整个 PR 就会变为 ❌ NOT READY，因此不要提升那些仅影响外观的问题，否则团队会逐渐完全忽视判定结果。
• 不要重复报告 ui-design Audit 模式的发现。 “缺少加载状态”和“出错时表单会清空”都属于其职责范围；重复报告会让工程师学会忽视整份 AX 报告。
• 只会提出建议的 Personally Intelligent agent 已经停滞不前。 记忆阶段不等于信任等级。要在 evolutionStage.behavior 中写明最高行动阶位，否则摘要只是在美化一个礼貌的聊天机器人。

审计自检

如果符合以下任一条件，请将审计标记为 INCOMPLETE，并将计数作为证据一并列出（各 playbook 计划运行的规则数与实际运行的规则数、unknown 比例、已抑制数量）：

• 实际运行的规则数少于各 playbook 计划的规则数
• 超过 30% 的规则返回了 unknown。这里只统计 unknown，绝不统计 out-of-scope：如果某条规则的层级不在给定的范围内，那么该规则的回答就是正确的；而范围应当采用 Step 1 要求的精简差异。将范围正确的审计标记为 INCOMPLETE，会让真正的阻碍被一个“我们什么也没学到”的结论掩盖。
• 任何 fail/warn 发现都缺少 file:line 证据或修复代码片段
• 所有发现都归入了同一个层级（疑似一概而论）
• 检测到 Agent 功能，但缺少 AX Relationship Summary

相关技能

• ui-design 审计模式：针对 Agent 功能界面的传统前端 UX；对于 Agent 功能 PR，请同时运行两者
• dx-audit：审查相同文件，但面向不同读者。此技能关注 Agent 能否操作和恢复；dx-audit 关注采用 API、CLI 或类型的人类用户能否获得良好的使用体验
• agent-ready：公共文档和 HTTP API 是否便于编码 Agent 发现；此技能审计产品内的 Agent UX
• product-design：本次审计之前，确定 Agent 功能应实现什么
• agents-md：CLAUDE.md / AGENTS.md 指令文件

仅用于维护：evals/evals.json 和 evals/evaluation-scenarios.md 保存了此技能变更的回归场景；执行用户任务时不会加载这两个文件。