maxritter/pilot-shell

How real engineers run Claude Code and Codex: spec-driven planning, enforced TDD, persistent memory, and quality enforcement on all levels. Make your agents production-ready.

Pilot Shell – 為 Claude Code 與 Codex 增強的 AI 指令列工具

是什麼 – 一個輕量級的 Shell/CLI，位於 Anthropic 的 Claude Code（主）或 OpenAI 的 Codex 之上，新增結構化、測試驅動的開發工作流程。它將原始的程式碼生成提示轉化為可重複、經過品質檢查的流程，涵蓋需求收集、規格制定、實作、缺陷修復與自主建置。

為何存在 – Claude Code 與 Codex 能快速撰寫程式碼，但缺乏框架時會：

  • 跳過測試與 linting，
  • 會話間遺失上下文，
  • 產生不一致的結果。 Pilot Shell 注入 規格驅動 與 目標驅動 的流程、品質門檻以及持久的「記憶」，使 AI 行為更像一位有紀律的工程團隊成員。

核心概念與指令

指令 使用時機 功能
/prd 你有一個模糊的想法或問題陳述時。 進行腦力激盪，可選地進行網路調查，並產生一份產品需求文件（PRD），儲存在 docs/prd/ 下。
/spec 你有一個明確的功能或 bug 要處理時。 引導 AI 完成 規劃 → 審核 → 實作（TDD）→ 驗證 → 完成 流程，自動執行 lint/format/type 檢查，並支援可選的協作式規格審查。
/build 你想在沒有完整規格的情況下達成具體目標時。 產生簡短的任務清單 + 接受標準，然後迭代建置、評估並優化，直到標準通過。
/fix 你需要一個符合測試驅動流程的 bug 修復時。 執行聚焦的 TDD 循環；若修復過於複雜則中止。
pilot（管理員別名） 管理安裝、更新與設定。 安裝/卸載執行時，激活授權，切換模型等。

主要功能

  • 品質鈎子 – 每次編輯都會自動強制執行 linting、格式化、類型檢查與測試執行。
  • 上下文工程與記憶共享 – 決策、規則與「記憶」會持久化儲存在 ~/.pilot/，並可透過專案倉儲共享。
  • 語意搜尋（Semble）+ 程式碼知識圖譜（CodeGraph） – 快速準確的程式碼庫查找，減少 token 使用量。
  • 令牌最佳化 – 透過 RTK 壓縮與 Semble 搜尋，實現 60–90% 的成本降低。
  • Pilot Bot – 持久的後台代理，可執行定時任務或長時間執行的任務。
  • 擴充功能 – 可重用的規則、技能與 MCP（訊息-控制-協定）伺服器，團隊可共享。
  • 控制台 – 本地 Web 仪表板，即時顯示通知、會話日誌與目前需求/規格。

安裝（快速入門）

# 一行命令適用於 macOS、Linux 與 Windows（WSL2）
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

安裝程式：

  1. 檢查 Homebrew、Node、Python 3.12+、git、jq 是否存在。
  2. 檢測支援的 AI 代理（Claude Code 或 Codex）——你必須事先安裝其中之一。
  3. 將 Pilot 資產部署至 ~/.pilot/ 並安裝代理專用適配器。
  4. 安裝支援工具（Semble、RTK、CodeGraph、Playwright、Chrome-DevTools MCP、語言伺服器等）。
  5. 為 bash、fish 與 zsh 加入 shell 別名（pilot、claude/codex 包裝器）。

要卸載但保留資料：

curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash

加入 --purge-data 以刪除 ~/.pilot/。

先決條件

  • Claude Code – 原生安裝程式（需要 Anthropic 訂閱）或
  • Codex CLI / ChatGPT 桌面版（需要 OpenAI 訂閱）。
  • 現代終端（推薦 Zentty，但 iTerm2、Ghostty 等也可用）。

典型工作流程範例

# 啟動 Claude Code（或 Codex）
claude                     # 或：codex

# 1️⃣ 建立 PRD
> /prd "為團隊更新新增即時通知"

# 2️⃣ 轉換為規格並實作
> /spec "為團隊更新新增即時通知"
# – Pilot 將引導你完成規劃、撰寫端對端測試、使用 TDD 實作、驗證並合併。

# 3️⃣ 後續需要快速修復時
> /fix "頁面重新整理後通知停止"

所有步驟皆被記錄，生成的規格、規則與記憶將儲存在倉儲中以供未來重用。

哪些人可能受惠？

  • 已使用 Claude Code 或 Codex 但希望獲得有紀律、可重複工作流程的軟體工程師。
  • 需要共享規格、品質門檻，並在團隊成員間持久化 AI 生成知識的團隊。
  • 希望在降低 token 成本的同時保持 AI 輔助安全且測試驅動的獨立開發者。

連結

相關

  • 專案
    sangrokjung/claude-forge

    A professional equipment pack for Claude Code that adds specialist agents, safety hooks, and automated workflows to transform the terminal AI into a full-scale development kit.

  • 專案
    wesammustafa/Claude-Code-Everything-You-Need-to-Know

    一份詳盡、範例豐富的 Anthropic Claude Code CLI 教學，涵蓋安裝、提示工程以及進階擴展（Skills、Hooks、Sub-agents、Workflows、MCP），協助開發者使用 Claude 實現專案級程式碼分析、編輯、測試與自動化。

  • 專案
    fengshao1227/ccg-workflow

    一個為 Claude Code 建立的工作流引擎，將其轉變為多模型編排器，將複雜軟體開發中的專業任務委派給其他 LLM。

  • Dispatch
    精通 Claude Code：從提示到可程式化工程

    深入探討如何將 Claude Code 從簡單的聊天機器人轉變為使用自訂技能、子代理人與模型上下文協議的複雜自主代理。

  • 專案
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent 是一個開源框架，為 Anthropic 的 Claude Code 專案賦予專案感知能力與專家代理功能。它使用 Python Hook 系統與本地執行的 Ollama 模型，自動偵測程式碼庫類型，分析使用者意圖，載入 300 多個領域專用的「技能」（後端、前端、測試、安全等），並強制執行自動文件（DEVELOPMENT.md、KNOWLEDGE.md、CHANGELOG.md）。克隆倉儲，安裝 Ollama、模型與 uv 後，將專案放入倉儲，Claude Code 即可立即了解其上下文，建議合適工具，並可透過 `/backend‑specialist` 或 `/kiro/spec` 等斜線命令驅動。 關鍵點： - 零設定啟動；所有設定皆位於 `.claude/settings.json` 與 `prompts.json`。 - Hooks 在會話啟動、使用者提示、工具使用等時執行，處理專案偵測、意圖分析與文件更新。 - Skills 由 `SKILL.md` 檔案定義，可自動發現。 - 完全本地運行（無外部 API），與 Git 整合，MIT 許可。 適合希望獲得可重現、本地部署 AI 編碼助手的開發者或小團隊。