/ 目錄 / 演練場 / pilot-shell
● 社群 maxritter ⚡ 即開即用

pilot-shell

作者 maxritter · maxritter/pilot-shell

Claude Code 搭配規格驅動流程和內建品質閘門——每項變更都要經過規劃 → 規格 → 實作 → 驗證才能落地。

pilot-shell 將 Claude Code 包裹在規格驅動迴圈中:功能從計畫開始,成為規格,對照驗收標準實作,並在所有閘門通過後才能發布(lint、類型、測試、文件)。它還持久化專案知識——不變量、決策、注意事項——讓品質得以跨對話維持。

為什麼要用

核心特性

即時演示

實際使用效果

就緒

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "pilot-shell-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "pilot-shell-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/maxritter/pilot-shell",
          "~/.claude/skills/pilot-shell"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add pilot-shell-skill -- git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: pilot-shell

以規格優先的紀律交付功能

👤 厭倦 AI 寫出半成品功能的開發者 ⏱ ~90 min intermediate

何時使用: PM 提出模糊的功能需求;你希望做對,而非做快。

前置條件
  • Skill 已安裝 — git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell
步驟
  1. 規劃
    Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ 已複製
    → 含明確未知點的計畫;你在進入下一步前填補空白
  2. 撰寫規格
    From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ 已複製
    → 規格已儲存至 /specs/<feature>.md
  3. 實作
    Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ 已複製
    → 測試 + 實作;未通過的測試在實作完成前可見
  4. 驗證閘門
    Run all gates: lint, type, tests, docs. Block PR if any red.✓ 已複製
    → 閘門報告;只有全綠才是合併候選

結果: 功能完整交付——有測試和文件。

注意事項
  • 規格階段拖延成規劃馬拉松 — 規格階段限時 30 分鐘;交付能鎖定驗收標準的最小規格即可
搭配使用: filesystem

不再開出在第一次 CI 就失敗的 PR

👤 PR 頻繁在 lint 和類型錯誤上被退回的開發者 ⏱ ~30 min intermediate

何時使用: 這週你開了 3 個 PR;全部在基本檢查上失敗。

步驟
  1. 設定閘門
    Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ 已複製
    → .pilot.config.json 含閘門清單
  2. 紅燈時封鎖
    Set policy: don't open PR until all gates green locally.✓ 已複製
    → 政策已套用
  3. 量測效果
    After 2 weeks, compare CI first-run pass rate before/after.✓ 已複製
    → 通過率提升

結果: PR 第一次就通過 CI;審查者的來回成本降低。

注意事項
  • 本機閘門與 CI 有細微差異(Node 版本不同) — 使用 .nvmrc 固定本機 Node 版本;完全鏡像 CI 的指令
搭配使用: github

在團隊壯大過程中保存專案知識

👤 正在交接或共享專案的負責人 ⏱ ~30 min beginner

何時使用: 你在移交或共享專案;希望決策和不變量有所記錄。

步驟
  1. 植入知識檔案
    Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ 已複製
    → /.pilot/knowledge.md 已建立,含各章節
  2. 隨時捕捉
    Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ 已複製
    → 決策持續累積;新協作者可閱讀歷史記錄
  3. 用於上手引導
    When a new collaborator starts, point Claude Code to this file as primary context.✓ 已複製
    → 更快速的上手;更少「為什麼要這樣做」的疑問

結果: 知識在團隊變動中得以傳承。

注意事項
  • 知識檔案變成瑣事日誌 — 保持簡潔:不變量、決策、注意事項。不是每日日誌

組合

與其他 MCP 搭配,撬動十倍槓桿

pilot-shell-skill + github

PR 範本自動從規格填寫;CI 驗證閘門符合

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ 已複製
pilot-shell-skill + filesystem

將規格和知識提交至儲存庫

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
plan feature_description 任何新功能的第一步 0
spec plan_id 計畫未知點解決後 0
implement spec_id 規格批准後 0
run_gates scope? PR 前;CI 鏡像 0
knowledge_update decision_or_invariant 捕捉專案層級的決策 0

成本與限制

運行它的成本

API 配額
無——本機
每次呼叫 Token 數
規格文件約 500–2000 token;知識檔案上限約 3000,以保持可管理
費用
免費
提示
將 knowledge.md 上限控制在約 3000 token;定期整合較舊的條目

安全

權限、密鑰、影響範圍

最小權限: filesystem-write
憑證儲存:
資料出站:

故障排查

常見錯誤與修復

閘門本機通過但 CI 失敗

固定 Node 版本、OS 相依套件;完全鏡像 CI 指令

驗證: 比對本機與 CI 指令輸出
實作步驟跳過了測試優先

在 .pilot.config 中設定 strict_tdd=true;工具會拒絕在測試之前撰寫實作

規格階段拖延

使用 --time-box 30m;強制對未知點做決策,而非追求完美規格

知識檔案過長

執行 knowledge_consolidate;將舊條目封存至 /.pilot/archive/

替代方案

pilot-shell 對比其他方案

替代方案何時用它替代權衡
spec-workflow-mcp你希望以 MCP 伺服器形式使用此功能,具有跨工具的觸達範圍設定較複雜;部署更靈活
純 CLAUDE.md + 手動 TDD個人專案,你不需要自動化依賴個人紀律;防護欄較少

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills