Spec Kit 教學網站

自動化與 CI 整合

在 CI 內檢查工具與檔案完整性，整合測試與型別檢查，合併前必須通過。

為何在 CI 驗證規格

規格（Spec）是專案的單一事實來源，描述了功能意圖、設計決策與驗收標準。然而，隨著開發推進，程式碼與規格往往悄悄脫節——開發者修改了實作邏輯卻忘記更新 spec.md，或者任務清單的狀態與實際合併情況不符。這種現象稱為「規格漂移（Spec Drift）」，是 SDD（規格驅動開發）最常見的品質風險。

規格漂移的代價：當規格與程式碼不同步，AI 代理人在下一個功能開發時會讀取過時的規格，導致產出錯誤的設計、重複解決已解決的問題，甚至引入與現有架構衝突的實作。CI 驗證規格是預防這種情況最低成本的方法。

將 specify check 納入 CI 流程，可以在任何人合併 Pull Request 之前，機械式地確認規格文件存在、格式正確、必要欄位齊全，並與任務清單保持一致。這樣即使在快速迭代的團隊中，規格也能持續作為可信的開發基礎。

specify check 在 CI 中的用法

specify check 是 Spec Kit 內建的環境與規格一致性檢查指令。在本機執行時，它會驗證工具鏈版本、必要目錄結構與規格文件格式。在 CI 環境中，建議搭配 --ci 旗標執行，以取得機器可讀的退出碼（exit code），讓 CI 管線能據此決定是否繼續執行後續步驟。 

# 基本檢查（適用本機與 CI）
specify check

# CI 模式：結構化輸出 + 非零退出碼代表失敗
specify check --ci

# 僅檢查特定功能的規格
specify check --feature feat/user-auth

# 輸出 JSON 報告供後續步驟解析
specify check --ci --output json > spec-report.json
注意：specify check 目前會驗證以下項目：.specify/ 目錄存在、spec.md 包含必要的 Frontmatter 欄位（feature、status、owner）、tasks.md 中每個任務的狀態值合法，以及 plan.md 的架構章節不為空。

GitHub Actions 完整 YAML 範例

以下是一個完整的 GitHub Actions 工作流程，將規格驗證作為第一道守門關卡，只有規格通過才會繼續執行測試與建置。 

# .github/workflows/spec-ci.yml
name: Spec Kit CI

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  spec-check:
    name: 規格一致性驗證
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 程式碼
        uses: actions/checkout@v4

      - name: 安裝 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 安裝依賴
        run: npm ci

      - name: 安裝 Spec Kit CLI
        run: npm install -g @spec-kit/cli

      - name: 執行規格檢查
        run: specify check --ci
        # 非零退出碼會自動讓此步驟失敗

      - name: 產出規格報告
        if: always()
        run: specify check --ci --output json > spec-report.json

      - name: 上傳規格報告
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: spec-report
          path: spec-report.json

  lint-and-test:
    name: Lint 與測試
    runs-on: ubuntu-latest
    needs: spec-check   # 必須等規格通過才執行
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
關鍵設計：needs: spec-check 確保只有在規格驗證通過後，耗時的測試才會啟動。這不僅節省 CI 資源，也強制要求開發者在提交前先整理好規格文件。

GitLab CI 範例

若團隊使用 GitLab CI/CD，以下是對應的 .gitlab-ci.yml 設定，同樣將規格檢查作為所有後續階段的前置條件： 

# .gitlab-ci.yml
stages:
  - spec
  - quality
  - test
  - build

variables:
  NODE_VERSION: "20"

.node-base:
  image: node:20-alpine
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

spec:check:
  stage: spec
  extends: .node-base
  script:
    - npm ci
    - npm install -g @spec-kit/cli
    - specify check --ci
  artifacts:
    when: always
    paths:
      - spec-report.json
    expire_in: 7 days
  rules:
    - if: $CI_MERGE_REQUEST_ID
    - if: $CI_COMMIT_BRANCH == "main"

quality:lint:
  stage: quality
  extends: .node-base
  needs: [spec:check]
  script:
    - npm ci
    - npm run lint
    - npm run typecheck

test:unit:
  stage: test
  extends: .node-base
  needs: [quality:lint]
  script:
    - npm ci
    - npm test -- --coverage --reporter=junit
  artifacts:
    reports:
      junit: test-results.xml
GitLab 特有功能：利用 needs: 關鍵字實現 DAG（有向無環圖）管線，讓規格驗證完成後立即觸發後續階段，而不必等待整個 spec 階段的所有工作完成，可縮短整體 CI 時間。

PR Gate：規格一致性作為合併條件

僅執行 CI 檢查還不夠——必須將規格驗證設為「必要狀態檢查（Required Status Check）」，才能真正防止規格漂移的程式碼進入主線分支。

團隊文化提示：技術守門只是第一步。建議在 PR 範本中加入明確的規格確認問題，例如「是否已更新對應的 spec.md？」「任務清單狀態是否與本次提交一致？」讓規格維護成為每個開發者的自然習慣，而非被動的 CI 阻擋。

自動化規格報告生成

除了驗證規格是否合規，還可以在 CI 中自動產出規格健康度報告，讓技術主管與 PM 一眼掌握各功能的開發進度與規格完整性。 

# 在 CI 中產出 HTML 格式的規格報告
specify report --format html --output ./reports/spec-health.html

# 產出所有功能的任務完成率摘要
specify report --summary --format markdown > SPEC_SUMMARY.md

# 偵測規格漂移並輸出差異清單
specify drift --since HEAD~10 --output drift-report.json

產出的報告可透過 GitHub Actions 的 actions/upload-artifact 或 GitLab 的 artifacts 保存，並在 PR 頁面提供可下載的連結。對於長期運行的專案，建議將報告部署至靜態網站（如 GitHub Pages），讓整個團隊隨時查閱。

規格漂移偵測與警告

規格漂移不一定在單一 PR 中發生，有時是多次小改動累積的結果。Spec Kit 提供漂移偵測機制，可在 CI 中定期執行或在每次 PR 時與基礎分支比對： 

# 與 main 分支比對，偵測規格與程式碼的差異
specify drift --base origin/main

# 偵測任務清單中已標記完成但對應程式碼未提交的項目
specify drift --check-tasks

# 設定漂移容忍閾值（超過 3 個不一致項目才視為失敗）
specify drift --threshold 3 --ci
定期掃描建議：除了在 PR 時觸發，建議設定每日排程工作（Cron Job）對主線分支執行 specify drift，並在偵測到漂移時透過 Slack 或 Email 通知技術負責人，做到早期預警而非事後補救。 
# GitHub Actions 每日排程漂移偵測
on:
  schedule:
    - cron: '0 9 * * 1-5'  # 週一至週五早上 9 點執行

jobs:
  drift-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需要完整歷史記錄
      - run: npm install -g @spec-kit/cli
      - name: 執行漂移偵測
        run: specify drift --ci --threshold 1
      - name: 發送 Slack 通知（僅在失敗時）
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: '{"text":"⚠️ 偵測到規格漂移，請立即檢查 spec-report"}'
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

團隊規格審查流程與 CI 配合

CI 自動化只能檢查格式與結構，無法評判規格內容的品質。完整的規格治理需要結合人工審查流程與自動化工具，形成互補機制。以下是建議的團隊規格審查標準流程：

最佳實踐總結：將 CI 規格驗證視為安全網，而非繁文縟節。當團隊真正將規格視為溝通工具而非文件負擔時，維護規格的成本遠低於解決規格漂移引發的溝通誤解與重工代價。從一個小功能開始，建立 CI 守門習慣，逐步推廣至整個專案。