自動で動くClaudeワークフローの構築方法

エージェントコーディングの目指す方向を要約する言葉が広まっています。その目標は、より良いプロンプトではなく、ユーザーが見守ることなく実行されるワークフローです。ほとんどの人は、チャットウィンドウを使うのと同じようにClaudeを使っています。入力し、待ち、読み、再び入力する。これは機能しますが、あなたが積極的に監視しているエージェント1つに成果が限定されます。Claudeから真のレバレッジを引き出しているエンジニアたちは、別のものを構築しました。それは、スケジュールやトリガーで開始され、作業を行い、自身の結果をチェックし、意思決定が必要な場合にのみ人間に通知するワークフローです。

ボタン

要するに

ユーザーなしで実行されるClaudeワークフローには5つの要素が必要です。精密な書面による仕様、ヘッドレス（非対話型）実行、合否を決定する決定論的な検証ゲート、厳格なガードレール（パーミッションの許可リスト、反復回数の制限、コスト上限、キルスイッチ）、そして、人間への通知または失敗時のエスカレーションを行うハンドオフです。Claude Codeのヘッドレスモード（claude -p）、Claude Agent SDK、フック、スケジューラ（cronまたはlaunchd）がこれら5つ全てを提供します。エージェント自体が危険なわけではありません。ゲートとガードレールなしでそれを無人で実行することが危険なのです。まずそれらを構築し、それから手を離してください。

なぜ「ユーザーなしで実行される」ことが真の目標なのか

監視付きチャットには、あなたという硬い上限があります。各反復は、人間が出力を読み、次何をすべきか決定するのを待ちます。モデルは数秒で生成し、あなたがコンテキストを切り替える間、数分間アイドル状態になります。そうでなければ高速であるシステムにおいて、あなたがボトルネックとなっているのです。

無人ワークフローはその上限を取り除きます。エージェントが作業し、スクリプトがそれをチェックし、失敗は自動的に戻され、あなたは端で介入するだけです。その見返りは速度だけではありません。並列性です。一度ワークフローが監視なしで実行されるようになれば、タイピング速度を上げるのではなく、ワークフローを追加することでスケールします。これは、1つのセッションが多数の並列エージェントに分岐するClaude Codeの動的ワークフローで説明したのと同じ飛躍です。

しかし、「ユーザーなしで実行される」ことはリスクを高めます。誤った編集をする監視付きエージェントは、差分を読めば発見されます。無人のエージェントはそれをコミットし、次のステップを実行し、作業を続けます。したがって、規律はプロンプト作成からシステム設計へと移行します。つまり、誰も見ていないときに正確で、制限があり、観測可能である必要があるマシンを構築しているのです。Anthropicの効果的なエージェントの構築に関する記事も同様の主張をしています。レバレッジは、より賢い単一のメッセージからではなく、モデルを取り巻く環境から生まれます。

すべての無人ワークフローに必要な5つの要素

これらのいずれかをスキップすると、ワークフローは自信満々に間違ったことを行うか、決して止まらなくなります。

精密な仕様。 エージェントがあらゆる実行の開始時に読み込む「完了」の書面による記述。曖昧な仕様は曖昧な作業を生み出します。「APIを修正する」は失敗します。「POST /ordersエンドポイントは201を返し、スキーマに対してボディを検証し、欠落フィールドは422で拒否する」は成功します。
ヘッドレス実行。 Claudeは人間がキーボードを操作することなく実行されなければなりません。つまり、チャットUIではなく、非対話型モードを意味します。
検証ゲート。 具体的な理由とともに合否を返す決定論的なチェック：テスト、型チェック、スキーマ検証、契約テスト。これにより、ワークフローはモデルの言葉を鵜呑みにするのではなく、実際に完了したかどうかを判断できます。
ガードレール。 許可リスト、最大反復回数、コスト上限、ロギング、キルスイッチ。これらは、混乱した実行があなたが寝ている間に損害を与えるのを防ぎます。
ハンドオフ。 ワークフローが完了または諦めた場合、誰かに伝えます。通知、レビュー用のドラフト、失敗アラート。沈黙は成功ではありません。

中央の3つは、ほとんどのセットアップで手薄になりがちな部分です。Claudeが提供するツールを使って、それぞれを構築していきましょう。

Claudeの構成要素

ヘッドレスモード (claude -p)

Claude Codeのプリントモードは、プロンプトを非対話的に実行し、終了します。これは、すべての無人ワークフローの基盤となります。タスクを与え、ツールを制限し、出力をキャプチャして、次に進みます。

claude -p "spec.mdに従ってordersエンドポイントを実装し、テストスイートを実行する" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1

--allowedToolsフラグは、見た目以上に重要です。チャットUIでは、各アクションを手動で承認します。ヘッドレスの場合、承認する人間がいないため、許可リストがエージェントが触れるものを制御する唯一の手段となります。最初は狭く設定し、実行を信頼できるようになったら広げてください。完全なフラグセットはClaude Codeのドキュメントにあります。

Claude Agent SDK

シェルコマンドでは不十分な場合、Claude Agent SDKを使用すると、PythonまたはTypeScriptからプログラムでClaudeを駆動できます。コード内でループを取得します。タスクを送信し、結果をストリーミングし、ツール呼び出しを検査し、続行するかどうかを決定します。これが、エージェントの周りに真の制御フローを構築する方法です。

import { query } from "@anthropic-ai/claude-agent-sdk";

const MAX_ITERATIONS = 8;
let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `${task}\n\nPrevious failures:\n${feedback}`,
    options: { allowedTools: ["Edit", "Write", "Bash"] },
  })) {
    // エージェントが動作する際にメッセージをストリーム/ログに記録
  }

  const gate = runVerification();      // あなたの決定論的なチェック
  if (gate.passed) break;              // 完了
  feedback = gate.failures;            // 次のプロンプトはそれ自体で生成される
}

正確なシグネチャはドキュメントにありますが、重要なのはその形です。それは、前回の失敗を次のプロンプトとしてエージェントを再実行するループです。独自のループを構築するかホストされたオプションを使用するかで迷っている場合は、マネージドエージェントとAgent SDKの比較で、それぞれの利点が詳しく説明されています。

決定論的なガードレール用のフック

フックは、モデルが関与することなく、Claudeのライフサイクルの固定された時点で独自のコマンドを実行します。これらは、エージェントが言い訳できないルールを強制する方法です。ファイル編集のたびにテストスイートを実行したいですか？ PostToolUseフックがそれを決定論的に行います。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm test --silent" }]
      }
    ]
  }
}

フックはモデルへのリクエストではなく、単なるコードであるため、常に発火します。それは、無人実行におけるガードレールに求められる特性です。エージェントはそれをスキップすることを決定できません。

実行をトリガーするスケジューラ

ユーザーなしで実行されるワークフローは、ユーザーなしでそれを開始する何かを必要とします。サーバー上ではcron、Mac上ではlaunchdです。いずれにせよ、スケジュールに基づいてヘッドレスコマンドを発火させます。

# 毎週平日の午前7時：メンテナンスワークフローを実行し、すべてをログに記録
0 7 * * 1-5  cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" >> logs/run-$(date +\%F).log 2>&1

これが自律的なセットアップの全体像です。スケジューラがヘッドレスClaudeを起動し、エージェントは仕様に沿って作業し、フックとゲートがその正確性を保ち、ログが何が起こったかを伝えます。

プロンプトではなくループを設計する

これらすべてを結びつける考え方です。「Claudeに何を伝えるべきか？」と尋ねるのをやめ、「どのようなループがClaude自身に伝えさせるのか？」と尋ね始めてください。エージェントは、それが正しいかどうか信頼できる感覚を持たない高速な生成器です。ループはゲートを介してその感覚を提供します。これについては、コーディングエージェントにプロンプトを出すのをやめ、代わりにループを構築するで詳しく説明しました。これは、無人作業における最も重要な考え方です。モデルの自信は重要ではなくなり、ゲートの判定だけが重要になります。

これが、明確な仕様が巧妙なプロンプトよりも優れている理由でもあります。同じ仕様があらゆる反復を推進し、ドキュメントとしても機能します。意図、制約、完了の定義を捉えたdesign.mdまたはAGENTS.mdファイルは、あなたが毎回コンテキストを再説明する代わりに、あらゆる実行でエージェントに安定したターゲットを与えます。

実践例：無人APIメンテナンス

具体的に考えてみましょう。あるAPIエンドポイントのセットをOpenAPI仕様と同期させ、毎朝実行され、決して壊れたエンドポイントを出荷しないワークフローを望んでいるとします。その形がこちらです。

仕様。 契約はOpenAPIファイルにあり、挙動はテストケースにあります。エージェントは実行開始時に両方を読み込みます。
トリガー。 午前7時のcronジョブが、メンテナンスタスクでヘッドレスClaudeを起動します。
生成。 エージェントは実装と仕様を調整します。不足しているエンドポイントを追加し、不一致なレスポンスの形状を修正し、検証を強化します。
ゲート。 ワークフローは、実行中のサービスに対してAPIテストスイートを実行します。ステータスアサーション、あらゆるレスポンスに対するJSONスキーマ検証、仕様に対する契約チェック。失敗は構造化されて返されます。「customer_idがない場合に422を期待したが、500が返された。」「レスポンスフィールドtotalが文字列だが、スキーマでは数値となっている。」
ループまたはエスカレーション。 赤色のゲート？構造化された失敗が次のプロンプトとなり、エージェントは反復上限まで特定のギャップを修正します。緑色？ドラフトPRを開きます。試行回数を超過？最後の失敗とともにアラートを記録し、停止します。
ハンドオフ。 人間は、レビュー用のきれいなPRか、正確な失敗レポートを受け取ります。決してサイレントコミットはありません。

ステップ4のゲートは、全体の無人実行を安全にするものです。それがないと、エージェントはコードを編集し、自身の解釈に基づいて成功を報告します。これこそが、壊れたエンドポイントが本番環境に到達する原因です。ここに、Apidogが自律ワークフローに適合する点があります。APIデザイン、スキーマ、モックサーバー、自動テストが1つのワークスペースに存在するため、ゲートと仕様がデフォルトで同期した状態を保ちます。Apidogテストシナリオに実行を指示すると、エージェントは各反復でスキーマ検証された合否判定を受け取ります。モックサーバーは起動していない依存関係の代わりとなり、午前3時の実行が不安定なサードパーティを待ってブロックされることはありません。Apidog AIエージェントデバッガを介してエージェントのエンドポイントアクセスを配線するチームは、人間のテスターがするのと同じ方法でエンドポイントをヒットおよび検査させることができます。ランナーを手作業で構築するよりも視覚的にゲートを構築したい場合は、Apidogをダウンロードしてください。

無人実行を安全にするガードレール

これが、夜間に信頼できるワークフローと、午前3時にあなたを起こすワークフローを分ける部分です。監視されていないエージェントには、善意ではなく、厳格な制限が必要です。

厳格なパーミッション許可リスト。 ヘッドレスでは、許可リストがエージェントができることに対する唯一のゲートです。タスクに必要な最小限のツールを付与してください。サンドボックスなしで、無制限のシェルや破壊的なコマンドを無人実行に渡してはなりません。
反復回数の制限。 ループに上限を設けます。N回の試行で緑のゲートに到達できない実行は、永遠に処理を続けるのではなく、停止してエスカレーションすべきです。
コスト上限。 無人ループは人間が気づかないうちにトークンを消費します。支出制限を設定し、実行ごとの支出をログに記録します。収束しないループは、制限に達して停止すべきです。エージェントトークンコストの削減に関する我々の記事が直接ここに適用されます。
ゲートの保護。 テストファイルと仕様を、エージェントが編集できるファイルのセットから除外します。もしエージェントがテストを書き換えて通過させることができれば、あなたは進捗を偽装するマシンを構築したことになります。
サンドボックス。 無人作業は、メインではなく、分離されたワークスペースまたはコンテナ内で実行します。gitワークツリーまたは使い捨てのブランチは、悪い実行による影響範囲を限定します。
ロギングとキルスイッチ。 あらゆる実行を実際に読むログに記録し、ジョブの実行中に停止する方法を確保してください。記録されていないものはデバッグできません。
端での人間の承認。 「ユーザーなし」は「誰でもなし」という意味ではありません。開始時（タスクの承認）または終了時（PRの承認）に人間を配置しますが、内部ループには配置しません。ここでの配線パターンと失敗モードは、エージェントワークフローツール配線と一致します。

これらのほとんどは、1つのルールに集約されます。それは、無人エージェントは自分の仕事以外は何もできないようにすべきだということです。ツールを制限し、ループに境界を設け、ワークスペースを隔離し、あらゆる実行を観測可能にしてください。

よくある間違い

いくつかのパターンは、自律ワークフローを急速に破綻させます。

ゲートなし、ただのフィーリング。 唯一のチェックが「エージェント、終わった？」であるなら、ワークフローではなく、監視されていないチャットボットです。ゲートはエージェントの外部に存在しなければなりません。
一つの巨大なタスク。 「サービス全体をメンテナンスせよ」と指示された実行は、めったに収束しません。エンドポイントサイズのタスクに分解し、それぞれに独自のゲートを持たせます。小さな実行は完了しますが、大きな実行は混乱します。
広すぎるパーミッション。 便利だからといってあらゆるツールを付与すると、誰も見ていないときに小さなバグが大きなインシデントに発展します。厳密に許可リストを設定してください。
サイレントな成功またはサイレントな失敗。 誰にも知らせずにコミットしたり、アラートなしで停止したりするワークフローは、ワークフローがないよりも悪いものです。常にハンドオフを行ってください。
モデルの自己申告を信頼すること。 エージェントは「完了した」と言うでしょう。しかし、それが完了したかどうかを決定するのはゲートです。「完了しているように見える」と「完了している」の間のギャップに備えて構築してください。なぜなら、無人では誰もそれを捕まえる人がいないからです。

これらを正しく設定すれば、Claudeワークフローはコーヒーを飲む前に、1日分の範囲内で検証済みの作業を完了します。これらを間違えると、自信過剰でテストされていないコードの生成を自動化してしまいます。その違いは、モデルではなく、ゲートとガードレールにあります。より深いアーキテクチャを知りたい場合は、エージェントハーネス設計に関する我々の詳細な説明が、大規模に各要素がどのように適合するかをカバーしています。

要点

ユーザーなしで実行されるClaudeワークフローを構築することは、Claudeそのものよりも、それを囲むシステムについてです。5つの要素がその重責を担います。精密な仕様、ヘッドレス実行、決定論的な検証ゲート、厳格なガードレール、そしてクリーンなハンドオフです。これらを正しく設定すれば、モデルは、あなたが見ていないときに正確で、制限があり、観測可能であるマシンの内部で高速な作業者となります。

1つのワークフローから始めてください。厳密な仕様を作成し、高速な検証ゲートに対してヘッドレスで実行し、ツールを許可リストに登録し、反復回数に上限を設け、ワークスペースを隔離し、完了または失敗時に通知するように設定してください。APIに触れるものについては、テストスイートが無人実行を安全にするゲートとなり、Apidogは、API設計、モック、自動テストを1つのワークスペースで提供し、それらを構築できます。ダウンロードし、ゲートを配線し、あなたが別のことをしている間にワークフローにその作業を任せましょう。