runesleo/claude-code-workflow

QuietHarness – AI 程式碼代理的輕量級可靠性層

是什麼

• 一組小型、可攜帶的設定檔與指令碼，為 Claude Code、Codex 或 Cursor 等 AI 程式碼助手添加安全檢查。
• 核心部分（1 604 位元組）定義了「工作邊界」：偵測不相關變更、執行測試、在執行不可逆操作（例如憑證變更、部署）前要求確認，並保留可驗證的稽核紀錄。
• 可與三種支援的代理中的任一種搭配使用；你只需安裝與你使用的客戶端相符的部分。

為何需要它

• 防止代理覆寫其未檢視的檔案。
• 阻止代理在未實際執行專案測試套件的情況下聲稱任務已完成。
• 確保在任何實際變更寫入檔案系統前都有預覽（dry-run）。
• 提供代理設定檔的自動備份／回復，可安全恢復至先前狀態。

組織結構

資料夾	目的
templates/	三個最小設定套件（共享核心、Claude 适配器、Cursor 规則、Codex 适配器）。
scripts/	輔助指令碼：清單、安裝（預覽與套用）、驗證、遷移。
examples/first-success/	分步隔離示範，展示代理成功「首次執行」的過程。
examples/leo-system/	作者真實任務系統的淨化快照（JSON 範例、文件）。
docs/	架構、任務連續性、會話結束處理、日報處理等。
tests/	在暫時 HOME 目錄中執行安裝器的煙霧測試。
media/	圖表與發布圖形。

典型工作流程

1. 克隆 倉儲並執行 ./scripts/inventory.sh 以查看將被觸及的項目。
2. 建立一個隔離的示範目錄（mktemp …）。
3. 以 預覽模式 執行你客戶端的安裝器，例如：

   ./scripts/install.sh --dry-run --claude-project "$demo_dir"
   

4. 審查預覽後，使用 --apply 套用。
5. 在 $demo_dir 中開啟所選代理，並給予簡單指令，如 Read TASK.md and complete the task.。
6. 代理應執行所需變更、執行現有測試，並返回成功的明確證據，無需額外提示。
7. 若一切正常，重複安裝步驟但不帶 --project 標誌，以全域安裝核心（寫入 ~/AGENTS.md、~/.claude/CLAUDE.md 等）。備份會自動建立（.bak-ai-workflow-*）。

關鍵安全機制

• 預覽模式 – 除非明確傳遞 --apply，否則不會寫入任何檔案。
• 備份與回復 – 原始設定檔會依時間戳保存；安裝器可自動恢復它們。
• 風險門控操作 – 任何潛在破壞性操作（憑證變更、生產部署、發布）都需要代理的明確確認步驟。
• 隔離 – 示範完全在暫時目錄內執行；安裝器從不連接網路或修改你的帳戶設定。

適合對象

• 已依賴 Claude Code、Codex 或 Cursor 進行程式碼生成，希望設置防護機制以避免意外覆寫或未經測試的提交的開發者。
• 在這些代理之間切換的團隊，需要一種可在不同工具間遷移的一致安全政策，無需重寫規則。
• 尋找可重現的「首次成功」入門測試，以驗證其 AI 助手在自身程式碼庫中行為可靠的任何人。

限制

• 它 不提供 任務資料庫、排程器或團隊級編排平台——這些需另行建構。
• 僅支援類 Unix shell；目前尚無 Windows 的 PowerShell 安裝器。
• 核心規則是靜態文字檔；擴展需手動編輯或建構自己的範本。
• 系統假設你已在本機安裝並設定相應的 AI 代理客戶端。

安裝與驗證

# 克隆並檢查
git clone https://github.com/runesleo/claude-code-workflow.git
cd claude-code-workflow
./scripts/verify.sh   # 執行煙霧測試，檢查備份、範本大小等

驗證後，遵循上述示範步驟，或執行全域安裝：

# Claude Code（使用者層級）
./scripts/install.sh --dry-run --claude
./scripts/install.sh --apply --claude

Codex（--codex）和 Cursor（--cursor）也有類似命令。

授權

• MIT 授權（參見 LICENSE）。

---

QuietHarness 本質上是一個 設定即程式碼 的套件，使 AI 程式碼助手的行為更可預測且安全，無需任何網路呼叫或專有 API。它是 LLM 基礎程式碼助手開發者真正可重用的工具。