规范与代码合规性
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Spec-to-Code Compliance
Two artifacts disagree, and the job is to find where. The documentation says what the system does; the code
decides what it actually does. Every gap between them is either a bug or a documentation fix, and which one it
is is the finding.
## When to Use
You have both documentation describing intended behavior and the code that should implement it. A whitepaper
against a protocol, a design note against a service, a README's stated guarantees against the functions behind
them.
Most useful when the document is authoritative — something a client wrote, published, or is audited against —
because then a divergence is a defect rather than stale prose.
## When NOT to Use
Not for code with no documentation of intended behavior. There is nothing to check against, and a requirement
inferred from the code is checked against itself. Build the system model first with `audit-context-building`.
Not for finding bugs in general. This finds one class: where the code and the document disagree. A bug both
artifacts are silent about is out of scope, and a bug the document endorses is a finding against the document.
Not for writing or improving documentation, though it produces the list of what needs fixing.
## Do not check requirements in this context
Run `/spec-to-code-compliance:spec-compliance <path>`. The slash command takes a path; to name the
specification directly or widen the fan-out, ask for the run with those values — "run spec-compliance on
./contracts against SPEC.md, checking 20 requirements" — and they reach the script as `{path, spec, limit}`.
Typing the object literally after the slash command does not work; it arrives as a string and becomes the path.
It finds the documents, splits them into individually checkable requirements, gives each requirement its own
agent to hunt the code with, has independent agents try to refute every divergence before it is reported, and
writes `spec-compliance/REPORT.md` plus one file per requirement under `spec-compliance/requirements/`. Only
compact records come back here.
For a single requirement, dispatch the `spec-to-code-compliance:spec-compliance-checker` agent at it.
This is not a preference about where output lands. The check does not fit in one context window if it is done
honestly: judging one requirement means reading the enforcement, its callees, and its callers, and doing that
for thirty requirements means holding thirty call chains at once. Attempted inline, the first few get a real
check and the rest get a plausible one — and the transcript looks the same either way, because a verdict resting
on a promising function name reads exactly like one resting on having read the function. Per requirement, in its
own context, is what makes that difference visible.
Two properties come from the script rather than from instructions, and cannot be had here:
- **A refutation the finding's author did not perform.** Claude favors findings it produced when asked to check
them. The workflow sends each divergence to agents that did not produce it — one reading the code again, one
re-reading the document — and drops what either knocks down.
- **Records that cannot be prose.** A subagent bound to a return schema has to name the lines it read and the
searches it ran. An `absent` verdict arrives with the patterns tried and their results attached, which is the
only thing separating a real absence from a search that stopped early.
Measured on the `routes-not-inline` eval: with this plugin installed the work is dispatched every run, without
it never — Δ +1.00. Deleting this section while leaving the workflow in place changes nothing, because the
workflow is a real command that gets found and dispatched on its own. Read that as the mechanism carrying the
behavior rather than this text: the section is here so a human knows what runs and why, not because the routing
depends on it.
## What comes back, and how to read it
Every requirement gets one of six verdicts: `implemented`, `partial`, `contradicted`, `stronger-than-spec`,
`absent`, or `undecidable`. The interesting ones are the middle four.
- **`partial`** is usually the most serious thing in the report. The requirement holds on the paths anyone would
test and fails on one nobody did, which is how it survived long enough to be found.
- **`absent`** rests entirely on its `searched` record. Read it. Enforcement often lives somewhere the search
did not go — a modifier, a base class, a caller that checks first.
- **`undecidable`**, and any `documentProblem`, are findings about the documentation. A requirement too vague to
check is one the client cannot hold anyone to.
- **`stronger-than-spec`** is an undocumented constraint. It works today, and nothing tells the next person
changing that code that anything depended on it.
The report also carries the reverse direction — behavior the code has that no document mentions — which the
per-requirement pass cannot find by construction, since it is driven by the documents.
Read `notChecked`, `unverified`, and `unreadableDocuments` before treating the report as complete. Requirements
below the fan-out cut were never checked, and a divergence whose refutation agents both failed is unverified
rather than confirmed.
## Judgment the workflow does not make for you
Severity is consequence, not distance from the text: [DIVERGENCE_RUBRIC.md](resources/DIVERGENCE_RUBRIC.md). A
rounding step that bleeds a pool outranks a MUST satisfied by different means than the document describes, and
documentation drift with no behavioral consequence is a docs ticket.
The verdict is not the finding. `absent` on a mandatory requirement is a finding; `absent` on a sentence
describing a roadmap item is not. Deciding which is which is what this skill is for, and the workflow hands you
the evidence to decide it with.
## The target does not have to be a contract
The question is the same everywhere — what does this requirement demand, where would it be enforced, is it
enforced on every path — but what counts as a specification and where enforcement hides both change.
[DOMAIN_NOTES.md](resources/DOMAIN_NOTES.md) maps that across contracts, C and C++, services, and decompiled
firmware, and covers the case where the specification is an RFC or a standard rather than a project document.
Read it when the target is not a contract, and when scoping a check against a large standard.
## Reference
- [ANALYSIS_FORMAT.md](resources/ANALYSIS_FORMAT.md) — the on-disk format for a per-requirement analysis. Read
when extending this plugin or judging whether a record is trustworthy.
- [WORKED_EXAMPLE.md](resources/WORKED_EXAMPLE.md) — three requirements chased to a verdict, one per verdict
that is easy to get wrong: arithmetic that satisfies a requirement it does not resemble, an absence whose
searches are the finding, and enforcement present on every path but the one nobody tested.
- [DOMAIN_NOTES.md](resources/DOMAIN_NOTES.md) — per-domain mapping of specifications and enforcement.
- [DIVERGENCE_RUBRIC.md](resources/DIVERGENCE_RUBRIC.md) — severity, and the two directions of a gap.
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
不要检查这种情况下的要求
返回什么以及如何读取它
工作流程不适合你的判断
文件/命令 -> audit-context-building · /spec-to-code-compliance:spec-compliance <path> · {path, spec, limit} · spec-compliance/REPORT.md · spec-compliance/requirements/ · spec-to-code-compliance:spec-compliance-checker · absent · routes-not-inline
内容校验值 -> a9eb11c50d86
当前原文的自动摘译,尚未人工审校。
何时使用
您既有描述预期行为的文档,也有应该实现它的代码。针对协议的白皮书、针对服务的设计说明、针对其背后功能的自述文件声明的保证。当文档具有权威性(客户撰写、发布或审核的文档)时最有用,因为这样的话分歧就是一种缺陷,而不是陈旧的散文。
何时不使用
不适用于没有预期行为文档的代码。没有什么可以检查的,从代码中推断出的需求会根据自身进行检查。首先使用
audit-context-building构建系统模型。一般不用于发现错误。这会找到一类:代码和文档不一致的地方。两个工件都没有提及的错误超出了范围,而文档认可的错误是针对该文档的发现。不要检查这种情况下的要求
运行
/spec-to-code-compliance:spec-compliance <path>。斜杠命令采用路径;要直接命名规范或扩大扇出,请要求使用这些值运行 - “根据 SPEC.md 在 ./contracts 上运行规范合规性,检查 20 个要求” - 然后它们会以{path, spec, limit}的形式到达脚本。在斜杠命令后面按字面输入对象是行不通的;它以字符串形式到达并成为路径。返回什么以及如何读取它
每个需求都会得到六个结论之一:
implemented、partial、contradicted、stronger-than-spec、absent或undecidable。有趣的是中间的四个。partial通常是报告中最严重的事情。该要求适用于任何人都可以测试的路径,而在没有人测试过的路径上失败,这就是它如何存活足够长的时间并被发现的原因。absent完全依赖于其searched记录。阅读它。执行通常位于搜索的某个地方工作流程不适合你的判断
严重性是结果,而不是与文本的距离:DIVERGENCE_RUBRIC.md。使池中的资源流失的舍入步骤超过了通过与文档描述的不同方式满足的“必须”,并且没有行为后果的文档漂移是一张文档票。判决不是调查结果。关于强制性要求的
absent是一项发现;描述路线图项目的句子中的absent不是。决定该技能的用途,工作流程将交给您