規格管理:把規格當作程式碼來存放、版本管理並審查
規格管理是團隊存放一份軟體規格、記錄每一次變更、審查該變更,並讓規格保持最新的方式。對規格的管理是同一項工作:規格是說明軟體必須做什麼的文件,管理它,是讓這份文件仍然找得到、仍然可信。把規格當作程式碼來管理,是說這些文件是版本控制系統裡的檔案,因此規格的一次變更就是審閱者能夠 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 的註解。那些行在這裡省略。命令就是該檔案所執行的命令。
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。
來源
CLI 檔案和 lint 規則一覽於 2026年11月9日讀取,對應 specscore-cli 標籤 v0.39.1(dogfood.yml 所安裝的版本)和 v0.55.1。功能和計畫的需求,是下面連結的 specscore/specscore 裡的檔案。競品頁面於同一天取得。
- specscore/specscore — spec/README.md
- specscore/specscore — 功能狀態值
- specscore/specscore — 計畫快照
- specscore/specscore
- specscore/specscore — CC BY 4.0 授權
- specscore/specscore-cli
- specscore-cli — Apache-2.0 授權
- specscore-cli v0.39.1 — internal/cli/spec.go
- specscore-cli v0.55.1 — internal/cli/spec.go
- specscore-cli v0.39.1 — lint 規則一覽
- specscore-cli v0.55.1 — lint 規則一覽
- specscore/specscore — dogfood.yml(CLI v0.39.1)
- SpecScore 驗證什麼
- 在 CI 中用規格檢查器檢查規格
- EARS 需求語法詳解與範例
- 寫出 AI 代理驗得過的驗收標準
- 給 AI 寫程式用的 Markdown PRD 範本
- 功能規範
- 計畫規範
- GitHub Spec Kit — 代理式 SDD 參考(/speckit.analyze)
- OpenSpec CLI 參考 — openspec validate 與 openspec status
- Fission-AI/OpenSpec
- 規範驅動開發工具