spec-audit-drift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Audit a Spec for Drift

审核规范偏差

Does the spec still describe what the code does? Reports only — fixing is

spec-maintain-on-ship

, and an auditor that can edit can make its own findings disappear.

Format authority:

references/spec-format.md

规范是否仍能准确描述代码的实际功能？仅生成报告——修复工作需使用

spec-maintain-on-ship

，具备编辑权限的审核者可自行消除发现的问题。

格式参考：

references/spec-format.md

。

When to use

使用场景

"Is this spec still accurate?"
Before planning work against a spec nobody has touched recently.
Suspicion that a journey does something the contract doesn't allow.

Not this skill: whether tests exist (

spec-assess-coverage

), updating the spec (

spec-maintain-on-ship

), classifying a bug report (

spec-triage-bug-report

“这个规范是否仍然准确？”
在基于长时间无人维护的规范规划工作之前。
怀疑用户流程存在契约未允许的操作。

**不适用此技能的场景：**检查是否存在测试（

spec-assess-coverage

）、更新规范（

spec-maintain-on-ship

）、分类 bug 报告（

spec-triage-bug-report

）。

Workflow

工作流程

1. Read the spec completely first

1. 先完整阅读规范

All behaviours, invariants, decision tables, and the flow contract. Form the expectation before looking at code — reading them together lets the code quietly redefine what the spec "meant".

通读所有行为、不变量、决策表和流程契约。在查看代码前先形成预期——如果同时阅读两者，代码会悄悄重新定义规范的“含义”。

2. Check each behaviour against the implementation

2. 逐一对照实现检查每个行为

For every behaviour ID, find the code that produces it and classify:

Verdict	Meaning
Matches	Code produces the described outcome
Drifted	Code produces a different outcome — the spec is now wrong
Missing	Badged 🟢 or 🟡 but no implementing code found
Unspecced	Code produces observable behaviour no behaviour describes
Badge wrong	Behaviour exists but the badge overstates or understates it

Unspecced is the category people forget and it's often the most valuable: features grow paths nobody recorded.

针对每个行为 ID，找到对应的实现代码并分类：

结论	含义
匹配	代码产生的结果与描述一致
偏差	代码产生的结果与描述不同——规范已失效
缺失	标记为🟢或🟡但未找到实现代码
未纳入规范	代码产生了规范中未描述的可观察行为
标记错误	行为存在，但标记夸大或低估了实际情况

未纳入规范是人们常忽略的类别，且往往最有价值：功能会衍生出无人记录的路径。

3. Check invariants are actually enforced

3. 检查不变量是否真的得到执行

For each invariant, find the code path enforcing it — and, more importantly, look for paths that bypass it. An invariant enforced in one mutation and not its sibling is a finding, not a match.

针对每个不变量，找到执行它的代码路径——更重要的是，寻找绕过它的路径。如果某个不变量在一个变更中被执行，但在其关联的变更中未执行，这属于问题发现，而非匹配。

4. Check the flow contract against real navigation

4. 对照实际导航检查流程契约

For each transition: does the code implement it, with that guard, reaching that state?

Then the harder direction — what can the code do that the contract doesn't declare? Undeclared bypasses, skipped steps, a back path that loses state, an error path that dead-ends. This is what a flow contract exists to catch, so spend the effort here.

Report guard mismatches precisely: a guard the code checks more loosely than the contract states is a real defect even when nothing has gone wrong yet.

针对每个过渡：代码是否按契约中的守卫条件实现了该过渡并到达指定状态？

然后检查更复杂的方向——**代码能执行哪些契约未声明的操作？**未声明的绕过路径、跳过的步骤、会丢失状态的返回路径、陷入死胡同的错误路径。这正是流程契约要捕捉的问题，因此需在此投入精力。

精确报告守卫条件不匹配的情况：即使目前未出现问题，若代码检查的守卫条件比契约中规定的更宽松，这也是一个实际缺陷。

5. Verify before reporting

5. 报告前验证

Confirm each finding against current code. Check whether shared middleware or a helper handles what looks missing. Drop anything already handled. Fewer verified findings beat a long speculative list.

对照当前代码确认每个发现。检查看似缺失的部分是否由共享中间件或辅助工具处理。剔除已被处理的内容。少量经过验证的发现胜过冗长的推测性列表。

6. Report

6. 生成报告

Group by verdict, most severe first. Each finding: behaviour or transition ID,

file:line

, what the spec says, what the code does, and which one you think is wrong — with a reason.

That last part matters. Drift has two fixes: update the spec because the change was intended, or fix the code because it wasn't. Say which you believe and why; don't leave a bare mismatch for someone else to decide blind.

End with: counts by verdict, and whether the front-matter roll-up status is still right.

按结论严重程度分组，从最严重的开始。每个发现需包含：行为或过渡 ID、

文件:行号

、规范描述的内容、代码实际执行的内容，以及你认为哪一方存在问题并给出理由。

最后一点至关重要。偏差有两种修复方式：若变更是有意为之则更新规范，若变更无意则修复代码。说明你的判断及理由，不要只留下一个裸的不匹配让他人盲目决策。

报告结尾需包含：各结论的数量统计，以及前端汇总状态是否仍然正确。

Quality gate

质量检查清单

Anti-patterns

反模式

Only checking spec → code. Misses everything the feature grew.
Reading code and spec together. Form the expectation first.
Reporting a mismatch without a recommendation. Half a finding.
Accepting an invariant as enforced because one path enforces it.
Fixing during the audit.

仅检查规范→代码：会遗漏功能衍生的所有内容。
同时阅读代码和规范：应先形成预期。
仅报告不匹配而不给出建议：这只是半完成的发现。
因某一条路径执行了不变量就认为它已被执行。
审核过程中直接修复问题。