規格圖：Specs are the ground truth · ThinkRail

定位

官網首頁兩句話把規格圖 (Spec Graph) 講透：

Specs are the ground truth.

…a connected graph of spec files lives beside the code, and the agent reads, searches, and maintains it with dedicated tools. Intent survives the session.

README 同義但更具體：

A connected graph of SPEC.md files lives beside the code; the agent reads, searches, and maintains it through dedicated spec_* tools, so intent survives the session.

spec_* 七工具

這組工具由 ThinkRail 自家的 pi-spec-graph 套件提供（packages/spec-graph/，以 pi 擴充形式註冊，不是 pi 引擎內建——pi 上游 node_modules 裡搜不到這些工具名）：

工具	作用
`spec_grep`	以 regex / 子字串搜規格檔內文，可用 type／tag／parent 等 metadata 過濾
`spec_get`	取單一規格節點：frontmatter、路徑與正反向連結
`spec_graph`	沿 parent／depends-on 等邊走一小片子圖（subtree／ancestors／neighbors）
`spec_create`	建立新的規格檔（含 frontmatter 腳手架）
`spec_update`	只改 frontmetadata，不動內文
`spec_delete`	刪除規格檔
`spec_validate`	檢查整張圖：dangling link、重複 id、parent cycle（原始描述：`report dangling parent/depends-on/references/implements links, duplicate ids, and parent cycles`）

子代理也吃這張圖——pi-subagents 的 SPEC_READ_TOOLS = ["spec_grep", "spec_get", "spec_graph"]：派出去的子代理同樣能讀規格。

介面裡的兩個入口

Specs 樹：工作台裡的唯讀 Specs 工具，renders the graph as a tree in the workbench。
spec-first 工作流：bundled workflow 之一（見技能與工作流），vibecoding 頁對流程的描述是——spec 先經你批准，Once approved, implementation follows that design…

ThinkRail 自己就是這樣開發的

README：

…a SPEC.md sits beside every module, and a change that moves a boundary, contract, or decision updates the spec in the same change.

官網首頁補一刀：this website is itself a module with a SPEC.md.——連官網都是圖上的一個節點。你以為的行銷頁面，其實是規格圖的吃自家狗糧示範。

跟其他 spec 系統的關係

TechSpecs 收錄的 OpenSpec 也是規格驅動開發工具——差異在：OpenSpec 是 CLI 變更管理流程（proposal → specs → design → tasks），ThinkRail 的規格圖是常駐 side-by-code 的知識層，由代理在對話中直接讀寫維護。兩者觀念同源（intent 要留下來），載體不同。

下一課

規格是知識、技能是手藝：Agent Skills 與 bundled workflows。