
Spec-receipt:比对代码与规格文档是否一致的工具
来源标题:Show HN: Spec-receipt – does your code still match your spec?
开发者发布静态工具 spec-receipt,可将 Markdown 规格声明与 Python 代码声明逐项比对,输出 IMPLEMENTED、MISSING、CONTRADICTED 或 UNTRACED 结论并附文件行号证据。该工具不调用 LLM、不联网、不执行任何代码,仅读取 Markdown 文本和 Python AST。作者称其目的是解决代码变动后规格文档逐渐失真的问题。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
你的 spec 写着 POST /items。用 receipt 核对一下——每个 spec 条目 IMPLEMENTED、MISSING、CONTRADICTED 或 UNTRACED,每个代码表面 DOCUMENTED 或 UNDOCUMENTED,都附上文件和行号证据。
spec 是设计阶段许下的承诺。之后代码会变:一个 flag 被删掉,一个默认值悄悄改变,某个 endpoint 的 method 翻转,一个被禁止的 flag 又偷偷溜回来,一个任何文档都没提到的功能上线了。审查能抓住一部分,记忆抓住的更少,spec 慢慢变成虚构——但它仍然是新贡献者、agent 和审查者最先信任的文档。
spec-receipt 打印的是 receipt。它提取 spec 声明的内容(flags、commands、endpoints、config keys、环境变量、需求 ID——通过确定性模式,从任意 Markdown spec 中),提取代码声明的内容(同样的五类表面,通过 Python AST),然后打印逐条判定,并附上双方的引用证据。没有 LLM。没有评分。没有网络。不上传任何东西。
静态且只读——它不执行任何东西。目标仓库只被当作 Markdown 文本和 Python AST 来读取:没有文件被运行、导入、编译或求值。它自己的源码不导入任何网络或 subprocess 模块,测试套件证明了只读声明:一个如果运行就会写标记文件的 fixture 模块永远不会运行,而且每次检查后每个 fixture 树都字节级完全一致。
判定在设计上很吝啬。只有当某一表面类别被完整枚举且该项在其中缺失时,才会发出 MISSING。CONTRADICTED 需要双方都有硬证据——声明的默认值对应不同的代码默认值,"不存在 --legacy" 对应 flag 自己的 AST 节点。散文式需求永远不会被判定为已实现或缺失:它要么被 TRACED 到代码或测试中的锚点,要么诚实地标为 UNTRACED。自然语言无法证明某个行为不存在,receipt 也从不假装它能。
该仓库自带的漂移 fixture,实时 receipt——--mode 默认值被矛盾,--level 缺失,POST /items 被矛盾,共 17 项,以 Verdict: DRIFT 收尾(27 秒,真实运行,无任何暂存)。
三个工具,一套语法——文档 = 声明,代码 = 证据,每个判定都有引用:
而在它们之前: skill-vet——它危险吗?窃取、间谍、隐藏发送,每一项都作为证据组合被证明。
pipx install spec-receipt # 或:pip install spec-receipt spec-receipt check path/to/repo
(自 v1.0.0 起在 PyPI 上线。源码检出也可用:python3 src/spec_receipt.py check <repo>,或 pipx install git+https://github.com/jasveerai88/spec-receipt。)
一条命令,一份 receipt,一个可以用于门禁的退出码——1 = 发现漂移(至少一项 MISSING 或 CONTRADICTED),0 = 无漂移,2 = 输入错误。加 --json 可获得机器可读的 receipt。Python 3.10+,仅标准库,无依赖。
哪个文件是 spec,按优先级顺序:
五类表面,从 spec 中提取并从代码中索引,双向判定:
外加需求项:携带 ID 的行(FR-###、REQ-<word>、R-##)会被追踪到锚点——代码或测试中逐字出现的 ID(限定在该 ID 自己的 spec 范围内),或者其两个或更多独特陈述术语在同一范围内文件中共同出现。
快速开始 · 它检查什么 · 如何比较 · 参考
spec-receipt chenhz01/spec-drift lilabrooks/spec-drift spec-kit /speckit.analyze
问题 代码是否仍然匹配 spec? spec-kit 的 spec 与其测试锚点是否一致? 按治理文档,这个 diff 中改了什么? spec、plan 和 tasks 文档是否一致?
范围 全仓库快照,事后 仅 spec-kit 布局(specs/NNN/spec.md、FR-###) 一个 diff 范围(base..HEAD) 编写过程中,流程内
检查内容 五类表面(flags、commands、routes、config、env)+ 需求追踪,双向 FR↔测试锚点和 spec 间取代关系 变更文件,对照其治理文档 Spec ↔ plan ↔ tasks——仅文档,从不涉及实现
方法 确定性模式 + AST——同一仓库,永远同一份 receipt 词法分析,零依赖,无 LLM 由 LLM 判定(Anthropic/OpenAI 密钥,逐文件模型调用,API 费用) 编写 agent,在环内
输出 逐条判定——MISSING / CONTRADICTED 仅在完整枚举或直接冲突时发出——双方都附文件和行号 "候选,绝非判定"(其 README 原话) 对 diff 的 LLM 漂移判断 编写流程内的一致性发现
许可证 / 状态 MIT,维护中 Apache-2.0 专有;其 README 将实验标记为即将结束 / 正在退役 github/spec-kit 的一部分
(可比描述来自它们各自的公开页面和 README,核查于 2026-11-06。chenhz01/spec-drift 是最接近的邻居,也是诚实的先前工作——其 README 发现对术语追踪必不可少的停用词 + 文档频率过滤,这里也使用了。spec-receipt 填补的空白正是 /speckit.analyze 按设计留下的:事后、针对代码、适用于任意 Markdown spec 格式。)
静态模式是证据,不是证明。纯运行时构建的表面可能不出现在索引中;无法完整枚举的类别会标记为 partial,其缺失判定会降级为 UNTRACED,而不是升级为 MISSING;散文式需求只被追踪,从不做语义判定。提取是有意限定范围的——spec 对其自身记法的示例不算声明,某些声明形态会因此被遗漏(每一种都在完整限制中列出)。每份 receipt 都会完整打印其限制;完整列表如下。
目录:漂移 fixture · 干净 fixture · 自用门禁 · 面向 agent · 测试 · 诚实的限制
tests/fixtures/drifted/ 是一个构造的仓库,其代码相对于冻结的 SPEC.md 发生了演化:一个 spec 中的 flag 被删除,一个默认值被改变,一个被禁止的 flag 被添加,一个 endpoint 的 method 从 POST 改为 GET,一个未文档化的 flag 生长出来,一个需求的测试被重命名掉。逐字输出:
$ spec-receipt check tests/fixtures/drifted spec-receipt 1.0.0 — spec drift receipt
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。