# 規格說明中的每一處歧義， 都是你的 AI 代理燒掉的 token。

Canonical: https://specscore.md/zh-tw/

SpecScore 是一種用於規格說明的開放、可 lint 的檔案格式，用 Markdown 和 YAML（YAML Ain't Markup Language）寫成，就像 JSON（JavaScript Object Notation）之於資料，並配有命令列介面（CLI），供你的 AI 代理呼叫以查詢和編輯它們，就像 `jq` 之於 JSON。

最後更新：2026年10月30日

然後是開發途中的一個澄清問題。然後是上線之後的一次修復。 然後是你一遍遍重新解釋的上下文。

 在 GitHub 上開源 取得 AI 技能外掛 安裝 CLI

## 為你已有的規格說明提供格式。

**SpecScore 是一種基於 Markdown + YAML 的格式**，用於描述功能、 需求和驗收標準。它定義了一種你的團隊和 AI 代理都能理解的結構——而它只是儲存庫中的檔案。

一個 SpecScore 專案包含三種生命週期產物：**Idea（構想）**捕捉一個半成形的方向；**Feature（功能）**凍結已達成共識的行為；**Plan（計畫）**將功能分解為循序任務， 每個任務引用它所滿足的驗收標準。

**為什麼你的 AI 代理在意。**因為結構是機器可讀的， AI 代理可以透過 CLI 查詢規格說明，而不必讀取每一個檔案。問一句*“我接下來該做什麼？”*，CLI 就會返回開放的 Feature 和尚未回答的問題。和你團隊審查的是同一份形態，但代理需要載入的 上下文要少得多。

 Feature → Requirements → Acceptance Criteria → Scenarios. 構想 → 功能 → 計畫 範例 ideas/apply-discount.md

```
# Idea: Discount codes at checkout **Status:** Approved **Date:** 2026-05-19 **Owner:** cart-team **Promotes To:** features/apply-discount ## Problem Statement How might we let returning customers redeem a single promo code at checkout without breaking the existing cart math or the site-wide promotion engine? ## Recommended Direction A registered user can apply **one** valid code per cart. Codes are time-bounded and replaceable. Stacking with site-wide promotions follows a deterministic tiebreak rule (higher discount wins; site-wide wins on tie).
```

 範例 features/checkout/apply-discount.md

```
--- status: approved owners: [cart-team] --- # Feature: Apply Discount A registered user can apply one valid discount code to their cart at checkout. ## Requirements ### R1 — Single-code limit - **AC-1** The cart accepts at most one discount code at a time. - **AC-2** Applying a second code replaces the first, with a visible confirmation. - **AC-3** Removing the code restores the original cart total. ### R2 — Code validity - **AC-1** A code is valid only if `valid_from` ≤ now ≤ `valid_until` . - **AC-2** Invalid codes show a specific error message. ### R3 — Discount application - **AC-1** Percentage discounts apply to subtotal, not shipping. - **AC-2** Discount totals round down to the nearest cent. - **AC-3** Stacking with site-wide promotions follows the higher-of rule. ## Scenario: Apply a valid percent-off code **GIVEN** a cart with subtotal $50.00 and shipping $10.00 **WHEN** the user applies code `SAVE20` (20% off) **THEN** the cart shows subtotal $40.00, shipping $10.00, total $50.00
```

 範例 plans/apply-discount/README.md

```
# Plan: Apply Discount **Status:** approved **Features:** - [apply-discount](../../features/apply-discount.md) **Author:** cart-team **Effort:** M **Impact:** high ## Context The apply-discount Feature is Approved. This plan breaks it into ordered tasks; each task cites the acceptance criteria it satisfies. ## Tasks ### T1 — Accept a `code` field on the cart Cites: R1.AC-1, R1.AC-2, R1.AC-3 ### T2 — Validate code time-window Cites: R2.AC-1, R2.AC-2 ### T3 — Apply percentage to subtotal, round down Cites: R3.AC-1, R3.AC-2 ### T4 — Higher-of tiebreak vs site-wide promo Cites: R3.AC-3 ### T5 — Confirmation toast on apply / replace Cites: R1.AC-2
```

## 規格說明是階層結構。所以你的規格樹也是。

當 Feature 數量達到五十個時，扁平列表就會變成一堆亂麻。 SpecScore 讓樹保持可導覽——父節點掌管範圍，子節點掌管細節， 目錄結構映射的正是你的團隊早已在頭腦中梳理的產品結構。

**未決問題會向上彙總。**任何深度上未解決的問題， 都會浮現在每個父節點的索引裡。你可以從樹頂看到是什麼在阻礙發布， 而無需深入挖掘。

大多數規格工具假設扁平列表就夠用了。確實夠用——直到不夠用為止。 SpecScore 正是為「這個 Feature 該放在哪裡？」開始變得要緊的那一刻 而設計的。

[在 specscore-cli 中即時檢視 →](https://specscore.studio/app/github.com/specscore/specscore-cli/spec/features/cli?op=explore)

 FROM 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](https://github.com/specscore/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 中的下一個任務
```

 /ideate → /specify → /plan → /implement Claude Code /ideate

```
> /ideate 讓我們想想結帳流程中購物車頁面應該怎麼設計。
```

 Claude Code /specify

```
> /specify 定義 spec/ideas/checkout-basket.md
```

 Claude Code /plan

```
> /plan 實現 spec/features/checkout/basket/README.md
```

 Claude Code /implement

```
> /implement 執行 spec/plans/checkout-basket/README.md
```

可免費用於任何用途，包括商業用途。外掛原始碼在[specscore/specstudio-skills](https://github.com/specscore/specstudio-skills)——MIT 授權條款。

## 分兩遍檢查你的規格。

先是快速的確定性程式碼檢查器，再是更深入的 AI 審查 — 都在你剛才看到的規格上執行。兩遍檢查，兩種確定性。

### 執行程式碼檢查器。

 deterministic

```
$ specscore spec lint features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds features/apply-discount/refunds:0 [error] readme-exists: README.md not found 3 violations found (3 errors) # exit code 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
```

像人類審查者一樣按含義閱讀。

## 它捕捉不到的，我們也照實說。

一個聲稱什麼都能查出來的程式碼檢查器是在說謊。SpecScore 是一個分層的系統 — 確定性的程式碼檢查器、AI 審查器，以及你自己的判斷 — 每一層都有真實的邊界。 我們把它們全都寫了下來：lint 能查到什麼、AI 能查到什麼，以及還有什麼只能靠你 — 因為目前還沒有工具能做到。

[程式碼檢查器查不到的東西 →](/zh-tw/validators/#limits)

## 包含什麼。

### 格式

Markdown + YAML。在任何能開啟文字的編輯器中使用。 無需新工具即可開始撰寫。

### 程式碼檢查器

Go 語言編寫的 CLI。驗證結構、引用和完整性。 失敗時返回非零結束代碼——適用於你的終端機和 CI。

## 無需綁定任何工具。

SpecScore 只是你儲存庫中的檔案。無需註冊任何 SaaS。無需編排器。 可以與 Linear、Jira、GitHub Projects、資料夾中的原始 Markdown 一起使用，或者完全不用任何專案管理工具。格式和程式碼檢查器 不關心你的工單放在哪裡。

## SpecScore 與同類工具的比較。

規範驅動開發是一個擁擠的領域。這裡坦誠地說明 SpecScore 相較於各種替代方案的定位。

 Plain Markdown 預設選擇。SpecScore 是你的 Markdown 進階後的樣子。 OpenSpec 一個可靠的入門通道。SpecScore 是品質護欄。 Spec Kit Spec Kit 是工作流程。SpecScore 是產物。 Datarim Datarim 執行管線。SpecScore 是它留下的成果。 CodeSpeak CodeSpeak 押注於編譯器。SpecScore 押注於格式。 Kiro Kiro 在 IDE 裡起草規格。SpecScore 是 CI 可以檢查的格式。 Tessl Tessl 主張規格即源頭。SpecScore 檢查放在程式碼旁邊的規格。 BMAD Method BMAD 跑敏捷循環。SpecScore 是拉取請求可以檢查的產物。 Task Master AI Task Master 把 PRD 拆成任務。SpecScore 是這些任務可以引用的規格。

[查看完整對比 →](/zh-tw/vs/)

## 更喜歡 CLI？

不使用 AI 代理，或者需要在 CI 管線中驗證規格？ 有一個 CLI 工具可以做到。60 秒完成安裝——無需帳號、無遙測， 適用於任何 Markdown 規格目錄。

 Linux / macOS Windows

```
$ 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
```

閱讀[完整文件](/docs/) · [在 GitHub 上貢獻](https://github.com/specscore/specscore)

## 基於 SpecScore 構建。

- ### DataTug 使用 DataTug 探索資料庫結構、撰寫並執行查詢，理解查詢結果。產品需求和驗收標準由 SpecScore 規範指導。 [datatug.app →](https://datatug.app)[了解這些開發工具 →](https://datatug.app/en/under-the-hood/tools-we-built/)
- ### MeaningGraph 資料模型與語意定義的開放註冊表，定義保存在你自己的 Git 儲存庫中，並與模型和程式碼關聯。 [meaninggraph.io →](https://meaninggraph.io/)[瀏覽註冊表 →](https://meaninggraph.io/registry/)
- ### Codegrapher 程式碼圖引擎，用於快速程式碼探索以及規範與程式碼的雙向關聯。 [codegrapher.dev →](https://codegrapher.dev/)
- ### DALgo 使用 SpecScore 規範的 Go 資料存取層。 [dal-go.github.io →](https://dal-go.github.io/)
- ### inGitDB 使用 SpecScore 規範的基於 Git 的版本化資料庫。 [ingitdb.com →](https://ingitdb.com/)
- ### Rehearse 驗收證據層——真實執行規範的驗收標準，檢查可重複使用，無需黏合程式碼。 [rehearse.ink →](https://rehearse.ink)
- ### SpecScore Studio 用於檢視和編輯 SpecScore 規格的 Web UI。 [specscore.studio →](https://specscore.studio)

## 還有疑問？

以下是大家最常問的問題。每條都連結到[FAQ 頁面](/zh-tw/faq/)的完整答案。

 SpecScore 和 spec-kit 有什麼區別？

spec-kit 是一種方法論；SpecScore 是你所寫規格說明的儲存格式， 外加一個 CLI。兩者可以組合——一個能輸出 SpecScore 的 spec-kit 擴充功能正在開發中。

 完整答案 → SpecStudio Skills 與 Superpowers、agent-skills 有何不同？

理念相近——三者都引導 AI 代理走完 ideate → specify → plan → implement。SpecStudio Skills 以 SpecScore 格式寫出 產物，並透過 `specscore` CLI 完成查詢和狀態變更； 另外兩者主要直接讀寫檔案。當 token 消耗很重要時，選 SpecStudio。

 完整答案 → 為什麼要 CLI——只裝技能不行嗎？

技能無法可靠地保證引用完整性，無法在不讀取所有檔案的情況下 返回篩選後的查詢結果，也無法在合適的時機更新正確的狀態欄位。 CLI 用一次呼叫就能完成每一項。技能要做同樣的事，得讀完每個檔案。

 完整答案 → 為什麼叫「SpecScore」——它在給什麼評分？

兩層含義，都是有意為之。Partitura（總譜）——一份結構化的 需求總譜。以及字面上的品質評分——CLI 檢查器給出確定性的分數，`/score` 技能則是 AI 評判的 A–F 就緒度評級。

 完整答案 → token 節省的數據在哪裡？

實測的並排對比正在準備，會在 Habr 文章前發布。從結構上看： CLI 返回一個小的結構化列表；而普通代理則要讀 N 份文件。

 完整答案 → SpecScore 使用什麼授權？

公開儲存庫 [specscore/specscore](https://github.com/specscore/specscore) 中的規範與文件是 [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)。[specscore/specscore-cli](https://github.com/specscore/specscore-cli) 中的參考命令列介面（CLI）是 [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)。

 完整答案 → SpecScore 是否綁定某一家 AI 工具？

不綁定。規格是儲存庫裡的純文字檔。CLI 是本機程式。本站的 AI Skills 為能執行技能的代理包裝這個 CLI。格式本身不要求單一供應商。

 完整答案 → 什麼是規格驅動開發（SDD）？

規格驅動開發（SDD）是在寫程式之前先寫出可檢驗的規格（需求與驗收標準），再對照該規格檢查結果。SpecScore 是承載這些規格的一種檔案格式。

 完整答案 →

## 定義成功，也為它留出時間。

SpecScore定義專案怎樣才算完成。每週承諾幫助你選擇下一步。用一次簡短的成果回顧把兩者連接起來。

 選擇下一個要完成的成果 → 認識CommittedMe（英文） →