Claude Code Loop Engineeringガイド：4つのLoopと安全な自動化設計 ================================================ Claude CodeのLoopは、エージェントが観察・行動・検証を終了条件まで繰り返すようにする制御構造だ。4種類のLoopの違いとともに、検証証拠、強制終了、冪等性、コスト、最小権限を含む実務上の設計方法を説明する。 - Claude CodeのLoopはコードのループ文ではなく、観察・行動・検証を終了条件まで繰り返すエージェント実行構造だ。 - Turn-basedは検証手順、Goal-basedは終了判断、Time-basedは再実行のタイミング、Proactiveは作業開始とオーケストレーションをシステムに委ねる。 - 優れたLoopには、測定可能な完了条件、外部の検証証拠、強制終了、冪等性、最小権限が備わっている必要がある。 - `/goal`評価モデルは、対話に現れた証拠だけを判断するため、テスト出力、終了コード、変更範囲を明確に報告する必要がある。 - 決定論的な変換はScriptで処理し、Dynamic Workflowと複数のAgentは、実際の並列性が必要な大規模作業にのみ適用すべきだ。 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つの質問が役に立つ。 何が作業を開始させるのか？ 何が作業を終了させるのか？ どのClaude Code機能が反復を制御するのか？ どのような種類の作業に適しているのか？ すべての作業を複雑なLoopにする必要はない。1つのファイルの誤字修正や単純な名前変更のように、結果をすぐ確認できる作業には通常のプロンプトのほうが効率的だ。Loopは、複数回の観察・修正・検証が実際に必要な場合にのみ選択すべきだ。 2. 4種類のLoopタイプ比較 タイプ 開始条件 終了条件 主に使用する機能 適した作業 人が委ねる責任 Turn-based ユーザーのプロンプト Claudeが完了したと判断するか、追加情報が必要なとき 通常の会話、Skills、テスト・ブラウザツール 短く一回性の実装・修正 反復検証手順 Goal-based ユーザーが完了条件を指定 評価モデルが条件達成を確認するか、ユーザーが中断 /goal、必要に応じてAuto mode テスト・ビルド・マイグレーションのように完了状態を測定できる作業 終了判断 Time-based 指定した時間・間隔・スケジュール ユーザーがキャンセルするか、外部作業が終わる /loop、/schedule PR・CI・デプロイ監視、定期要約、状態Polling 次の実行時点 Proactive スケジュール、API、GitHubイベントなど 個別作業の目標達成、Routineの無効化 Routines、/goal、Skills、Dynamic Workflows、Auto mode イシュー分類、バグ対応、大規模マイグレーションなどの継続業務 作業発見、プロンプト実行、オーケストレーション この分類の核心は、「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か確認する」のほうが、はるかに強いルールだ。 検証証拠の強度 証拠 信頼度 理由 「正常だと思われる」というAgentの説明 低い 実行結果ではなく推論にすぎない コードDiffと静的レビュー 中程度 変更内容は見えるがRuntime動作は確認できない 実際のテスト出力と終了コード 高い 再現可能な外部結果が存在する ブラウザ操作、スクリーンショット、コンソール・パフォーマンス結果 非常に高い ユーザー経路とRuntime状態を直接検証する 独立したReview AgentとCIが同じ結論を出す 非常に高い 実装Agentの自己確証バイアスを減らす 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要素を含む。 測定可能な成功条件: テスト通過、ビルド成功、キューが空になる、スコア閾値達成 検証方法: どのコマンドやツールで成功を証明するかを明示 変更範囲の制約: 修正可能なディレクトリ、禁止ファイル、許可されたSide effect 強制終了条件: 最大Turn、最大時間、連続失敗回数、権限エラー時の中断 /goal auth関連テストとlintがすべて成功し、 git diffにはsrc/authと関連テストファイルのみ含まれていなければならない。 各Turnで実行結果と終了コードを報告する。 最大12ターンまたは45分に達したら中断し、残った失敗を整理する。 /goal自体の核心的な終了条件は、評価モデルの成功判定またはユーザーの/goal clearだ。Turn・時間上限を強制するには、Goal条件の中に明示しなければならない。 良い条件と悪い条件 良い条件 悪い条件 npm testが終了コード0で終わる コードを完璧にする 認証関連テスト48個がすべて通過する ユーザー体験を最大限改善する すべてのAPI呼び出し箇所が新しいインターフェースに変更され、ビルドが成功する より良い構造にリファクタリングする 処理対象イシューキューが空になり、各イシューに結果が記録される 可能な限り多くのイシューを処理する 曖昧な目標は、早すぎる終了や終わりのない改善の反復につながることがある。 状態確認と中断 /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 5m <prompt> 指定した固定間隔でPromptを実行 /loop <prompt> Claudeが反復ごとに間隔を選択 /loop built-inメンテナンスPromptまたはプロジェクトのloop.mdを実行 /loop 20m /review-pr 1234 許可されたSkillを指定間隔で再実行 /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の比較 区分 /loop /schedule Routine 実行場所 現在のコンピューターとセッション Anthropic管理Cloud コンピューター終了後の実行 一般的に不可 可能 開いているセッション 必要 不要 ローカルの未コミットファイル アクセス可能 アクセス不可、実行ごとにRepositoryを新たにClone 最小間隔 公式ドキュメント基準1分 公式ドキュメント基準1時間 持続性 セッション中心、反復作業は7日で期限切れ アカウントに保存されるRoutine 権限Prompt 現在のセッションポリシーを継承 対話型承認なしで自律実行 適した用途 短いPR・デプロイ監視 継続的な運用自動化 PollingよりEventが優れている場合 変更が少ないPRを1分ごとに確認すると、ほとんどの実行は何もせず終了する。外部システムがイベントを送れるなら、次の構造のほうが効率的だ。 CI失敗またはPR更新 ↓ GitHub TriggerまたはRoutine API ↓ 必要なときだけClaude実行 Eventベースの設計は遅延を減らし、不要なモデル呼び出しとトークン消費を減らす。Pollingが避けられないなら、実際の変更頻度に合わせて間隔を伸ばし、長時間変化がないときはBackoffを適用するのがよい。 時間ベース作業の必須条件 冪等性: 同じイベントを複数回受け取っても、重複コメント、重複PR、重複デプロイが発生してはならない。 処理状態: 最後に処理したEvent ID、Commit SHA、Review Comment IDなどを記録しなければならない。 終了状態: PR merge・close、Queue empty、Deploy success・rollbackのように終了を判定できなければならない。 書き込み範囲: コメント許可、Merge禁止、claude/* BranchのみPushなど、Side effectを制限しなければならない。 失敗処理: 外部サービス障害、認証期限切れ、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と結果報告 構成要素ごとの責任は次のとおりだ。 構成要素 責任 Triggerまたは/schedule 新しい作業を開始する時点を決定 /goal 今回の実行で何が完了状態かを定義 Skill 再現、実装、検証、報告手順の標準化 Dynamic Workflow 複数Subagentの並列実行と条件分岐 Auto mode 許可されたツール呼び出しを承認待ちなしで実行 Permission policy 禁止・承認・自動許可範囲を固定 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を作る 変更タイプ 最小検証 API 契約テスト、後方互換性、Schema・ドキュメント例の更新 Frontend 実際のブラウザ操作、コンソールエラー、アクセシビリティ、レスポンシブ画面 Database Forward・Rollback Migration、Lock範囲、実行計画 Dependency Build、主要回帰テスト、License・Security確認 Infrastructure Plan Diff、最小権限、Rollback、秘密情報露出検査 この基準は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によって異なるが、コスト構造を決める原理は同じだ。 コストを減らす実務原則 小さな作業にはLoopを使わない。 誤字、名前変更、1ファイルの型エラーは単一Turnで処理する。 成功条件とHard stopを併せて置く。 成功、最大Turn、最大時間、連続失敗、権限エラーをすべて考慮する。 大規模Workflowは小さい範囲で試す。 5個のファイル、1つのディレクトリ、一部のIssueでコストと品質を検証した後に拡大する。 決定論的作業はScriptで処理する。 AST置換、JSON変換、Formatting、固定形式生成は、検証済みのScriptのほうが安く再現可能だ。 Polling周期を実際の変更頻度に合わせる。 可能ならEvent Triggerを使う。 進行中の使用量を観察する。 /usage、/goal、/workflowsでSkill・Subagent・MCP・Turn・Token使用量を確認する。 同じエラーが繰り返されるなら、再試行を続けない。 連続失敗上限を置き、人にEscalationする。 ModelとEffortは別のレバーだ Modelは基本的な推論能力と解決可能な問題の範囲を変える。 Effortは読むファイル数、使用するツール数、検証の幅、複数段階作業をどこまで最後まで押し切るかを変える。 Claudeが必要なファイルとテストをすべて確認したにもかかわらず判断自体がずっと間違うなら、より強いModelが必要なことがある。逆に、重要なファイルを読まない、テストを飛ばす、リファクタリングを途中で終えるなら、Effortを高めるほうがより適切なことがある。 9. 権限と安全境界 Proactive Loopで最も危険な設計は、Agentに広い権限を与え、成功条件と中断条件を緩く置くことだ。 Auto modeは通常の権限Promptを減らすが、元に戻しにくい、破壊的、または信頼境界の外を対象とするTool callは分類器がブロックすることがある。また、明示的なpermissions.askとpermissions.denyはAuto modeより優先される。 権限階層の例 レベル 例 自動許可 コード読み取り、テスト・lint・Build、分析、claude/* Branch作成、Draft PR作成 人の承認 Default Branch反映、本番デプロイ、DB Migration適用、外部顧客メッセージ送信 常に禁止 Force push、Secret出力、本番データ削除、権限迂回、監査ログ削除 会話で「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を選ぶべきか 状況 推奨方式 1回の修正と検証で終わる作業 Turn-based 複数回試す必要があるが完了状態が明確な作業 /goal 外部CI・PR・デプロイ状態をしばらく待つ必要がある作業 /loop ノートPCを閉じても反復実行する必要がある業務 /schedule Routine GitHubイベントやAlertに即時反応しなければならない業務 Event-triggered Routine 数百項目を並列処理し、相互検証しなければならない業務 Dynamic Workflow 入力と出力ルールが完全に決定論的な変換 ScriptまたはCI Job 選択順序は「最も強力な機能」ではなく、「目標を達成する最も単純な制御構造」を基準にすべきだ。 12. 安全な導入順序 人が繰り返し確認しているボトルネック業務を1つ選ぶ。 まず検証手順をSkill、Script、CIとして作る。 Turn-based方式で検証品質を安定化する。 完了状態が明確なら/goalを付ける。 外部状態を待つ必要があるときだけ/loopを使う。 長期実行が必要なら/schedule Routineへ移す。 冪等性、権限、コストが検証された後にのみDynamic WorkflowとProactive Loopへ拡張する。 13. よくある誤解 誤解 正確な解釈 Loopは無限実行だ 成功条件とHard stopがある制限付き反復構造だ Agentの完了報告は検証だ 外部コマンド出力、終了コード、Runtime結果が必要だ /goalがすべての権限を自動許可する 次のTurnだけを自動開始し、権限ポリシーは別物だ /loopは長期運用Schedulerだ セッション中心であり、7日で期限切れになることと実行環境の制約がある Agentが多いほど結果が良くなる 役割・観点・検証が異なるときだけ並列化の価値が生まれる すべての反復作業はLLMがすべきだ 決定論的な部分はScriptのほうが安く、再現性が高い 結論 Loop Engineeringは、AIを長時間実行させる技術ではなく、AIが間違ったときに自ら発見し、コスト上限内で修正し、危険な地点では止まるようにする制御システム設計だ。 LLMは探索、推論、実装、例外分析、代替案比較に強い。システムは実行時点、変更範囲、検証方法、終了基準、コスト上限、承認境界を担当すべきだ。この役割分担が明確であるほど、Claude Code自動化は単なるコード生成ツールを超え、再現可能で監査可能な開発運用システムに近づく。 FAQ Q. Claude CodeのLoopは、一般的なfor・whileの反復文と何が違いますか？ A. 一般的な反復文は、コードに定義された命令を決定論的に繰り返します。Claude CodeのLoopは、Agentがコードと外部状態を観察し、次の行動を推論し、ツールを実行し、結果を検証したうえで、終了条件に応じて再び作業するエージェント制御構造です。 Q. Turn-based Loopはいつ最も適していますか？ A. 短く単発で、ユーザーが結果をすぐに確認できる作業に適しています。ただし、UI・API・データベースのように検証手順が繰り返される場合は、その手順をSkillやScriptとして作成し、Claudeが同じ基準で自己検証できるようにするのがよいです。 Q. `/goal`評価モデルはファイルとテスト結果を直接確認しますか？ A. いいえ。評価モデルはツールを呼び出したりファイルを直接読んだりせず、Goal条件と会話に表れた証拠を判断します。作業Claudeがテストコマンド、終了コード、変更ファイル、失敗原因を結果に明確に残す必要があります。 Q. 良い`/goal`条件には何を含めるべきですか？ A. 測定可能な完了状態、その状態を証明するコマンドやツール、変更可能な範囲と禁止範囲、最大Turn・時間・連続失敗のようなHard stopが必要です。「きれいにリファクタリング」よりも、「テストとlintの終了コードが0で、指定パス外のDiffがない」のほうが良い条件です。 Q. `/goal`には自動の最大Turnや時間制限がありますか？ A. Goalは、評価モデルが成功を判定するか、ユーザーが`/goal clear`で中断するまで続きます。実行予算を制限するには、「最大12ターンまたは45分後に中断」のように、Goal条件にTurn・時間の条項を直接含める必要があります。 Q. `/goal`を使用すると、ツール権限も自動的に許可されますか？ A. いいえ。`/goal`は次のTurnを自動的に開始しますが、ファイル書き込み、Shell、Git、外部Connectorの権限ポリシーはそのまま維持されます。無人実行が必要な場合はAuto modeを検討しつつ、`ask`・`deny`ルールで危険な作業を別途制御する必要があります。 Q. `/loop`と`/schedule`の最大の違いは何ですか？ A. `/loop`は、現在のClaude Codeセッションとコンピューターで反復実行する短期のPolling手段です。`/schedule`はPromptとRepository、Connector、TriggerをCloud Routineとして保存し、Anthropic管理インフラで実行するため、開いているセッションや起動中のノートPCは必要ありません。 Q. コンピューターをオフにすると、`/loop`は実行され続けますか？ A. 一般的には実行され続けません。`/loop`はセッション範囲の作業であり、Claude Codeが実行中である必要があります。長期自動化にはCloud Routine、Desktop scheduled task、GitHub Actionsのような持続可能なSchedulerを使用する必要があります。 Q. 時間PollingよりEvent Triggerのほうが良い理由は何ですか？ A. 変化がないときに不要なモデル呼び出しを発生させず、実際の変更直後に実行できるためです。CI失敗、PR更新、Alertのようにイベントを発行できるシステムは、GitHub TriggerやRoutine APIで接続するほうが、コストと遅延の両面で有利です。 Q. 検証手順を`CLAUDE.md`ではなく`SKILL.md`に置く理由は何ですか？ A. `CLAUDE.md`はプロジェクト全体に常に適用する短いルールに適しており、Skillは特定の作業でのみ必要な手順とサポートファイルをまとめるのに適しています。長い検証チェックリストをSkillとして分離すれば、関連する作業でのみロードし、直接再実行できます。 Q. Dynamic Workflowは一般的なSubagent呼び出しとどう違いますか？ A. 一般的なSubagent方式では、ClaudeがTurnごとに次の作業者を選択し、結果がContextに蓄積されます。Dynamic WorkflowはJavaScript Scriptが並列実行、分岐、反復、中間結果を管理するため、大規模なMigration・Audit・クロス検証をより再現可能な形で組織できます。 Q. 複数のAgentを使用すると、常に品質は向上しますか？ A. いいえ。役割と観点が重なると、同じエラーを繰り返しながらコストだけが増える可能性があります。実装、テスト設計、セキュリティレビュー、回帰分析、Judgeのように責任を分離し、各結論に独立した証拠を求めてこそ、並列Agentの価値が生まれます。 Q. Time-basedまたはProactive Loopで重複作業はどのように防ぎますか？ A. Event ID、Commit SHA、Review Comment IDのようなIdempotency keyと最後の処理状態を保存する必要があります。すでに回答したメッセージ、すでに作成したPR、すでに処理したCommitを再処理しないというルールを検証段階に含める必要があります。 Q. 最初に自動化するLoopはどのような業務がよいですか？ A. 人が繰り返し確認するものの、危険なSide effectは少なく、完了状態を明確に測定できる業務が適しています。たとえば、PRの失敗したCI原因の要約、ドキュメントとコードの不一致検出、定められたテスト・lint検証から始め、その後、修正とPush権限を段階的に拡大していく方法が安全です。 Sources - ループエンジニアリング：ループ入門 | Claude by Anthropic: https://claude.com/blog/getting-started-with-loops - スキルでClaudeを拡張する - Claude Code Docs: https://code.claude.com/docs/en/skills - Claudeが目標に向かって作業を続けられるようにする - Claude Code Docs: https://code.claude.com/docs/en/goal - スケジュールに従ってプロンプトを実行する - Claude Code Docs: https://code.claude.com/docs/en/scheduled-tasks - ルーチンで作業を自動化する - Claude Code Docs: https://code.claude.com/docs/en/routines - 動的ワークフローでサブエージェントを大規模にオーケストレーションする - Claude Code Docs: https://code.claude.com/docs/en/workflows - Claude CodeでClaudeモデルとエフォートレベルを選択する | Claude by Anthropic: https://claude.com/blog/claude-model-and-effort-level-in-claude-code - 自動モードを設定する - Claude Code Docs: https://code.claude.com/docs/en/auto-mode-config Images - AIロボットとコード画面を中心に、循環矢印、目標、時間、安全、コスト管理のアイコンが連結された構成: https://injoys.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MTg3OSwicHVyIjoiYmxvYl9pZCJ9fQ==--cac49ec584371c2261bd3272e7574ca38ecc1f85/ChatGPT%20Image%202026%E1%84%82%E1%85%A7%E1%86%AB%207%E1%84%8B%E1%85%AF%E1%86%AF%2016%E1%84%8B%E1%85%B5%E1%86%AF%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%2006_56_28.webp - 検証、強制停止、権限ゲート、資源監視に囲まれた保護領域内のAIエージェント: https://injoys.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MTg4NiwicHVyIjoiYmxvYl9pZCJ9fQ==--e5ead4b7a604375b9c6a192eb3a981cf4c93b3c9/ChatGPT%20Image%202026%E1%84%82%E1%85%A7%E1%86%AB%207%E1%84%8B%E1%85%AF%E1%86%AF%2016%E1%84%8B%E1%85%B5%E1%86%AF%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%2007_02_56.webp --- Category: チュートリアル Source: https://injoys.com/ja/articles/claude-code-loop-engineering-guide License: cc_by Translation-Status: reviewed