claude-auto-dev

TDD 自動開發循環 for Claude Code。Claude 跑 Red-Green-Refactor，Stop Hook 用 quality-gate 驗證完成。

What it does

你: /auto-dev "實作用戶登入
              - JWT token 生成
              - Email + password 驗證
              - 錯誤訊息要友善"

Claude: [寫紅燈測試 → 實作 → 跑測試 → 重構 → touch .auto-dev/done]

Stop Hook 介入: 跑 build + test
  ✓ 通過 → 結束
  ✗ 失敗 → 把控制權還給 Claude，要求修正

整個過程沒有人工確認、沒有 AC 勾選比對。唯一的真相來源是 build/test 的 exit code。

Why

傳統 TDD agent 用「逐項勾選 acceptance criteria」當完成判斷。問題：

• AC 顆粒度由 LLM 自由詮釋，難以驗證
• Claude 跟 hook 同時寫 checkpoint 會 race
• 「checked = 完成」是 self-reported，不等於程式真的會跑

這個工具反過來：checkpoint 退化為純紀錄（給人看），完成判斷只看 quality-gate exit code。Hook 不寫狀態，Claude 用 signal file（.auto-dev/done）通知 hook 「我覺得做完了，你來驗」。

Install

Option A：Claude Code Plugin（推薦）

# 待提交到 marketplace 後
/plugin install claude-auto-dev

Option B：手動 CLI scaffold

npx claude-auto-dev init

init 會在當前 repo：

• 複製 hooks 到 .claude/hooks/
• 複製 skill 到 .claude/skills/auto-dev/
• 在 .claude/settings.json 註冊 Stop hook
• 寫入 .auto-dev/config.example.json 當作自訂 quality-gate 的範本

Usage

# 啟動
/auto-dev "你的任務 + acceptance criteria"

# 查看當前 session 狀態
npx claude-auto-dev status

# 中斷
npx claude-auto-dev abort     # 安全中斷（讓 hook 放行）

# 清理
npx claude-auto-dev clean     # 移除 .auto-dev/

# 健檢
npx claude-auto-dev doctor    # 確認 hook 有掛載、jq/python3 都裝了

Customize Quality Gate

預設只支援 Node（偵測 package.json + tsconfig.json → 跑 tsc + npm test）。 其他語言請建立 .auto-dev/config.json：

{
  "build": "cargo check",
  "test": "cargo test"
}

範本見 templates/config.json.example，已涵蓋 Python/Go/Rust/Deno。 任何回傳 exit code 的指令都行——Hook 只看 exit code，不解析輸出。

How it works (deeper dive)

Files

.auto-dev/
├── checkpoint.json     # Claude 自己維護，AC + status，純紀錄
├── config.json         # 可選，覆寫 build/test 指令
├── done                # signal file: Claude 宣告完成
└── stop                # signal file: 手動中斷

Stop Hook Flow

Claude Stop event
  ↓
.auto-dev/ 存在？─ no ──→ 放行
  ↓ yes
.auto-dev/stop 存在？─ yes ──→ 刪除 + 放行
  ↓ no
checkpoint.status == completed/aborted？─ yes ──→ 放行
  ↓ no
.auto-dev/done 存在？─ no ──→ block + 「請繼續或宣告完成」
  ↓ yes
跑 build + test
  ├─ 通過 ──→ 刪 done + 放行
  └─ 失敗 ──→ 刪 done + block + 報告失敗原因

Key Design Decisions

| Decision | Why | |----------|-----| | Signal file 而非 hook 寫 checkpoint | 消除 Claude/hook 同時寫 JSON 的 race condition | | quality-gate exit code 是完成判斷 | 「測試會跑」比「Claude 自己 check ✓」可靠 | | AC 勾選只是給人看 | Hook 不解析 AC，Claude 可以一輪做完多個 AC、自由詮釋顆粒度 | | Stop hook 而非 PreToolUse | TDD 的天然節奏是「Claude 講完一段話 → 驗收 → 繼續」 |

Requirements

• Claude Code CLI
• bash、python3（hook 用來 escape JSON）
• jq（可選，沒裝會 fallback grep）
• Node ≥ 18（CLI 用）

License

MIT