Claude Codeをヘッドレスで回す設計

このハーネスは、エンジニアが最後に挙げる少数のルールに支えられている。すべてを1回の実行に任せないこと、工程を分割し各工程の権限を最小限にすること、文脈が要る修正は同じセッションで、独立した判断は別セッション・別モデルで行うこと、AIの判定は散文を解析せず固定形式に強制すること、打ち切りは理由ごとに分類しAIの責任でない失敗でリトライを消費しないこと、状態をプロセスの外に置きどこで止まっても再開できるようにすること、の5点だ。

いくつかの設計判断は具体的な事故から生まれている。AIにpush、マージ、ブランチ切り替えを禁じているのは、リモートが先行した状態でpushに何度も失敗したためだ。設計の実行は読み取り専用、レビューはRead、Grep、Globに限定している。自ら修正するレビュアーは何を指摘したかの記録を残さないという理由からだ。設計はあえて必須ゲートにしていない。設計の出力が空でもタスクは失敗せず、止まった補助工程が本作業を止められないようにしている。

復旧は最重要課題として扱われている。再開点は実装後、レビュー承認後、マージ直前に記録され、中断しても最初からやり直さずに済む。各起動時には、プルリクエストを持つ未完了タスクを実際のGitHubの状態と突き合わせ、マージ済みのものは完了として扱い、同じタスクを二重に実装しないようにする。完了したタスクのうち217件は初回実行で、22件は再実行で完了した。