格式
Markdown + YAML。在任何能打开文本的编辑器中使用。 无需新工具即可开始编写。
规格说明中的每一处歧义，
都是你的 AI 代理烧掉的 token。
然后是开发途中的一个澄清问题。然后是上线之后的一次修复。 然后是你一遍遍重新解释的上下文。
SpecScore 是一种用于规格说明的开放、可 lint 的文件格式—— 就像 JSON 之于数据。并配有 CLI，供你的 AI 代理调用以查询和 编辑它们——就像 jq 之于 JSON。
为你已有的规格说明提供格式。
SpecScore 是一种基于 Markdown + YAML 的格式，用于描述功能、 需求和验收标准。它定义了一种你的团队和 AI 代理都能理解的结构——而它只是仓库中的文件。
一个 SpecScore 项目包含三种生命周期制品：Idea（构想）捕捉一个半成形的方向；Feature（功能）冻结已达成共识的行为；Plan（计划）将功能分解为有序任务， 每个任务引用它所满足的验收标准。
为什么你的 AI 代理在意。因为结构是机器可读的， AI 代理可以通过 CLI 查询规格说明，而不必读取每一个文件。问一句“我接下来该做什么？”，CLI 就会返回开放的 Feature 和尚未回答的问题。和你团队评审的是同一份形态，但代理需要加载的 上下文要少得多。
规格说明是层级结构。所以你的规格树也是。
当 Feature 数量达到五十个时，扁平列表就会变成一堆乱麻。 SpecScore 让树保持可导航——父节点掌管范围，子节点掌管细节， 目录结构映射的正是你的团队早已在头脑中梳理的产品结构。
未决问题会向上汇总。任何深度上未解决的问题， 都会浮现在每个父节点的索引里。你可以从树顶看到是什么在阻塞发布， 而无需深入挖掘。
大多数规格工具假设扁平列表就够用了。确实够用——直到不够用为止。 SpecScore 正是为"这个 Feature 该放在哪里？"开始变得要紧的那一刻 而设计的。
specscore-cli/spec/features/cli/spec/features/cli/
├── agent/
│ └── setup/
├── feature/
│ ├── change-status/
│ ├── deps/
│ ├── info/
│ ├── list/
│ ├── new/
│ ├── refs/
│ └── tree/
├── idea/
│ ├── change-status/
│ ├── new/
│ └── relocate/
├── spec/
│ └── lint/
│ ├── issue-rules/ ← 子-子 Feature
│ └── plan-rules/
├── task/
│ ├── info/
│ ├── list/
│ └── new/
└── … 还有 10 个顶层 Feature没有它会出什么问题。
规格说明会漂移。
文档中的规格、Slack 里的讨论和 PR 中的代码悄悄地 分歧了好几周。没人能找到哪个版本的对话才是权威的。
解决方案
仓库中的唯一权威规格，与代码一起进行版本管理。
specscore lint在 CI 中每次推送时运行； git 历史就是审计追踪。规格、讨论和 PR 不可能悄悄 分歧——它们审查的是同一个文件。验收标准含混不清。
"优雅地处理错误"本来应该是指"显示提示并回滚"。还是"记录日志并重试？"AI 代理只能猜测。
解决方案
代码检查器在写任何代码之前就能捕获含混的标准。 动词无法通过检查，因为它缺少具体的对象或条件。 修复这个警告会迫使你写清楚"处理"到底 意味着什么。
AI 代理交付了错误的东西。
人类会推断、提问、澄清。AI 代理不会——它们实现的 是训练数据中最常见的模式。代码通过了审查，因为它做了某些合理的事情。只是不是你想要的。
解决方案
结构化输入。AI 代理确定性地解析 REQ ID、AC ID 和
GIVEN / WHEN / THEN场景——无需推断。Plan 必须引用每个任务满足的 AC ID， 所以构建的内容始终可以对照规格进行验证。含糊的规格,你要付两次钱。
代理根据含糊的指令做出了东西,你发现不对,于是换四种说法 重新提示。每个做了一半的功能、每一次重试,都按 token 计费。 规格越含糊,落地前来回的轮次就越多。
解决方案
在代理运行前先 lint 规格。
specscore lint在一开始就拒绝含糊的动词和缺失的验收标准,于是代理一次就 实现明确的指令,而不是在重试中反复猜测。最便宜的一次代理 运行,就是你不必重复的那一次。AI 代理反复付费读取规格。
AI 代理回答"什么依赖于这个功能？"时， 要读取整个功能 README。然后读每个父级索引。 然后以防万一再读兄弟功能。每次查询都是一次重新解析。 Token 在消耗；延迟在增加；费用也随之攀升。
解决方案
用结构化查询代替文件读取。
specscore feature tree以 YAML 格式返回层级结构；feature deps遍历传递性依赖链；feature info展示状态、负责人和待解决问题——每个只需 一次调用。代理导航的是图，而不是文本。代码忘记了它的规格。
六个月后，你在调试一个函数，没人记得它实现了哪个 功能。代码和规格之间的关联存在于某人的脑袋里， 而那个人已经离职了。引入它的 PR 已经存档。
解决方案
源码注解。类似
// specscore: features/checkout/apply-discount/R1.AC-2的注释使关联变得机器可读，并在每次重构中保留下来。specscore code deps一次调用即可回答"这个文件实现了哪个规格？"； 代码检查器会标记指向已删除规格的引用。状态变更会泄漏。
你把一个功能从 Draft 改为 Approved， 但父级的 features-index 仍然显示它是 Draft。三周后， 读取索引的 AI 代理认为它仍在变动中。状态现在存在于 两个地方，而且它们不一致。
解决方案
specscore feature change-status在一个 原子操作中重写功能的 Status 字段并重新同步 features-index 中的行——检查失败会回滚修改。状态存在于唯一的权威位置； 索引只是它的生成视图。规格忘记了它不知道的东西。
规格读起来像是已经定稿了——直到你想起两个月前在 Slack 讨论中丢失的"时区怎么办？"这个问题， 它从来没有进入文档。现在你们在实现阶段，没人能说出 答案是什么。
解决方案
每个 SpecScore 功能都有一个必填的Outstanding Questions 部分。代码检查器 会拒绝省略它的功能——留空可以 （
"None at this time."），但不能没有。 未解决的问题在文档中可见，可从 CLI 查询，不可能被遗忘。
最简单的入门方式：面向 AI 代理的 SpecStudio Skills。
SpecStudio Skills是一个 Claude Code 插件，它将 SpecScore 生命周期转化为四个斜杠命令。 安装一次，然后按顺序运行——从原始想法到可执行计划。
$ /plugin marketplace add specscore/ai-marketplace $ /plugin install specstudio@specscore
Claude Code自动补全
> /specstudio: /specstudio:ideate 将原始想法打磨为 SpecScore Idea /specstudio:specify 将已批准的 Idea 转化为 Feature 规格 /specstudio:plan 将 Feature 分解为有序任务的 Plan /specstudio:implement 执行 Plan 中的下一个任务
对公开和开源仓库免费。插件源代码在specscore/specstudio-skills——MIT 许可证。
分两遍检查你的规格。
先是快速的确定性代码检查器，再是更深入的 AI 审查 — 都在你刚才看到的规格上运行。两遍检查，两种确定性。
运行代码检查器。
deterministic$ specscore lint apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
每次运行结果都相同。免费、快速，可在每次提交时运行。
用 AI 审查并评分。
non-deterministic> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
像人类审查者一样按含义阅读。
包含什么。
代码检查器
Go 语言编写的 CLI。验证结构、引用和完整性。 失败时返回非零退出码——适用于你的终端和 CI。
无需绑定任何工具。
SpecScore 只是你仓库中的文件。无需注册任何 SaaS。无需编排器。 可以与 Linear、Jira、GitHub Projects、文件夹中的原始 Markdown 一起使用，或者完全不用任何项目管理工具。格式和代码检查器 不关心你的工单放在哪里。
SpecScore 与同类工具的比较。
规范驱动开发是一个拥挤的领域。这里坦诚地说明 SpecScore 相较于各种替代方案的定位。
更喜欢 CLI？
不使用 AI 代理，或者需要在 CI 流水线中验证规格？ 有一个 CLI 工具可以做到。60 秒完成安装——无需账户、无遥测， 适用于任何 Markdown 规格目录。
$ curl -fsSL https://specscore.md/install/get-cli | sh> irm https://specscore.md/install/get-cli.ps1 | iex对随二进制文件附带的示例规格运行代码检查器：
$ specscore lint examples/checkout/apply-discount.md查看输出：
examples/checkout/apply-discount.md
✓ R1 has acceptance criteria
✓ R2 has acceptance criteria
✗ R3 no acceptance criteria
✗ link "Related Feature: discount-tiers" not found
✗ section "Open Questions" missing
3 problems exit 1基于 SpecScore 构建。
Codegrapher
代码图引擎，用于快速代码探索以及规范与代码的双向关联。
codegrapher.devDALgo
使用 SpecScore 规范的 Go 数据访问层。
dal-go.github.ioinGitDB
使用 SpecScore 规范的基于 Git 的版本化数据库。
ingitdb.comRehearse
验收证据层——真实运行规范的验收标准，检查可复用，无需胶水代码。
rehearse.inkSpecScore Studio
用于查看和编辑 SpecScore 规格的 Web UI。
specscore.studio