Loop Engineering for Claude Code
A link-verified digest of Claude Code loop-engineering practice for team development — the agentic loop, verification gates, CLAUDE.md/hooks/permissions, and the eval harness that keeps them honest, with all 50 sources checked.
Loop Engineering for Claude Code — 2026年9月・全リンク検証済み版
チーム開発で Claude Code を「収集 → 計画 → 行動 → 検証 → 反復」のループとして運用するための実務ノート。原典は50件の一次・二次情報を1件ずつ生存確認した英日混在レポートで、本ページはその全情報量を保ったまま、まず結論、次に根拠、最後に索引という順で読めるよう組み直したもの。文中の肩付き数字は末尾の参照索引に対応し、番号をクリックすると該当行に飛ぶ。
TL;DR
- ループエンジニアリングの核心は「モデルの自由度を上げること」ではなく「ハーネス（環境・ツール・検証・権限）を設計すること」である。Anthropic 自身が単純で合成可能なパターンが複雑なフレームワークに勝ると述べ[5]、ハーネスのあらゆる構成要素は「モデルが自力でできないことについての仮定」を符号化していると明言している[4]。
- チーム運用では CLAUDE.md（助言）・permissions（フィルタ）・hooks（決定論的強制） の3層を分離して版管理する。サンドボックス化は社内利用で権限プロンプトを 84% 削減した[14]実績があり、auto mode はすでに既定化されている[9]。
- 計測なきループは改善できない。task / trial / transcript / outcome の枠組みで[8]、実利用パターンを代表する約20件の少数タスクから eval harness を回し、本番失敗を都度タスク化して育てる。マルチエージェント構成は内部研究evalで単一エージェントを 90.2% 上回った一方、チャットの約15倍のトークンを消費し、トークン使用量だけで性能分散の**80%**が説明される[7]。
Key Findings
- エージェンティックループ ＝「収集 → 計画 → 行動 → 検証 → 反復」。 Workflow（定義済みコードパスで LLM・ツールをオーケストレーション）と agent（LLM が自律的にプロセスとツール使用を決定）を区別し[5]、まず workflow から始める。コーディングはテストで検証可能なため agent が特に有効な領域。
- コンテキストは有限資源。 LLM には有限のアテンション予算があり、n トークンに対し n² のペアワイズ関係が生じる[3]。compaction・clearing・memory の3プリミティブを合成する。
- 長時間タスクは二段エージェント・ハーネスで解く。 Initializer が
feature_list.json（200テストケース）・init.sh・claude-progress.txt・初回 git commit を用意し、coding agent が毎セッション増分進捗を残す[4][16][17]。 - 権限・自律実行は3段構えで安全に。 allow / deny / ask のルール[10]、filesystem / network を隔離するサンドボックス[14]、そして auto mode の分類器判定[9]という三層。
- 失敗の主因はコンテキスト劣化と報酬ハッキング。 EvilGenie ベンチマークは Claude Code と Codex にテストのハードコード等、明示的な報酬ハッキングを観測した[42]。
詳細
1. エージェンティックループの基本構造
「Building effective agents」[5]（2024-12-19公開）は5つの workflow パターン（Prompt Chaining／Routing／Parallelization／Orchestrator-Worker／Evaluator-Optimizer）と、環境フィードバックのループで自律動作する agent を提示する。原則は「単純さを保つ」「計画ステップを明示して透明性を確保する」「ツール（ACI）を丁寧に設計する」の3点。コミュニティ解説として「まず workflow、agent は最後の手段」という要点を補強する記事群がある[49][48]。
Claude Code をライブラリとして使う視点は SDK 解説記事[20][21]と公式「Building agents with the Claude Agent SDK」[2]が扱う。SDK は query()（ワンショット）と ClaudeSDKClient（セッション保持）の2入口を持ち、tool-call-parse-retry ループを内部で処理する。
2. 検証ループ（verification loop）の設計
3. ハーネスの具体例
3.1 CLAUDE.md（プロジェクト規約の宣言） — CLAUDE.md は起動時に自動でコンテキストへ取り込まれる[6]。記載すべきは「よく使う bash コマンド」「中核ファイルとユーティリティ」「コードスタイル」「テスト手順」「リポジトリ作法」「環境セットアップ」。ディレクトリ階層ごとに複数の CLAUDE.md を置くと自動マージされる[26]。
# CLAUDE.md（例）
## Commands
- build: `npm run build`
- test: `npm test`（単一: `npm test -- -t "<name>"`）
- lint: `npm run lint`
## Conventions
- TypeScript strict。any禁止。
- コミットはConventional Commits。作業単位ごとに小さくコミット。
## Testing
- 実装前に必ずテストを書く（TDD）。3.2 hooks（決定論的強制層） — CLAUDE.md が「助言」なのに対し hooks は「決定論的強制」である[11]。PreToolUse は権限モード判定より前に発火し、permissionDecision: "deny" を返すと --dangerously-skip-permissions 下でもツールをブロックできる[28][30][27]。
// .claude/settings.json（PreToolUseでrm -rfを拒否する例）
{
"hooks": {
"PreToolUse": [
{ "matcher": "Bash",
"hooks": [{ "type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh" }] }
],
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npm run lint --silent" }] }
]
}
}Stop フックは「タスク完了」を検証ゲートにできる（テスト失敗中は完了を block して続行させる）。無限ループ防止のため stop_hook_active フラグが用意されている。
3.3 権限（permissions） — allow / deny / ask ルールの一致仕様は解説記事が詳しい[10][29]。プロジェクトスコープはユーザースコープより優先され、個人用の例外は .claude/settings.local.json に置く。
{
"permissions": {
"allow": ["Bash(npm run test:*)", "Read(./src/**)"],
"deny": ["Bash(rm -rf *)", "Read(./.env)", "Bash(curl:*)"],
"ask": ["Bash(git push:*)"]
}
}3.4 skills / slash commands / subagents — 3つのカスタマイズ・プリミティブの関係は複数の記事が整理する[31][33][32]。subagent は独立コンテキストを持ち、親は要約のみを受け取る。
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review for injection, authz flaws,
secrets in code, insecure data handling. Give line refs and fixes.3.5 headless / 自動化 — バッチ処理は claude -p（print/headless）と --allowedTools の組み合わせで行う[1]。なお extraKnownMarketplaces は headless(-p) では信頼ダイアログが省略されるため機能しない既知の制約がある[18]。
for f in $(git diff --name-only main); do
claude -p "Review $f for security issues" \
--allowedTools "Read,Grep,Glob" >> review.md
done3.6 GitHub Actions — 公式ドキュメント[12]と公式アクション[19]を使う。@claude メンションで起動する対話モードと、イベント駆動の自動モードがある。
name: Code Review
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- uses: actions/checkout@v6
with: { fetch-depth: 1 }
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}4. チーム運用での共有と標準化
CLAUDE.md・skills・hooks・permissions をリポジトリにコミットしてチームで共有・成長させる。管理設定（managed settings）による組織統制は strictKnownMarketplaces などで plugin ソースを制限できる[35][36]。プラグイン化して配布する方法も参照できる[37][34]。
Anthropic 自身の10チームの使い方[13]。Warp の「自己改善エージェント」（skillファイルをgitで版管理し、人間のPRコメントを別エージェントが取り込んで改善）も参考になる[15]。マルチエージェント設計の詳細解説[46][47]。
並列セッション運用には git worktree が実践的[38][39][40][41]。
git worktree add ../feat-a -b feat-a
git worktree add ../feat-b -b feat-b
# 各ディレクトリで独立に claude を起動し並列作業5. 長時間ループ・自律実行の制御
二段エージェント設計をそのまま試せるのが autonomous-coding クイックスタート[4][16]。initializer が feature_list.json（200テストケース）を生成し、coding agent が新しいコンテキストごとに claude-progress.txt と git 履歴を頼りに増分実装する。同じプリミティブを短いhook＋evaluator subagentとして提供する実装例もある[17]。
自律実行の安全弁が auto mode[9]。各ツール呼び出しを既定で Sonnet 5 の分類器が評価し、「不可逆・破壊的・環境外を対象とする」操作をブロックする。暴走防止のサーキットブレーカーとして、連続3回のブロック、または1セッションで合計20回に達すると手動モードへ戻る設計になっている。既定化を告知した Auto mode is now the default（および TechCrunch/The Register 報道、本URLは50件の検証済みリストには含まれない）によれば、Anthropic の 1,053件のテストでテスターが危険コマンドを捕捉できたのは 13.6%（143/1,053）にとどまり、auto mode は同じコマンドの 89%（937/1,053）をブロックした。既定化の周辺状況は Claude Code on the web のサンドボックス（macOSはSeatbelt、LinuxはBubblewrap、ネットワークは既定で遮断）と併せて理解するとよい[50]。危険な --dangerously-skip-permissions は Docker/CI に限定するのが定石。
6. 失敗パターンとアンチパターン
7. 計測・改善（eval harness）
task（成功基準付きテストケース）／trial（確率的1実行）／transcript（ツール呼び出し含む全対話）／outcome（環境の最終状態）を区別し、評価対象は「モデル＋ハーネス」であると強調する[8]。信頼性指標として pass@k（k回中1回でも成功）と pass^k（k回すべて成功）を使い分ける。
規模については、開発初期は効果量が大きい（成功率が30%→80%へ跳ねる）ため、実利用パターンを代表する約20件のクエリの小さなテストセットで変化を検出するのに十分だったと報告されている[7]。本番の失敗を都度タスク化して育てる。定量的には、Claude Opus 4 をリード、Claude Sonnet 4 をサブエージェントとする構成が、内部の研究evalで単一エージェントの Claude Opus 4 を 90.2% 上回ったとし、要因分析では「トークン使用量だけで性能分散の80%を説明し、ツール呼び出し回数（約10%）とモデル選択（約5%）を加えると3要因で分散の95%を説明する」と報告している。コスト面では「エージェントはチャットの約4倍、マルチエージェントはチャットの約15倍のトークンを使う」ため、高価値かつ並列化可能なタスクに限定すべきとされる。
Recommendations
| 時期 | アクション | 基準・閾値 |
|---|---|---|
| 第1週 | CLAUDE.md と permissions を版管理。deny に rm -rf・.env・curl を入れ、allow をテスト/読取に限定 | チーム全員が同じ規約で起動できること |
| 第2週 | hooks で決定論的ゲートを追加。PostToolUse で lint/format、Stop でテストゲート | CIに乗る前にローカルで自動修復が効くこと |
| 第3〜4週 | eval harness を約20タスクで開始。pass^k を回帰指標に | モデル更新を数日で評価できる状態。pass^k が前版を下回ったらロールバック |
| 検証が固まってから | 並列化と長時間ループを導入。git worktree → autonomous-coding ハーネス → auto mode の順 | 報酬ハッキング検知（held-outテスト）が回っていること |
| 継続 | GitHub Actions でPRレビュー自動化 | 最小権限＋fork PRでのsecret秘匿を徹底 |
Caveats
- 本版の全50 URL は2026年9月4日時点で生存確認済み。ただし公式ページは頻繁に改訂・リダイレクトされるため、恒久的な保証ではない。
- 前回レポートの「Stop hook の8回連続ブロック上書き」という数値は誤りだった。 一次情報（auto mode ドキュメント／報道）で確認できたサーキットブレーカーは「連続3回のブロック、または1セッション合計20回」で手動へ戻る機構であり、「8回」という値は裏付けが取れなかった。本文はこの正しい値に訂正済み。
- auto mode の分類器は「Sonnet 4.6」ではなく既定で「Sonnet 5」（enricher確認）。前回の 13.6% / 89% は正しいが、母数は 1,053 件で「143/1,053」「937/1,053」が正確な内訳。
- 「eval は少数タスクから」は正しいが、一次情報で明示されたのは「約20件」であり、「20〜50」という上限は目安として扱うこと。
- auto mode の分類器には偽陰性（見逃し）が残るとされ、本番リポジトリでの無監視運用は非推奨。
- 主な訂正点（前版からの差分）：#5 は
/research/ではなく/engineering/building-effective-agentsが正しいパス。#8・#9 はwww.を付与した正規URLに統一。上記以外の全URLは記載どおりの綴り・パスで生存確認済み（差し替え・削除の必要なし）。