specrail

繁體中文 | English

以 PRD 為單一事實來源的規格驅動開發工作流，落地為 AI coding agent 通用的 skills / rules / agents / hooks——Claude Code 原生載入，Codex、Cursor 等其他 agent 依 AGENTS.md 導入。 適合 2–5 人小團隊（PM ＋ RD）從需求輸入一路走到驗收上線。

核心理念

• 雙事實來源：PRD 管 WHAT（.docs/prd/），技術設計文件管 HOW（.docs/tech-design/），互相引用、變更留痕
• DSL ➜ ISA 分層：驗收條件先以領域語言 Gherkin（DSL）定義行為；客戶確認流程後，才綁定成 API 層 Gherkin（ISA）介面契約，再串 OpenAPI 與自動化驗收測試
• 流程閘門：flow_locked 未鎖定前，hook 直接擋下 ISA/OpenAPI 撰寫——強制「先確認流程、再定稿設計」
• 契約優先：前端對 mock、後端對合約，並行開發不互等

十步流程總覽

1 需求輸入 ─ 2 需求整理 ─ 3 PRD（Story+DSL Gherkin）─ 4 可行性驗證 ─ 5 Wireframe
      └──────────────── 高頻迭代區（回寫 PRD、改 wireframe）────────────────┘
6 客戶確認 ⇒ flow_locked
7 技術設計定稿（DSL→ISA、OpenAPI）─ 8 契約優先開發 ─ 9 UAT 驗收 ─ 10 發布上線

前五步是高頻迭代區：需求輸入、PRD、可行性驗證、wireframe 來回打磨，改的都是文件與原型，成本低。 步驟 6 的 flow_locked 是分水嶺：鎖定前不寫任何 API 契約與程式碼；鎖定後才進入定稿與開發，變更成本開始變高，所以任何流程變更都要重新走鎖定。

逐步說明

步驟 1–2：需求輸入與整理（/intake）

• 輸入：任何形式的原始需求——訪談（訪談前可先產提綱）、會議記錄、合約、需求規格書、RFP
• 產出：.docs/intake/ 結構化需求紀錄（每條需求標注來源/定義者）＋ 待釐清問題清單
• 多來源衝突：列入待釐清由使用者裁決；暫定立場依「合約 ＞ 規格書 ＞ 會議/口頭」
• 此階段尚無 Feature，不進狀態機

步驟 3：Epic / Feature PRD（/prd）

• 輸入：.docs/intake/ 全部需求紀錄
• 產出：.docs/prd/epic.md（系統簡介、功能藍圖、NFR、範圍外）＋ 每個 Feature 一份 .docs/prd/f{NNN}-{slug}.md（User Story ＋ DSL 層 Gherkin 驗收條件）
• 紀律：DSL 層 Gherkin 只寫領域行為，不出現 API 路徑、HTTP 動詞、資料表、畫面元件
• 審查：自動派 spec-critic agent 挑模糊、矛盾、缺漏、不可測的 AC
• 狀態機：每個新 Feature 登記進 .docs/status.yml（flow_locked: false）
• 流程後段（可行性、客戶回饋、開發發現）要改需求時，一律回到這裡走回寫模式：只改受影響章節、記 Changelog、標記需同步的 ISA/測試

步驟 4：可行性驗證（/feasibility）

• 輸入：.docs/prd/
• 產出：.docs/tech-design/feasibility.md 可行性草圖——概念資料模型、整合點、技術風險、NFR 初判。草圖可丟棄，不是定稿設計
• 審查：派 rd-feasibility（RD 視角評估）與 spec-critic（規格視角複審）雙 agent；發現的規格瑕疵回寫 PRD
• 深度界線：只驗證「做不做得起來」，不預先設計 API 與 schema 細節

步驟 5：Wireframe（/wireframe）

• 輸入：Feature PRD 的流程與欄位定義
• 產出：wireframes/ 可部署的 HTML 原型——中性樣式（shadcn 風格），刻意不做視覺設計，讓客戶聚焦在流程、排版、欄位是否正確
• 交付後該 Feature 的 phase 推進到 flow-review（等客戶確認）

步驟 6：客戶確認閘門（/lock-flow）

• 輸入：客戶對 wireframe 的回饋
• 確認 OK → 該 Feature 在 status.yml 標記 flow_locked: true，解鎖 ISA/OpenAPI 撰寫
• 有問題 → 引導回寫 PRD 與 wireframe，重走步驟 4–6
• 鎖定後客戶又要改流程：用 /lock-flow 解鎖該 Feature（phase 同步退回 feasibility）、回步驟 4–6 重走，並在 PRD Changelog 記錄哪些 ISA／合約需要重審

步驟 7：技術設計定稿（/tech-design）

• 前提：該 Feature flow_locked: true（hook 強制）
• 產出：
  • .docs/tech-design/isa/f{NNN}-{slug}.feature——把每條 DSL 層 AC 綁定成 API 層 Gherkin（ISA 介面契約）
  • .docs/tech-design/openapi.yaml——全專案共用的 OpenAPI 合約，端點只能來自已鎖定 Feature 的 ISA
  • 定稿資料模型（tech-design.md）
• 審查：派 contract-reviewer agent 驗證 DSL ↔ ISA ↔ OpenAPI 三方一致、追蹤鏈（Feature ➜ Story ➜ AC ➜ ISA）完整

步驟 8：契約優先開發（/develop）

• 輸入：ISA ＋ OpenAPI 合約
• 產出：features/ 可執行的 cucumber 驗收測試（合約的可執行形式）＋ 實作
• 協作方式：前端依 OpenAPI 建 mock 切版串接、後端依合約實作，互不等待
• 衝突處理：
  • 實作與合約衝突 → 不准默默改合約遷就實作；回 /tech-design 修訂、過 contract-reviewer、記 Changelog、前後端同步知情
  • 發現規格本身有錯（WHAT 錯了）→ 回寫 PRD（/prd 回寫模式），不讓程式行為偏離 PRD

步驟 9：驗收（/uat）

• 輸入：全部自動化驗收測試 ＋ PRD 的 Gherkin AC
• 兩段式硬性順序：先內部驗證（跑全回歸——全部 features/，不只受驗 Feature——＋內部檢核，記進報告），全過才交客戶驗收（staging，版本與內部驗過一致）
• 產出：.docs/uat/ 驗收報告，逐條核對 AC——與步驟 3 的驗收條件形成閉環
• 測試結果照實呈報：失敗就是失敗，附輸出；退回開發走 /develop 修復模式（先寫紅的回歸測試重現，再修）
• 通過後 phase 推進 release，等待發布

步驟 10：發布上線（/release）

• 前提：內部驗證＋客戶驗收皆通過（phase release）
• 發布：依 release-checklist 逐項核對——全回歸綠、migration 前向相容（expand-contract）、rollback 計畫部署前預寫、staging 同版本驗證過——缺一項不部署；部署後跑 smoke，通過才標 done＋released: v{X}＋deployed: true
• 回滾模式：線上事故依預寫計畫回退（資料庫不回退——前向相容保證舊版程式可跑新 schema），deployed: false 留痕，再依根因分流修復（實作 bug → /develop 修復模式；合約錯 → /tech-design 修訂模式；需求錯 → /prd 回寫），修好重走 /release 形成閉環
• 產出：.docs/release/ 發布紀錄（含 rollback 計畫與 smoke 結果）

狀態機與閘門

.docs/status.yml 是流程狀態機，以 Feature 為單位追蹤——F-001 可以在 develop、F-002 還在 feasibility，互不阻擋：

features:
  F-001:
    slug: course-progress
    phase: done           # feasibility | wireframe | flow-review | tech-design | develop | uat | release | done
    flow_locked: true
    released: v1.3.0      # 選填，只由 /release 寫入
    deployed: true        # 選填，回滾時改 false（phase 維持 done）

phase 的語意是「下一個要執行的階段」，轉換表（誰在什麼時機推進／回滾）與各 skill 的 entry-check 規則見 .agents/rules/workflow-status.md。

• status.yml 只透過 skills 更新，不手動修改
• ISA 閘門（per-Feature）：hook 依 ISA 檔名的 f{NNN}- 前綴判斷歸屬，該 Feature 未鎖定就擋下，已鎖定的其他 Feature 不受影響
• OpenAPI 閘門（全專案）：至少一個 Feature 鎖定後才可撰寫；端點層級的歸屬由 contract-reviewer 把關

追蹤鏈

需求到測試雙向可追，任何一環斷鏈都是缺陷：

需求（intake 紀錄 #N）➜ Feature（F-001）➜ User Story（US-001）➜ AC（AC-F001-001-1，DSL Gherkin）
  ➜ ISA（f001-{slug}.feature 內同編號 scenario）➜ 自動化測試（features/）

編號規則與完整性檢查清單見 .agents/rules/traceability.md。

安裝與使用

方式一：npm CLI（建議）

npm install -g specrail
cd your-project
specrail init        # 導入整套工作流（skills/rules/hooks/assets）

或免安裝：npx specrail init。日後升級：npm update -g specrail && specrail update（update 只更新工作流資產，不動你的 PRD、狀態與文件；會覆蓋你對工作流資產本身的客製，覆蓋前自動備份到 .specrail-backup/）。

移除工具：全域安裝的用 npm uninstall -g specrail；裝進專案的（npm install -D specrail）用 npm uninstall specrail；只用過 npx 的不需要移除——npx 不會在機器上安裝任何東西，只留下可有可無的下載快取。移除工具不影響已 scaffold 進專案的內容（.agents/、.docs/、AGENTS.md 等照常保留、照常運作——工作流資產本來就不依賴 CLI，CLI 只負責導入與更新）。

方式二：Clone 範本

Clone 本 repo 作為新專案起點（或把 .claude/ 與 .agents/ 複製進既有專案）。

導入後依階段執行——Claude Code 用以下 slash 指令；其他 agent 依 AGENTS.md 的對照表讀取各階段 SKILL.md 照做，效果相同：

/intake      # 訪談/會議記錄/合約/規格書 → 結構化需求紀錄
/prd         # Epic + Feature PRD，spec-critic 自動審查
/feasibility # rd-feasibility 評估可行性，產出可丟棄的草圖
/wireframe   # HTML 原型（中性樣式），部署給客戶看流程
/lock-flow   # 記錄客戶確認 → 解鎖技術設計
/tech-design # DSL→ISA 綁定 + OpenAPI，contract-reviewer 驗一致性
/develop     # cucumber 驗收測試 scaffold + 契約優先開發
/uat         # 兩段式驗收：內部驗證 → 客戶驗收（staging），產出報告
/release     # 發布上線：checklist + smoke 驗證；含回滾模式

組成

所有工作流資產的本體集中在 .agents/（跨工具共用）；.claude/ 內是 symlink，供 Claude Code 原生機制載入。

| 類型 | 本體位置 | 內容 | |---|---|---| | Skills ×9 | .agents/skills/ | 每個流程階段一個指令，內建該階段的紀律與產出規範 | | Agents ×3 | .agents/agents/ | spec-critic（挑規格瑕疵）、rd-feasibility（可行性評估）、contract-reviewer（契約一致性） | | Hooks ×3 | .agents/hooks/ | 流程閘門（未鎖定擋 ISA/OpenAPI）、Bash 寫入閘門（防 shell 繞過）、.docs/index.md 同步提醒 | | Rules ×5 | .agents/rules/ | 2 個全域載入、3 個依編輯路徑觸發（paths frontmatter） | | Templates ×9 | 各 skill 的 .agents/skills/{name}/assets/ | 訪談紀錄、文件解析紀錄、Epic PRD、Feature PRD、詞彙表、可行性草圖、技術設計、UAT 報告、發布檢查清單 | | AGENTS.md | 專案根目錄 | Codex 等其他 AI 工具的入口：流程總覽 + 資產讀取指引 |

需求

• 任一 AI coding agent——Claude Code 原生支援（skills / rules / hooks 自動載入）；Codex、Cursor 等其他工具依 AGENTS.md 指引使用
• bash + python3（hooks 使用，僅 Claude Code 強制執行；其他工具以 AGENTS.md 的文字約定為準）
• Node.js ≥ 18（僅安裝 CLI 需要）

License

MIT