Claude Code Loop Engineeringガイド：4つのLoopと安全な自動化設計

Claude CodeのLoopは、単にモデルを長時間実行する機能ではない。核心は、確率的に行動するAI Agentの周囲に Trigger, Verifier, Success condition, Hard stop, Permission boundary を配置し、反復作業を制御可能なシステムにすることにある。本稿では、Turn-based、Goal-based、Time-based、Proactive Loopの違いと実務上の設計原則を一度に整理する。

1. Claude CodeにおけるLoopとは何か

ここでいうLoopは、プログラミング言語のforやwhile文ではない。Claude Codeチームが説明するLoopは、Agentが現在の状態を観察し、行動し、結果を検証した後、終了条件が満たされるまで再び作業する実行構造だ。

作業開始
  ↓
状態とコードの把握
  ↓
計画策定
  ↓
コード修正またはツール実行
  ↓
テスト・検証
  ↓
完了条件を満たしたか？
  ├─ いいえ: 次の反復
  └─ はい: 終了および結果報告

Loopを区別するときは、次の4つの質問が役に立つ。

1. 何が作業を開始させるのか？
2. 何が作業を終了させるのか？
3. どのClaude Code機能が反復を制御するのか？
4. どのような種類の作業に適しているのか？

すべての作業を複雑なLoopにする必要はない。1つのファイルの誤字修正や単純な名前変更のように、結果をすぐ確認できる作業には通常のプロンプトのほうが効率的だ。Loopは、複数回の観察・修正・検証が実際に必要な場合にのみ選択すべきだ。

2. 4種類のLoopタイプ比較

この分類の核心は、「AIがどれだけ賢いか」ではなく、人がどの制御責任をシステムに委ねるかだ。Turn-basedでは人が次のプロンプトを作り、Goal-basedでは完了判断を委ね、Time-basedでは再実行時点を委ねる。Proactive段階では、作業発生を検知し、適切なプロンプトを実行する責任までシステムへ移動する。

3. Turn-based Loop: 検証手順を委ねる

Turn-based Loopは、ほとんどの開発者がClaude Codeを使う基本形だ。

Human → Claude → Human → Claude

ユーザーが依頼すると、Claudeは関連ファイルを探し、コードを修正し、テストし、結果を報告する。内部的には複数回の観察・行動・検証が起きることがあるが、次の作業を開始する権限はユーザーに残っている。

コード修正と機能完成は異なる

Claudeが「実装とテストを完了した」と報告しても、実際の製品では次の問題が残ることがある。

• ボタンをクリックしても状態が変わらない。
• ブラウザコンソールにエラーが発生する。
• モバイルレイアウトが崩れる。
• アクセシビリティ属性が抜けている。
• テストは通るが、実際のブラウザフローは失敗する。
• 変更と無関係なファイルまで修正された。

したがって完了基準は、「コードを変えた」ではなく「外部証拠で動作を確認した」でなければならない。

SKILL.mdで検証を再利用する

Skillは、繰り返し使う指示と手順をSKILL.mdに保存する方式だ。Claudeが関連性を判断して自動で読み込むか、/skill-nameで直接実行できる。長い運用手順を常にCLAUDE.mdに入れるより、必要な瞬間にだけSkillをロードするよう分離すれば、コンテキストをより効率的に使える。

---
name: verify-ui-change
description: UI変更を完了扱いにする前に、実際の実行環境で検証する。
---

# UI変更の検証

1. 開発サーバーを実行する。
2. 変更された画面をブラウザで開く。
3. 新しいコントロールを実際に操作する。
4. 期待した状態変化が発生するか確認する。
5. ブラウザコンソールの新しいエラーと警告を確認する。
6. アクセシビリティおよび主要なパフォーマンス指標を点検する。
7. 失敗した場合は修正後、最初から再度検証する。
8. 実行したコマンド、結果、スクリーンショットなどの証拠を報告する。

良いSkillは、抽象的なお願いではなく実行可能なチェックリストを含む。「より慎重に検討する」より「npm testが終了コード0か確認する」のほうが、はるかに強いルールだ。

検証証拠の強度

Claude Code公式ドキュメントには、実行中のアプリケーションを確認する/run、変更を実際の実行環境で検証する/verifyのようなbundled Skillも説明されている。プロジェクトの実行方式が複雑なら、チーム固有のSkillに正確な開始コマンド、環境変数、データ準備手順を記録するほうが安全だ。

4. Goal-based Loop: 終了判断を委ねる

Goal-based Loopでは、「もう一度作業するか」をユーザーが毎回決めない。ユーザーは完了状態を定義し、Claudeはその条件が満たされるまで複数のTurnを続ける。

ユーザーがGoalを指定
  ↓
Claude作業Turn
  ↓
別の評価モデルが完了条件を確認
  ├─ 未達成: 理由を次のTurnに伝達
  └─ 達成: Goal終了

/goalはClaude Code v2.1.139以上で使用できるよう文書化されている。1つのセッションでは1つのGoalだけを有効化できる。

評価モデルが実際に見るもの

各Turnが終わると、別のsmall fast modelが完了条件と会話内容を見て、達成または未達成を判断する。デフォルト設定はHaiku系の評価モデルだ。重要な制限は、評価モデルがファイルを直接読んだり、テストを別途実行したりしない点だ。

したがって、作業を行ったClaudeが次の証拠を会話に明確に残さなければならない。

• 実行したコマンド
• テスト数と成功・失敗結果
• 終了コード
• ビルド結果
• 変更ファイル一覧
• 残っている失敗原因
• 範囲制約を守ったという確認結果

評価モデルは「実際に何が起きたか」ではなく、「会話にどのような証拠が示されたか」を判断する。

良いGoalの4要素

良いGoalは次の4要素を含む。

1. 測定可能な成功条件: テスト通過、ビルド成功、キューが空になる、スコア閾値達成
2. 検証方法: どのコマンドやツールで成功を証明するかを明示
3. 変更範囲の制約: 修正可能なディレクトリ、禁止ファイル、許可されたSide effect
4. 強制終了条件: 最大Turn、最大時間、連続失敗回数、権限エラー時の中断

/goal auth関連テストとlintがすべて成功し、
git diffにはsrc/authと関連テストファイルのみ含まれていなければならない。
各Turnで実行結果と終了コードを報告する。
最大12ターンまたは45分に達したら中断し、残った失敗を整理する。

/goal自体の核心的な終了条件は、評価モデルの成功判定またはユーザーの/goal clearだ。Turn・時間上限を強制するには、Goal条件の中に明示しなければならない。

良い条件と悪い条件

曖昧な目標は、早すぎる終了や終わりのない改善の反復につながることがある。

状態確認と中断

• /goal: 有効条件、実行時間、評価Turn数、トークン使用量、最近の評価理由を確認
• /goal clear: 有効なGoalを中断
• 新しいGoal設定: 既存Goalを置き換え
• --resumeまたは--continue: 未完了Goalの復元が可能

再開時に条件は維持されるが、Turn数、時間、トークンの基準線は初期化されることがあるため、Hard stopを運用指標と併せて管理するのがよい。

/goalと権限は別物だ

/goalは次のTurnを自動的に開始するだけで、ツール権限を広げるわけではない。ファイル書き込み、テストコマンド、Git作業が承認対象なら、Goal中でも承認が必要になることがある。

無人実行にはAuto modeを併用できるが、Auto modeは「すべてのツールを無条件に許可する」機能ではない。分類器が破壊的、または元に戻しにくい、あるいは信頼境界の外を対象とする作業をブロックし、明示的なaskとdenyルールは分類器より先に適用される。

5. Time-based Loop: 再実行時点を委ねる

Goal-based Loopが「いつ止まるか」を扱うなら、Time-based Loopは「いつ再び実行するか」を扱う。外部システムの状態が時間とともに変化する作業に適している。

• PRに新しいレビューが付いたか確認
• CIまたはデプロイが終わったか確認
• 長時間ビルドの状態確認
• 毎日のSlackメッセージ要約
• イシューキューの新規項目確認

/loop: 現在のセッション内で反復実行

/loop 10m 現在のPRを確認して新しいレビューを反映し、
失敗したCIがあれば原因を分析して修正する。

現在のドキュメントで説明されている主な形式は次のとおりだ。

/loopは現在のClaude Codeセッションに依存する。コンピューターとセッションが実行中でなければならず、新しい会話を始めるとセッション範囲の作業は消える。未期限切れの作業は--resumeまたは--continueで復元できるが、反復作業は基本的に作成後7日で期限切れになる。逃した周期をすべて遡って実行することもない。

セッションSchedulerにはJitterが適用されることがあるため、「正時に必ず実行」しなければならない運用要件には適さない場合がある。

/schedule: Anthropic管理Cloud Routine

/scheduleはPromptとRepository、Connector、Triggerを束ね、Anthropic管理インフラで実行するRoutineを作る。ノートPCを閉じても実行でき、公式ドキュメントではResearch Previewとして案内されている。

RoutineがサポートするTriggerは次のとおりだ。

• 反復スケジュール
• 特定の未来時点の一回限りのスケジュール
• 認証済みAPI呼び出し
• GitHub Pull requestまたはReleaseイベント

1つのRoutineに複数のTriggerを接続できる。たとえばPR Review Routineを毎晩実行しつつ、pull_request.openedイベントにも反応させることができる。

/loopと/scheduleの比較

PollingよりEventが優れている場合

変更が少ないPRを1分ごとに確認すると、ほとんどの実行は何もせず終了する。外部システムがイベントを送れるなら、次の構造のほうが効率的だ。

CI失敗またはPR更新
  ↓
GitHub TriggerまたはRoutine API
  ↓
必要なときだけClaude実行

Eventベースの設計は遅延を減らし、不要なモデル呼び出しとトークン消費を減らす。Pollingが避けられないなら、実際の変更頻度に合わせて間隔を伸ばし、長時間変化がないときはBackoffを適用するのがよい。

時間ベース作業の必須条件

1. 冪等性: 同じイベントを複数回受け取っても、重複コメント、重複PR、重複デプロイが発生してはならない。
2. 処理状態: 最後に処理したEvent ID、Commit SHA、Review Comment IDなどを記録しなければならない。
3. 終了状態: PR merge・close、Queue empty、Deploy success・rollbackのように終了を判定できなければならない。
4. 書き込み範囲: コメント許可、Merge禁止、claude/* BranchのみPushなど、Side effectを制限しなければならない。
5. 失敗処理: 外部サービス障害、認証期限切れ、Rate limit、権限不足時の再試行とEscalationルールが必要だ。

6. Proactive Loop: 作業発見とオーケストレーションを委ねる

Proactive Loopは1つのコマンドではなく、複数の機能を組み合わせた常時自動化アーキテクチャだ。

Trigger
+ Goal
+ Skills
+ Dynamic Workflow
+ Auto mode
+ Repository・Connector・Browser・CIツール

人がリアルタイムでプロンプトを入力しなくても、新しい作業が検知され、処理され、検証され、結果が報告される。

例: バグフィードバックの自動処理

GitHub IssueまたはSlackフィードバック受信
  ↓
重複・優先順位・再現可能性の分類
  ↓
再現テスト作成
  ↓
候補解決策の探索
  ↓
選択した解決策の実装
  ↓
独立したReview Agentが反例を探索
  ↓
テスト・ビルド・セキュリティ検証
  ↓
Draft PRと結果報告

構成要素ごとの責任は次のとおりだ。

Dynamic WorkflowとWorktree

Dynamic Workflowは、Claudeが作成したJavaScriptオーケストレーションScriptをRuntimeが実行する構造だ。通常のSubagent呼び出しでは、ClaudeがTurnごとに次のAgentを選ぶが、WorkflowではLoop、並列処理、分岐、中間結果の保存がScriptに移る。

Workflow Script
  ├─ Agent A: 要件分析
  ├─ Agent B: テスト設計
  ├─ Agent C: 実装候補探索
  ├─ Agent D: セキュリティレビュー
  └─ Judge: 証拠ベースの比較

中間結果がメイン会話ContextではなくScript変数に残るため、大規模作業をより再現可能に組織できる。現行ドキュメントには、同時に最大16個のAgent、実行あたり最大1,000個のAgentというRuntime上限が明記されているが、製品Preview段階の制限は変わる可能性がある。

複数の実装候補を同時に試す必要があるなら、Git Worktreeで作業空間を分離できる。

repo/
worktree-solution-a/
worktree-solution-b/
worktree-solution-c/

各Agentが独立したBranchとディレクトリで作業すれば、同じファイルを同時に上書きする問題を減らせる。Judge Agentは、要件充足、テスト結果、回帰リスク、変更範囲、複雑度、性能、セキュリティ、既存アーキテクチャとの一貫性を基準に候補を比較しなければならない。

Agentが多ければ常に良いわけではない

並列性のない作業でAgent数だけを増やすと、コストと遅延が増える。複数のAgentが同じ誤った仮定を共有すれば、エラーが拡大することもある。

Dynamic Workflowが適している場合は次のとおりだ。

• 数百ファイルに同じ変換を適用するMigration
• コードベース全体のセキュリティ・品質Audit
• 独立した複数観点のPlan比較
• 多くの項目を分割処理し、相互検証しなければならないResearch
• 1つのAgentのContextにすべての中間結果を入れるのが難しい作業

小さなバグ修正、1ファイルのリファクタリング、単純なテスト追加には、通常のTurn-based Loopや/goalのほうがよい。

7. Loopでコード品質を維持するシステム

Loop結果の品質は、モデル自体だけでなく、モデル周辺の検証システムに大きく左右される。

7.1 コードベースを整える

Claudeは既存コードのパターンを強く踏襲する。古いAPI、重複実装、不明確なテスト構造、巨大なモジュール、一貫しない例外処理ルールがあると、Loopがその問題を素早く複製してしまうことがある。

必須の基盤は次のとおりだ。

• Formatterとlint
• 明確なディレクトリとモジュール境界
• 信頼できるUnit・Integration・E2E Test
• 使用中のAPIとDeprecated APIの区別
• プロジェクト別の開発ルール
• 再現可能なBuild・Dev環境

7.2 変更タイプ別Definition of Doneを作る

この基準はPromptに毎回長く繰り返すより、Skill、Hook、Script、CI Ruleとして固定するほうがよい。

7.3 最新ドキュメントと正確なバージョンを提供する

Loopは誤った仮定を何度も繰り返すことがある。プロジェクトで使う正確なVersion、公式ドキュメント、内部Architecture文書、API仕様、Migration Guide、承認済みの例を簡単に見つけられるようにしなければならない。

7.4 実装AgentとReview Agentを分離する

実装したAgentは、すでに選択した設計と推論の影響を受けている。新しいContextのReview Agentは、次の質問をより独立して投げかけることができる。

• テストを弱めて通したのではないか？
• 範囲外ファイルを変更していないか？
• セキュリティ境界が破られていないか？
• 失敗経路と境界値テストが抜けていないか？
• 既存機能に回帰が生じていないか？

Review Promptは、「良い点を要約せよ」より「実装が間違っているという仮定で反例を探し、各指摘に再現証拠を付けよ」のように書くほうが効果的だ。

7.5 個別の失敗をシステム改善につなげる

同じエラーが繰り返されるなら、その結果だけを修正してはいけない。失敗タイプが再発しにくくなるよう、次のいずれかを変える必要がある。

• Regression Test追加
• Skill検証手順の強化
• CLAUDE.mdルール追加
• Hookまたはlint Rule追加
• 権限Deny Rule追加
• Goalの完了条件強化
• Review Checklist補完

良いLoop Engineeringとは、1回の失敗を直す作業ではなく、その種類の失敗が再び出にくいシステムを作る作業だ。

8. Tokenとコスト管理

Loopのコストは単一Promptより大きく増えることがある。

総コスト ≈
メインAgent Turnコスト
+ Goal評価コスト
+ Subagentコスト
+ Workflow反復コスト
+ ツール結果を読むContextコスト
+ 時間ベース実行頻度

正確な課金はPlan、Model、Providerによって異なるが、コスト構造を決める原理は同じだ。

コストを減らす実務原則

1. 小さな作業にはLoopを使わない。 誤字、名前変更、1ファイルの型エラーは単一Turnで処理する。
2. 成功条件とHard stopを併せて置く。 成功、最大Turn、最大時間、連続失敗、権限エラーをすべて考慮する。
3. 大規模Workflowは小さい範囲で試す。 5個のファイル、1つのディレクトリ、一部のIssueでコストと品質を検証した後に拡大する。
4. 決定論的作業はScriptで処理する。 AST置換、JSON変換、Formatting、固定形式生成は、検証済みのScriptのほうが安く再現可能だ。
5. Polling周期を実際の変更頻度に合わせる。 可能ならEvent Triggerを使う。
6. 進行中の使用量を観察する。 /usage、/goal、/workflowsでSkill・Subagent・MCP・Turn・Token使用量を確認する。
7. 同じエラーが繰り返されるなら、再試行を続けない。 連続失敗上限を置き、人にEscalationする。

ModelとEffortは別のレバーだ

• Modelは基本的な推論能力と解決可能な問題の範囲を変える。
• Effortは読むファイル数、使用するツール数、検証の幅、複数段階作業をどこまで最後まで押し切るかを変える。

Claudeが必要なファイルとテストをすべて確認したにもかかわらず判断自体がずっと間違うなら、より強いModelが必要なことがある。逆に、重要なファイルを読まない、テストを飛ばす、リファクタリングを途中で終えるなら、Effortを高めるほうがより適切なことがある。

9. 権限と安全境界

Proactive Loopで最も危険な設計は、Agentに広い権限を与え、成功条件と中断条件を緩く置くことだ。

Auto modeは通常の権限Promptを減らすが、元に戻しにくい、破壊的、または信頼境界の外を対象とするTool callは分類器がブロックすることがある。また、明示的なpermissions.askとpermissions.denyはAuto modeより優先される。

権限階層の例

会話で「Pushするな」と一度言うより、永続的なask・deny Ruleとして固定するほうが安全だ。Context圧縮やセッション変更によって、会話上のルールが弱まることがあるからだ。

Cloud Routineは実行ごとにRepositoryを新たにCloneし、接続されたGitHub・Connector権限で動作する。次の範囲を最小化しなければならない。

• アクセス可能なRepositoryとBranch
• 許可されたNetwork Domain
• 使用するConnector
• 環境変数とSecret
• 外部システムの書き込み権限
• PR作成・Push・Merge範囲

Routine実行一覧の「正常終了」状態は、InfrastructureエラーなしにSessionが終わったという意味である場合があり、業務目標が成功した保証ではない。Transcript、Test evidence、生成されたDiffを別途レビューしなければならない。

10. 開発プロジェクト用Loop設計テンプレート

次のYAMLは実際のClaude Code文法ではなく、設計レビュー用Templateだ。

trigger:
  type: manual | interval | schedule | github_event | api_event

scope:
  repositories:
    - target-repository
  allowed_paths:
    - src/**
    - tests/**
  prohibited_paths:
    - production/**
    - secrets/**

task:
  objective: 変更または処理する目標
  input: 新しく入ってくるIssue、Event、Fileまたは状態

verification:
  commands:
    - unit-test
    - integration-test
    - lint
    - build
  runtime_checks:
    - browser-interaction
    - console-errors
    - accessibility
  evidence:
    - command-output
    - exit-code
    - test-summary
    - screenshots

success:
  condition: 真偽で判定可能な完了状態

stop:
  max_turns: 12
  max_duration_minutes: 45
  max_consecutive_failures: 3
  stop_on_permission_error: true
  escalate_on_external_outage: true

side_effects:
  idempotency_key: event-id-or-commit-sha
  allow_branch_push: claude/*
  require_human_for_merge: true
  require_human_for_deploy: true

review:
  independent_agent: true
  adversarial_review: true

observability:
  report_progress: true
  report_token_usage: true
  report_changed_files: true
  report_remaining_failures: true

最も重要な項目は、プロンプト文そのものより次の5つだ。

Trigger
Verifier
Success condition
Hard stop
Permission boundary

11. どのLoopを選ぶべきか

選択順序は「最も強力な機能」ではなく、「目標を達成する最も単純な制御構造」を基準にすべきだ。

12. 安全な導入順序

1. 人が繰り返し確認しているボトルネック業務を1つ選ぶ。
2. まず検証手順をSkill、Script、CIとして作る。
3. Turn-based方式で検証品質を安定化する。
4. 完了状態が明確なら/goalを付ける。
5. 外部状態を待つ必要があるときだけ/loopを使う。
6. 長期実行が必要なら/schedule Routineへ移す。
7. 冪等性、権限、コストが検証された後にのみDynamic WorkflowとProactive Loopへ拡張する。

13. よくある誤解

結論

Loop Engineeringは、AIを長時間実行させる技術ではなく、AIが間違ったときに自ら発見し、コスト上限内で修正し、危険な地点では止まるようにする制御システム設計だ。

LLMは探索、推論、実装、例外分析、代替案比較に強い。システムは実行時点、変更範囲、検証方法、終了基準、コスト上限、承認境界を担当すべきだ。この役割分担が明確であるほど、Claude Code自動化は単なるコード生成ツールを超え、再現可能で監査可能な開発運用システムに近づく。