文章

规格管理:把规格当作代码来存放、版本管理并审查

规格管理是团队存放一份软件规格、记录每一次变更、审查该变更,并让规格保持最新的方式。对规格的管理是同一项工作:规格是说明软件必须做什么的文档,管理它,是让这份文档仍然找得到、仍然可信。把规格当作代码来管理,是说这些文档是版本控制系统里的文件,因此规格的一次变更就是审阅者能够 diff 的一次提交。规格的版本管理,是这些提交的历史,加上写在每份文档上的状态。让规格与代码保持同步,是说一项破坏规格结构的提议变更,会在代码变更所经过的同一项自动检查上失败。规范驱动开发(SDD,spec-driven development)是在写代码之前写下规格,并把规格当作事实来源。持续集成(CI,continuous integration)是对每一项提议变更的自动检查。产品需求文档(PRD,product requirements document)是陈述问题和范围的散文。Markdown PRD 模板就是一份这种形态的 SpecScore 功能文件。Easy Approach to Requirements Syntax(EARS)是一条需求的句式。在 SpecScore 里,需求(REQ)是功能内部一条有名字的规则,验收标准(AC,acceptance criterion)是可选的抽象条件,指向其中一条或多条规则。这项检查是命令行界面(CLI,command-line interface)命令 specscore spec lint,记载于 在 CI 中用规格检查器检查规格。格式位于公开仓库 specscore/specscore(CC BY 4.0)。CLI 位于 specscore/specscore-cli(Apache-2.0)。

最近更新:2026年11月9日

规格存放在哪里

规格管理从文件能够存放的地方开始。在这个仓库里,规格是 spec/ 下的 Markdown。spec README 列出这些目录:features、plans、ideas、decisions、lessons。一个功能是带有一份 README.md 的目录。功能规格 是该文件的契约,PRD 模板 是检查器已经接受的一份填好的示例。

specscore spec lint 并不猜测要读哪一棵树。internal/cli/spec.go 在标签 v0.55.1,同一函数也在 标签 v0.39.1。该函数从工作目录向上走,直到找到 specscore.yaml。该函数上的注释说,命令要求这个文件,文件缺失时返回退出码 3,并让你运行 specscore init。本仓库的 dogfood 工作流 安装 CLI v0.39.1,然后运行 specscore spec lint,因此它所检查的那次检出里有这份配置文件。

功能文件旁边有一份索引。规则 feature-index-row-sync 在 v0.39.1 和 v0.55.1 的 lint 规则一览里是一条错误。规则一览的那一行说,它要求功能索引的每一行与其功能文件一致。这是索引与它所指向的文档保持对齐。它不是把需求的措辞和源文件做比较。

规格的版本管理

对已提交到 git 的文件来说,规格的版本管理就是这些文件的提交历史。SpecScore 不在功能上再加第二个版本号。审阅者所看的修订,是分支上的那次提交。文档上的状态行说明该功能处在生命周期的哪一处。这是和 git 哈希不同的另一件事实。

仓库里的 功能规格 自身就是 **Status:** Stable。它要求标题之后紧接着一行 **Status:**,值必须是 Draft、In Review、Approved、Implementing、Stable、Amending、Rejected 或 Deprecated 之一。规则 status-mirror 在上面点名的两份规则一览里,都要求带有状态的产物在 frontmatter 里的 status: 与正文那一行一致,并禁止在没有状态的类型上写 status:。让两份副本一致,并不等于拒绝八个值之外的词。两份规则一览的那一行都没有描述一条会拒绝该集合之外的功能状态的规则,所以本页不声称存在这样一条规则。

计划使用另一套值。规则 P-006 在两份规则一览里,都要求单文件计划正文的 **Status:** 是 Draft、In Review、Approved、Executing、Blocked、Implemented、Failed、Rejected、Withdrawn、Superseded 或 Deprecated 之一。规则 idea-status-values 拒绝该规则所允许的集合之外的想法状态。规则一览就是那份清单。本页不重述想法所用的词。

计划规格 还描述一张可选的 ## Snapshots 表,列是 Date、Git Hash、Action 和 Comment。它说,每条快照引用该计划在那一刻的状态的一个 git 提交哈希。为本页核对过的两份 lint 规则一览,都没有点名一条会解析该哈希的规则,所以本页不声称检查器会检查该提交是否存在。哈希是一个人可以在 git 里顺着走的指针。已发布的 计划规格 是该文档的格式页。

审查一份规格

审查一份 Markdown 规格,就是改变它的那次拉取请求。dogfood.yml 在 pull_request 上运行,也在向 main 的推送上运行。这个作业检出仓库,把 SPECSCORE_VERSION 设为 v0.39.1 来安装 CLI,然后不加额外标志运行 specscore spec lint。该进程以非零退出时,GitHub Actions 让这个步骤失败。工作流的权限是 contents: read。

功能状态 In Review 表示该功能被提交出来供审查。写下这个词,是对 Markdown 文件的一次编辑。拉取请求是人阅读 diff 的地方。status-mirror 检查 frontmatter 和正文是否写出同一个状态。它不记录审阅者是否同意那段散文。验证器页面 把那项结构检查,和人仍然要做的阅读分开。specscore spec lint 所报告内容的逐条规则说明,见 在 CI 中用规格检查器检查规格。

让规格与代码保持同步

在本站,让规格与代码保持同步,是说规格和项目放在同一个仓库里,并且当规格树违反格式时,CI 让拉取请求失败。一次拉取请求可以在同一个 diff 里同时改功能文件和代码。规则 feature-index-row-sync 让索引行与它所点名的功能文件保持对齐。它不读取源文件,也不判断代码是否实现了需求。

下面的摘录是 dogfood.yml 里的安装与检查步骤。工作流文件还设置权限、一个并发组,以及一条说明为何钉扎不是 latest 的注释。那些行在这里省略。命令就是该文件所运行的命令。

dogfood.yml 里的安装与检查步骤
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint

该文件里的注释说,浮动的 latest 钉扎会改变仓库之下的门禁:一次拉取请求,和它所指向的 main 分支,可能看到不同的规则。钉扎是 v0.39.1。这个作业不传入 --fix。一次干净的运行和一次失败的运行,包括 file:line [severity] rule: message 这一行,见 在 CI 中用规格检查器检查规格。

规格里一句不再描述代码的话,并不是那些发现之一。specscore spec lint 验证的是结构:必需的文件和节、索引行、标题的形状,以及规则所点名的引用。它不评判实现是否符合需求。这个限度就是 验证器页面 的要点。让散文保持为真,仍然是对 diff 的审查。

其他规范驱动的工具如何检查一份规格

下面几段使用 2026年11月9日获取的页面。它们描述那些工具自己的检查。它们不说存在多少产品,也不给市场排名。工具综述 是更长的比较。

GitHub Spec Kit 代理式 SDD 参考 把 /speckit.analyze 描述为横跨 spec.md、plan.md 和 tasks.md 的只读检查。它报告冲突、缺口和含糊之处,它从不编辑文件,并且你在实现之前于代理里运行它。同一页的命令列表没有描述一个 CI 作业,会针对 SpecScore 树运行 specscore spec lint。

OpenSpec 把一项变更存成 openspec/changes/ 正下方的一个目录。openspec validate 检查变更和规格的结构问题。该参考说,退出码 0 表示每一个被验证的项目都通过,退出码 1 表示某一项失败、报告请求无效、配置无法读取,或这次运行失败。那项检查是 OpenSpec 的形态,包括它的需求块和场景块,不是 SpecScore 的 ### AC: 标题。对另一个命令 openspec status,同一参考说,一个无法加载其中一项变更的批次仍然以 1 退出,“so CI doesn’t accept an incomplete report as successful.” 那句话是关于 openspec status 的,不是关于 openspec validate 的。

常见问题

什么是规格管理?

规格管理是存放一份软件规格、记录每一次变更、审查该变更,并让规格保持最新。在 SpecScore 里,文件是 git 仓库中的 Markdown,specscore spec lint 是一项结构检查,CI 作业可以因此失败。

什么是对规格的管理?

对规格的管理是同一项做法。规格是说明软件必须做什么的文档。管理它,是说这份文档有一个已知的位置、一段历史、一次审查,以及一项检查,确认它的结构仍然符合格式。

把规格当作代码来管理是怎样运作的?

规格是 spec/ 下一棵 Markdown 文件树,加上仓库根目录的 specscore.yaml。一次变更就是一次提交。拉取请求审查 diff。dogfood.yml 在那次拉取请求上运行 specscore spec lint。

规格的版本管理是怎样运作的?

git 历史就是这些文件的版本历史。功能还带有 **Status:**,取值是功能规格所要求的八个值之一。计划可以记录一行 ## Snapshots,其 Git Hash 是该计划状态的一次提交。这里引用的检查器规则一览,没有描述一条会解析该哈希的规则。

怎样让规格与代码保持同步?

把规格放进仓库,并在 specscore spec lint 报告结构违规时让拉取请求失败,包括与其功能文件不一致的索引行。这条命令不判断代码是否实现了需求。一句已经偏离代码的话,仍然需要人来读 diff。

把规格留在仓库里。

发现翻译问题或有改进此页面的想法?