コーディングエージェントの夜間ワークフロー

新しい外部の協力者に頼むようにタスクを書く

夜間のタスクには、質問できる相手がいません。必要な背景はタスク自体に含める必要があります。各タスクは1段落に収め、3つの問いに答えるようにします。何が間違っているか、何が足りないか。完了とはどういう状態か。それをどう証明するか。

## Task: paginate the /orders endpoint
Problem: GET /orders returns every order. Large accounts time out.
Done: accepts ?cursor and ?limit (max 100), returns next_cursor.
Proof: new tests in tests/orders_pagination.test.ts pass; existing tests pass.
Do not: change the response shape of existing fields.

タスクは小さくします。人の作業で2〜4時間分がちょうどよい大きさです。それより大きければ分割します。エージェントが20分で終えるタスクでもかまいません。タスクは、リポジトリ内のファイルか、エージェントが読めるissueに書きます。ファイルがいちばん簡単です。

1タスク、1ブランチ、1 worktree

タスク同士で作業ツリーを共有してはいけません。2つのタスクが同じチェックアウトを編集すると、誰も解きほぐせない差分ができます。Gitのworktreeを使えば、同じリポジトリでタスクごとに専用のフォルダを持てます。

git worktree add ../work/orders-pagination -b agent/orders-pagination
git worktree add ../work/retry-webhooks -b agent/retry-webhooks

ブランチごとにエージェントを1回実行し、プルリクエストを1つ作ります。朝はそれを1つずつレビューします。1つが駄目でも、それを閉じるだけで、ほかには影響しません。

エージェントが単独でしてよいことを決める

権限モードと拒否リストは、最初の実行のあとではなく、前に設定します。正確な設定はClaude Codeを無人で動かすガイドにあります。夜間作業向けに短くまとめると、こうなります。ファイルは自由に編集してよい。テストスイートは自由に実行してよい。タスクのブランチへのコミットとプッシュも自由にしてよい。プルリクエストを作成する。それ以外は確認が必要で、リポジトリの外に及ぶことは一切しない。

実行ループ

小さなスクリプトで、タスクごとにヘッドレス実行を1回ずつ始めます。実行はそのタスクのworktreeで行い、ターン数の上限とログファイルを付けます。必要なのはこれだけです。

#!/bin/sh
# run-overnight.sh: one agent run per task file in tasks/
for task in tasks/*.md; do
  name=$(basename "$task" .md)
  dir="../work/$name"
  git worktree add "$dir" -b "agent/$name" 2>/dev/null
  (
    cd "$dir" || exit 1
    claude -p "Complete the task in $task. Commit on this branch, push it, and open a pull request with gh pr create. Stop when the tests pass or when you are blocked, and say which." \
      --permission-mode acceptEdits \
      --max-turns 80 \
      > "../logs/$name.log" 2>&1
  )
done

SSH接続に左右されないよう、tmuxの中で実行します。タスクは1つずつ順に動きます。並列実行もできますが、CPUとレート制限を奪い合い、ログも読みにくくなります。まずは順番に実行してください。

判定はテストに任せる

プロンプトでは、テストが通ったら止まるようエージェントに指示しています。その後、CIがプルリクエストで同じテストを実行します。エージェントが成功したと言っても、CIが失敗を示していれば、差分を1行も読む前に分かります。mainを保護し、このチェックなしでは何もマージされないようにします。これはこのワークフローでいちばん価値のあるガードレールで、しかも費用はかかりません。

朝のレビューは10分

• プルリクエストの一覧を開き、タスクリストと数を照らし合わせます。足りないものの理由はログにあります。
• ブロックされて止まったもののログを読みます。たいていは認証情報の不足か、曖昧なタスクです。直すのはエージェントではなく、タスクの文章です。
• 成功したプルリクエストを、小さいものから順にレビューします。正しいものはマージします。間違っているものは理由を1行書いて閉じ、その1行を明日のタスクファイルにコピーします。
• マージ済みのworktreeとブランチを削除し、今夜をきれいな状態で始められるようにします。

git worktree remove ../work/orders-pagination
git branch -d agent/orders-pagination

最初に任せる作業

夜間に向いている作業と、そうでない作業があります。まずは次のものから始め、信頼が積み重なるにつれて範囲を広げてください。

• 期待する動作がはっきりしている、失敗するテストや不安定なテスト。
• テストスイートで判定できる依存関係のアップグレード。
• 多数のファイルにまたがる機械的なリファクタリング。
• すでに動いているコードへの、不足しているテストの追加。
• 型エラー、lintエラー、非推奨の警告。

設計の判断、課金や認証に関わるもの、テストで検証できないものは、日中に回します。日中なら質問に答えられるからです。

土台となるマシン

これはすべて、午前4時にもマシンが動いていることが前提です。夜間実行が何も生まない原因として最も多いのは、ノートPCのスリープです。ご自身のMacならスリープのガイドで解決できます。ホスト型のエージェント用Macなら、最初から解決済みです。