ax-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AX Audit

AX 审计

Feature-level reviewer for apps where an agent acts for the user. One question: does it earn trust, and where does it break?

IS: rules-based audit of agentic surfaces (chat, tool execution, config, dashboards) across architecture (
```
rules-arch/
```
) and trust (
```
rules-ax/
```
), ending in a ship-readiness verdict plus an AX Relationship Summary.
IS NOT: traditional frontend UX (use
```
ui-design
```
Audit mode); developer-facing API, CLI, or type ergonomics (use
```
dx-audit
```
); agent instruction files (use
```
agents-md
```
); what the product should do before it exists (use
```
product-design
```
).

No agentic features in scope? Stop. AX rules against forms and lists are noise.

针对由Agent代表用户操作的应用的功能级审查工具。核心问题：它是否能赢得用户信任，又在哪些环节失去信任？

适用场景：基于规则对Agent交互界面（聊天、工具执行、配置、仪表盘）进行架构（
```
rules-arch/
```
）和信任体验（
```
rules-ax/
```
）审计，最终给出发布就绪判定结果及AX关系摘要。
不适用场景：传统前端UX（请使用
```
ui-design
```
审计模式）；面向开发者的API、CLI或类型ergonomics（请使用
```
dx-audit
```
）；Agent指令文件（请使用
```
agents-md
```
）；产品未成型前的需求设计（请使用
```
product-design
```
）。

如果没有Agent相关功能，请停止审计。针对表单和列表的AX规则会产生无效结果。

Audit workflow

审计流程

text

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-mode scope is the diff plus the tool definitions and orchestrator it touches. Findings in untouched files belong in a full sweep, not this verdict. Playbook annotations are a scan copy; the rule file is authoritative.

parity-orphan-ui-action

runs on every PR-mode audit and never in a full sweep, where there is no diff for it to read.

Rule greps name the most common identifiers, not every framework's spelling. When a grep misses in code that plainly does the thing (a gate, a stream, a tool result), check

references/framework-signals.md

for the stack's name for it before recording

unknown

text

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模式的范围是代码差异及其涉及的工具定义和编排器。未改动文件中的问题应在全面扫描中排查，而非本次判定结果。剧本注释仅为扫描副本，规则文件具有权威性。

parity-orphan-ui-action

仅在PR模式审计中运行，全面扫描模式下因无代码差异可读取，不会执行该操作。

规则中的grep命令仅列出最常见的标识符，并非覆盖所有框架的写法。当grep在明确包含相关功能（如网关、流、工具结果）的代码中未命中时，请先查看

references/framework-signals.md

中对应技术栈的命名方式，再记录为

unknown

。

Two rule layers

两层规则体系

Layer	Folder	Rules	Load when a playbook names
1: Architecture	`rules-arch/`	12	`rules-arch/<category>-<slug>.md`
2: Experience	`rules-ax/`	15	`rules-ax/<category>-<slug>.md`

Categories: arch = parity, granularity, context, comm; ax = trust, control, context, comm. Shared prefixes are different rules:

rules-arch/comm-no-approval-gate.md

(no gate on the execution path) is not

rules-ax/control-no-approval-gate.md

(gate exists, stakes are wrong).

Run Layer 1

comm

parity

and Layer 2

control

trust

first. They hold the blockers. Category map:

rules-arch/_sections.md

rules-ax/_sections.md


comm-
parity-
control-
trust-
context-
comm-
context-
granularity-

Priority	Layer	Category	Prefix	Rules
1	arch	Communication	`comm-`	3
2	arch	Parity	`parity-`	4
3	ax	Control	`control-`	4
4	ax	Trust	`trust-`	4
5	arch	Context	`context-`	3
6	ax	Communication	`comm-`	4
7	ax	Context	`context-`	3
8	arch	Granularity	`granularity-`	2

层级	文件夹	规则数量	加载时机
1: 架构层	`rules-arch/`	12	当剧本指定 `rules-arch/<category>-<slug>.md` 时
2: 体验层	`rules-ax/`	15	当剧本指定 `rules-ax/<category>-<slug>.md` 时

分类说明：架构层包含一致性、粒度、上下文、通信；体验层包含信任、控制、上下文、通信。前缀相同的规则为不同规则：

rules-arch/comm-no-approval-gate.md

（执行路径无网关）与

rules-ax/control-no-approval-gate.md

（网关存在，但风险等级不匹配）并非同一规则。

优先运行架构层的「通信」/「一致性」规则和体验层的「控制」/「信任」规则，这些规则涉及发布阻塞项。分类映射可查看

rules-arch/_sections.md

和

rules-ax/_sections.md

。


comm-
parity-
control-
trust-
context-
comm-
context-
granularity-

优先级	层级	分类	前缀	规则数量
1	架构层	通信	`comm-`	3
2	架构层	一致性	`parity-`	4
3	体验层	控制	`control-`	4
4	体验层	信任	`trust-`	4
5	架构层	上下文	`context-`	3
6	体验层	通信	`comm-`	4
7	体验层	上下文	`context-`	3
8	架构层	粒度	`granularity-`	2

Tiers and verdict

分级标准与判定结果

Three tiers. Full trigger lists and the generic surface bump live in

references/ship-readiness.md

Precedence: the rule's own surface-override table > the generic bump >

defaultTier

. Apply at most one adjustment.

Verdict: ✅ READY (0 blockers, ≤3 sprint) · ⚠️ READY WITH FOLLOW-UP (0 blockers, ≥4 sprint) · ❌ NOT READY (≥1 blocker) · 🚫 INCOMPLETE (self-check failed).

Blockers outrank an incomplete audit. With ≥1 release-blocker and a failed self-check, report ❌ NOT READY and note the self-check failure beneath it: the blockers are established findings and stay actionable, while 🚫 reads as "nothing was learned" and sends the reader away. Reserve 🚫 for an audit with no blockers whose coverage you cannot vouch for.

分为三个等级。完整触发条件和通用等级调整规则请查看

references/ship-readiness.md

。

优先级：规则自身的覆盖表 > 通用等级调整 >

defaultTier

。最多仅应用一次调整。

判定结果：✅ 就绪（0个阻塞项，≤3个待办 sprint） · ⚠️ 需跟进后就绪（0个阻塞项，≥4个待办 sprint） · ❌ 未就绪（≥1个阻塞项） · 🚫 不完整（自检未通过）。

阻塞项的优先级高于不完整的审计结果。当存在≥1个发布阻塞项且自检未通过时，需报告❌ 未就绪，并在下方注明自检失败原因：阻塞项是已确认的问题，仍需处理；而🚫 会被解读为「未获取有效信息」，导致读者忽略问题。仅当审计无阻塞项但无法保证覆盖范围时，才使用🚫 不完整的判定。

AX Relationship Summary

AX关系摘要

Render after findings when any agentic feature was detected. Findings serve engineers; this serves designers and PMs. Four fields: evolution stage (behavior, not a label), trust signal (high/moderate/low plus one-line reason), key gap (one actionable sentence), trust question (one question only research can answer).

当检测到任何Agent相关功能时，需在问题排查结果后生成该摘要。问题排查结果面向工程师，该摘要面向设计师和产品经理。包含四个字段：演进阶段（行为描述，而非标签）、信任信号（高/中/低+一句话说明）、核心差距（一句可落地的改进描述）、信任疑问（仅需一个需通过研究解答的问题）。

Reference files

参考文件

File	Read when
`references/feature-playbooks.md`	Steps 2-3: detection heuristics, per-feature ordered checks, diff-wide checks
`references/framework-signals.md`	Step 4, when the code uses AI SDK, MCP, the Claude Agent SDK, or AG-UI: where the gate, the stream, the completion signal, and the structured result live in each, with the spec defaults the rules lean on
`references/ship-readiness.md`	Step 5: tier triggers, precedence, verdict logic
`references/output-format.md`	Step 6: findings JSON schema, summary schema, terminal rendering
`references/agent-native-principles.md`	A Layer 1 finding needs grounding the rule file does not carry
`references/ax-evolution-curve.md`	Writing the AX Relationship Summary: stage, action depth, costume vs intelligence
`references/invisible-interface.md`	Grounding for structured tool output, approval payload, access scope, unprompted action; also the arguments that stay in `keyGap`
`references/evaluation-scenarios.md`	When changing this skill. Never loads during a user audit
`rules-arch/_sections.md`	Layer 1 categories, default tiers, co-firing pairs
`rules-ax/_sections.md`	Layer 2 categories, default tiers, co-firing pairs

文件	读取时机
`references/feature-playbooks.md`	步骤2-3：检测启发式规则、按功能排序的检查项、全差异检查（仅PR模式）
`references/framework-signals.md`	步骤4，当代码使用AI SDK、MCP、Claude Agent SDK或AG-UI时：查看各技术栈中网关、流、完成信号、结构化结果的位置，以及规则依赖的规范默认值
`references/ship-readiness.md`	步骤5：分级触发条件、优先级、判定逻辑
`references/output-format.md`	步骤6：问题排查结果JSON schema、摘要schema、终端渲染格式
`references/agent-native-principles.md`	架构层问题排查结果需补充规则文件未包含的依据
`references/ax-evolution-curve.md`	撰写AX关系摘要：阶段、操作深度、外在表现vs智能能力
`references/invisible-interface.md`	结构化工具输出、审批负载、访问范围、主动操作的依据；同时用于确定「核心差距」中的内容
`references/evaluation-scenarios.md`	修改本技能时使用。用户审计过程中不会加载该文件
`rules-arch/_sections.md`	架构层分类、默认等级、关联规则组
`rules-ax/_sections.md`	体验层分类、默认等级、关联规则组

Gotchas

注意事项

Scope before rules. Running all 27 rules repo-wide on a 3-file PR buries a new release-blocker under pre-existing backlog noise; the verdict stops meaning "can this PR merge."
The rule's override table is authoritative.
```
comm-no-intent-handshake
```
defaults to
```
fix-this-sprint
```
but its table says
```
release-blocker
```
on tool execution. Stacking the generic "+1 tier on tool execution" bump on an explicit override double-upgrades backlog findings into blockers.
A stop button not wired to
AbortController.abort()
is a false affordance.
```
control-no-escape-hatch
```
still fails: verify the
```
abort()
```
call, not the button label, or the audit passes a UI that lies to users.
A client
stop()
that only closes the stream leaves the executor running.
```
useChat().stop()
```
aborts the fetch. Unless the route passes
```
req.signal
```
into
```
streamText({ abortSignal })
```
and tool
```
execute
```
reads it, the server finishes every remaining tool call after the user pressed Stop. Trace the signal to the loop, not to the button.
Tool annotations are hints, not stakes. MCP tells clients to treat
```
annotations
```
from untrusted servers as untrusted; a gate that auto-approves on a third-party server's
```
readOnlyHint: true
```
has handed the gate to that server.
```
comm-no-approval-gate
```
fails it. The spec defaults (
```
destructiveHint: true
```
,
```
readOnlyHint: false
```
) are the fail-closed baseline.
A framework approval flag is the gate's input, not the gate. AI SDK
```
toolApproval: "user-approval"
```
emits a
```
tool-approval-request
```
part and waits. A UI that never renders
```
state === "approval-requested"
```
, or answers it with
```
addToolApprovalResponse({ approved: true })
```
on arrival, has a gate in the type system and none for the user. Check the renderer and the response call, not the option.
Absence checks need a recorded file list. "Find components lacking X" greps return nothing both when everything passes and when nothing was scanned. List candidate files first (
```
rg -l <feature-pattern>
```
), check each for the counter-pattern, and cite the file list as evidence.

detection: observational
rules cannot fail on grep evidence alone.

granularity-static-api-mapping

trust-no-uncertainty-markers

control-over-conversational

, and

comm-no-generative-momentum

need interaction-flow judgment; on static evidence alone, return

unknown

with a reason, not

fail

Gates fail in three separate places. Absent from the path (
```
comm-no-approval-gate
```
), present but mismatched to the stakes (
```
control-no-approval-gate
```
), or correct and unreadable (
```
control-thin-approval-payload
```
). Report the first that holds and fix in that order.
Interactive gates do not cover unattended runs. Cron, webhook, and queue entry points reach the same executor with nobody to prompt.
```
comm-unrequested-action-no-consent
```
audits that path; evidence names the entry point, not the executor.
ax-audit-ignore:<slug>
comments count as
suppressed
, not
pass
. Report the count in the verdict block; a suppression with no reason is itself a
```
warn
```
.
Don't inflate tiers.
```
comm-no-generative-momentum
```
and
```
granularity-static-api-mapping
```
default to
```
backlog
```
. One finding promoted to
```
release-blocker
```
flips the whole PR to ❌ NOT READY, so promoting cosmetic ones trains the team to ignore the verdict entirely.
Don't duplicate
ui-design
Audit mode findings. "Missing loading state" and "form clears on error" are its territory; duplicating them trains engineers to dismiss the whole AX report.
A Personally Intelligent agent that only ever suggests has plateaued. Memory stage is not trust. Name the highest action rung in
```
evolutionStage.behavior
```
or the summary flatters a polite chatbot.

先确定范围，再执行规则。针对仅改动3个文件的PR，在全仓库运行27条规则会导致新的发布阻塞项被淹没在既有待办问题中，使得判定结果失去「该PR是否可合并」的参考意义。
规则的覆盖表具有权威性。
```
comm-no-intent-handshake
```
默认等级为「fix-this-sprint」，但其覆盖表显示在工具执行场景下为「release-blocker」。若在明确覆盖的基础上再叠加通用的「工具执行场景下等级+1」调整，会将待办问题错误升级为阻塞项。
未绑定
AbortController.abort()
的停止按钮属于虚假交互。
```
control-no-escape-hatch
```
规则仍会判定失败：需验证
```
abort()
```
调用是否存在，而非仅检查按钮标签，否则审计会通过一个向用户撒谎的UI。
仅关闭流的客户端
stop()
会导致执行器继续运行。
```
useChat().stop()
```
会终止请求。除非路由将
```
req.signal
```
传入
```
streamText({ abortSignal })
```
，且工具
```
execute
```
读取该信号，否则用户点击停止后，服务器仍会完成所有剩余工具调用。需追踪信号至循环逻辑，而非仅检查按钮。
工具注释仅为提示，而非风险判定依据。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>
```
），再逐个检查反模式，并将文件列表作为证据引用。
detection: observational
规则无法仅通过grep证据判定失败。
```
granularity-static-api-mapping
```
、
```
trust-no-uncertainty-markers
```
、
```
control-over-conversational
```
和
```
comm-no-generative-momentum
```
规则需要交互流程判断；仅靠静态证据时，需返回
```
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判定为❌ 未就绪，因此将 cosmetic 问题升级会让团队忽略判定结果的严肃性。
不要重复
ui-design
审计模式的结果。「缺少加载状态」和「表单错误时清空内容」属于
```
ui-design
```
的范畴；重复报告这些问题会让工程师忽略整个AX报告。
仅提供建议的Personal Intelligent Agent已达瓶颈。记忆阶段不等同于信任。需在
```
evolutionStage.behavior
```
中注明最高操作层级，否则摘要会错误地美化一个仅能礼貌聊天的机器人。

Audit self-check

审计自检

Flag the audit

INCOMPLETE

if any of these hold, and include the counts as evidence (planned vs. run rules per playbook, unknown rate, suppressed count):

Fewer rules ran than the playbooks planned
More than 30% of rules returned
```
unknown
```
. Count only
```
unknown
```
here, never
```
out-of-scope
```
: a rule whose layer is absent from the scope you were given was answered correctly, and a narrow diff is the scope Step 1 asks for. Marking a correctly scoped audit INCOMPLETE buries its real blockers under a verdict that reads as "we learned nothing".
Any
```
fail
```
/
```
warn
```
finding lacks
```
file:line
```
evidence or a fix snippet
Every finding landed in the same tier (suspect blanket assignment)
AX Relationship Summary is missing despite detected agentic features

若出现以下任一情况，需标记审计为「不完整」，并将相关计数作为证据（剧本计划运行的规则数vs实际运行数、未知结果占比、抑制项数量）：

实际运行的规则数少于剧本计划的数量
超过30%的规则返回
```
unknown
```
。此处仅统计
```
unknown
```
，不统计
```
out-of-scope
```
：若规则所属层级不在给定范围内，则判定正确，且范围缩小是步骤1的要求。将正确范围的审计标记为不完整，会导致真正的阻塞项被「未获取有效信息」的判定结果掩盖。
任何
```
fail
```
/
```
warn
```
结果缺少
```
file:line
```
证据或修复代码片段
所有结果都属于同一等级（怀疑存在批量赋值）
检测到Agent相关功能但未生成AX关系摘要