Claude Code 自律開発ワークフロー × ループエンジニアリング 設計ノート

0.全体像 — 1 issue を回す「内側パイプライン」#

ある機能要求を、計画詰め → 仕様 → タスク分解 → 並列実装 → 検証 → マージ まで流す1本のパイプライン。

/grill-with-docs ○○したい
   → Q/A …(反復)… → PRD → ISSUES
        → (issue ごとに) Worktree #1..#n（並列）
              → テストレビュー（実装前に人間が確認）
              → /goal ループ（完了条件まで自走）
              → PR
   → 人間がチェックして承認・マージ

要点：上半分（grill → PRD → issues）は既に公開スキルとして存在する。再発明せず install してよい。

mattpocock/skills、Claude Code /goal（後掲リンク）

1.ループは「二重」ではなく「四重」#

トリガー→実施→判定の二重ループは、より大きな4層スタックの一部にすぎない（LangChain / Sydney Runkle の整理）。

• L1 エージェントループ — モデルがタスク完了までツールを呼び続ける。仕事を片付ける層。
• L2 検証ループ — 出力を rubric で採点し、足りなければフィードバック付きで差し戻す。採点役は決定論的（テスト実行・リンク解決確認）でも別モデルの judgeでもよい。/goal の「別モデルが完了判定」がこれに当たる。
• L3 オーケストレーション/オートメーション — cron・webhook で仕事を発見して配る。図でいう外側ループ（トリガー→オーケストレータ）。
• L4 ヒルクライミング — 各実行が残す trace（行動・ツール呼び出し・採点フィードバックの記録）を分析エージェントが読み、harness 自体（プロンプト・採点基準）を書き換える。戻り矢印は先頭に戻るだけでなく、L1 の内側を直接更新する。

含意：よくある図は L1〜L3 で閉じており、L4 が抜けている。L4 を足さないとループは「回るが賢くならない」。価値が複利で効くのは L3・L4。設計に trace ログ + 定期的な改善パスを1本足すべき。

Sydney Runkle, "The Art of Loop Engineering"（LangChain）

2.ループはどこに住むか（3層）#

「ラップトップを閉じて回す」は /loop を端末で走らせることではない。ループは記憶・検証・境界を持つ反復プロセスで、スケジュール・状態永続化・並列隔離・実ツール接続の「住む場所」が要る。

• Tier A 端末ハーネス（個人/小チーム）— Claude Code が /loop・スキル・サブエージェント・worktree・MCP を一箇所で提供。多くの場合これで十分。
• Tier B プラットフォームランタイム（本番/マルチテナント）— 午前3時に走り、実行途中のクラッシュを生き延び、数日の人間承認を待ち、各エージェントに隔離マシンを与える必要が出たら、この領域。ハードウェア隔離 microVM、チェックポイント付き durable execution、エージェントサーバ上の cron、人間介入での一時停止と再開。Claude Code 単体なら GitHub Actions、本格運用なら LangSmith 等。
• Tier C エディタ/軽量 — 既にエディタに固定されている、または full なエージェント基盤なしに cron/webhook だけ欲しい場合。

cron の2種（盗む価値あり）：

• stateful cron … 毎回同じ thread で「昨日」を覚える（夜間リサーチ・履歴付き監視）≈「STATE.md に追記」
• stateless cron … 毎回新規 thread（バッチトリアージ・一回限りの掃引）≈「リポジトリを読んで終了」

Cobus Greyling, "Loop Engineering Playbook"

3.部品マッピング（Addy Osmani の「5＋1」）#

ループに必要なのは5つの部品＋状態を覚える1か所。

モデルは実行間で全部忘れる。だからメモリはコンテキストではなくディスクに置く。エージェントは忘れるがリポジトリは忘れない。

Addy Osmani, "Loop Engineering"

4.自作すべき .claude/ 構成#

① test-review スキル（ゲート）

issue から「自然言語のテスト仕様 + 失敗するテスト（red）」だけを書き、実装せず停止して人間レビューを待つ。図の「実装前にテストをレビュー」の本体。

---
name: test-review
description: issueから失敗テストとテスト仕様を書き、実装せず停止して人間承認を待つ
invocation: user
allowed-tools: Read, Grep, Glob, Write, Bash(npm test:*)
disable-model-invocation: true
---
1. 対象issueと CONTEXT.md / ADR を読む
2. 受け入れ条件を TEST_PLAN.md（自然言語テストケース一覧）に落とす
3. 実装は一切せず failing test だけを書き、red を確認する
4. ここで必ず停止。「TEST_PLAN.md を人間が承認したら /goal を起動」と明示して終了

② freeze-tests フック（最重要）

/goal ループ中、エージェントは「テストを弱めて pass させる」方向へ逃げる。テストファイルへの Edit/Write を PreToolUse フックで拒否し、レビュー済みテストの不変性を強制する。これが無いと「テストが green」は自己採点になる。

// settings.json（実装フェーズのみ有効化）
"hooks": { "PreToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{ "type": "command",
    "command": "case \"$CLAUDE_TOOL_FILE\" in *.test.*|*_test.*) exit 2;; esac" }]
}]}

③ implementer / verifier サブエージェント

.claude/agents/ に役割を分離。verifier は編集権限なし・別モデルで、テスト/スペック照合だけを行う。無人で回るからこそ、信頼できる検証役だけが「歩いて立ち去れる」唯一の根拠になる。

④ orchestrator（issue → worktree ファンアウト）

to-issues の出力を読み、衝突しない issue 群に worktree + ブランチを作って test-review → 人間承認 → /goal → open-pr を回す。「衝突しない範囲」は自動判定しきれないので、issue が触るファイル/モジュールの重複チェックを挟むか、共有モジュールを触る issue は直列化する。

⑤ open-pr スキル

push → gh pr create → issue 紐付け。push と PR 作成は不可逆の公開操作なので実行前に必ず停止して確認（自動 push しない）。最終 diff は /review で。

⑥ STATE.md（ループの背骨）

worktree の外に1つ置き、「試したこと/通ったこと/未着手」を記録。毎サイクルここから再開する。これが無いと外側ループは毎回ゼロから再発見して破綻する。

⑦ trace ログ + L4 改善パス

各実行の trace を残し、定期的に分析パスを走らせてスキル本文・プロンプト・採点基準を直す。これが §1 の L4。

5.コスト/安全のデフォルト値#

• トリアージは安く：シグナルへの1モデルパス。毎 cron tick で implementer＋verifier を回さない。
• サブエージェントは状態が「着手可能」と言ったときだけ spawn する（5分ループにフルの maker/checker を毎回付けると上限プランを朝食前に焼き尽くす）。
• 項目ごとに試行を上限化：3回でダメなら人間にエスカレーション。
• 反復ごとに tool-call 予算を切る。予算を使い切っても進展がないなら、それを失敗シグナルとして別戦略へ。
• 反復前にログを圧縮して作業メモリへ要約（例:「fix A 失敗:TypeError / fix B 失敗:同 / fix C 部分成功:エラー解消もテストは47行目で失敗」）。
• 回復可能エラー（構文・import 漏れ）とハードブロッカー（認証情報欠如）を区別する。

Cobus Greyling（コスト/安全デフォルト）、MindStudio（ループの破綻モードと対策）

6.容赦ない注意点#

1. 「auto 承認なし」と人間ゲートは矛盾する。 完全自動＋自作テスト＋人間ゲート無しは自己採点ループになる。解は「実装の各ターンの承認だけ省き、テスト仕様の確定とマージは人間に残す」。加えて (a) テスト凍結 (b) 編集権限のない verifier (c) マージは人間、の3点を外さない。
2. /goal の判定が真偽を出せるのは機械的条件のみ（tests green && lint clean && build exit 0）。「正しい」「きれい」は判定不能。
3. 「数百〜数千エージェント」は理論値。 worktree は機械的衝突を消すが、上限はツールではなくあなたのレビュー帯域とコスト。
4. 理解の腐敗。 ループが速くコードを吐くほど、存在するものと自分が把握しているものの差（comprehension debt）が速く広がる。"done" は主張であって証明ではなく、検証は人間に残る。
5. 弱いテスト基盤では全体が空回りする。 信頼できるテスト/型/ビルドが前提。greenfield では先に基盤整備が要る。

同じループを2人が組んでも、深く理解している作業を速める人と、理解を避けるために使う人で正反対の結果になる。ループはその違いを知らないが、あなたは知っている。

Addy Osmani（comprehension debt / cognitive surrender）

7.図（HTML 化時に SVG で描く 3 枚）#

配色は共通：teal = ループ/自動、amber = 人間/ゲート/警告。角丸の矩形ノード、細い罫線、日本語フォント。

図A：内側パイプライン（縦フロー）

/grill-with-docs → Q/A…→PRD→ISSUES → 横に並ぶ Worktree #1..#n → 各列 テストレビュー(amber) → /goal(teal・循環アイコン) → PR → 最下段に幅いっぱいの 人間が承認・マージ(amber)。テストレビューと最終マージを amber で強調。

図B：4重ループ（同心の入れ子）

中心から外へ L1 エージェント → L2 検証 → L3 オーケストレーション → L4 ヒルクライミング。各層に役割ラベル。L4 から内側へ伸びる「harness を直接書き換える」戻り矢印を1本描く。L1〜L2 を teal、L4 を amber 寄りに。

図C：3層ランタイム

Tier A 端末 / Tier B プラットフォーム / Tier C エディタ を3カラム。Tier B に「sandbox 隔離・durable execution・cron」を、下部に stateful cron（≈STATE.md 追記）と stateless cron（≈読んで終了）の対比を添える。

8.出典（原文はここで読む）#

• Addy Osmani, "Loop Engineering" — https://addyosmani.com/blog/loop-engineering/
• Cobus Greyling, "Loop Engineering Playbook" — https://cobusgreyling.substack.com/p/loop-engineering-playbook
• Sydney Runkle, "The Art of Loop Engineering"（LangChain）— https://www.langchain.com/blog/the-art-of-loop-engineering
• MindStudio, "What Is Loop Engineering?" — https://www.mindstudio.ai/blog/what-is-loop-engineering-ai-coding-agents
• mattpocock/skills（grill-with-docs / to-prd / to-issues）— https://github.com/mattpocock/skills
• Steering Claude Code: skills, hooks, subagents（Anthropic）— https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
• Claude Code 公式ドキュメント — https://docs.claude.com/en/docs/claude-code/overview