対象リポジトリ: cobusgreyling/loop-engineering（MIT ライセンス）
本記事の調査時点: 2026年8月

0. この記事の要約（3行）

Loop Engineering とは、エージェントに毎回プロンプトを打つのをやめ、エージェントにプロンプトを打つシステム（ループ）そのものを設計する実践方法論。
cobusgreyling/loop-engineering は、その方法論を 7つの本番パターン + クローン可能な starter + 十数本の npm CLI + 安全設計ドキュメント に落とし込んだリファレンス実装。
目玉は Loop Readiness Score（0–100点、L0〜L3）。「うちのリポジトリはエージェントを自走させて大丈夫か？」を機械的に採点してくれる。

1. なぜ今「ループ」なのか

このリポジトリの README は、まずこの2つの引用から始まります。

Peter Steinberger: 「コーディングエージェントにプロンプトを打つのはもうやめるべきだ。エージェントにプロンプトを打つループを設計すべきだ」
Boris Cherny（Anthropic / Head of Claude Code）: 「私はもう Claude にプロンプトを打っていない。Claude にプロンプトを打って何をすべきか判断するループを走らせている。私の仕事はループを書くことだ」

レバレッジポイントが「個々のプロンプトを磨くこと」から「時間軸をまたいでエージェントを統率する制御システムを設計すること」へ移った、という主張です。

一方で Addy Osmani の警句もそのまま載せられています。「ループを作れ。ただし、ボタンを押すだけの人ではなく、エンジニアであり続けるつもりの人間として作れ」。このリポジトリは推進派の書物であると同時に、抑制の書でもある——ここが他のバズワード解説記事との決定的な違いです。

プロンプト / コンテキスト / ループの位置づけ

観点	Prompt Engineering	Context Engineering	Loop Engineering
設計対象	1回の指示文	モデルウィンドウの中身	ループ全体の制御システム
人間の関与	毎ターン必須	レスポンスごと	例外・承認ゲートのみ
状態管理	なし	セッション内のみ	セッション横断で外部永続化
自律性	なし	なし	スケジュール駆動〜完全自律まで段階的

これらは排他ではなく積層します。ループはプロンプトで構成されるため、雑なプロンプトを内包したループは「雑な仕事を高速に量産する装置」になります。

2. リポジトリの全体像

項目	内容
ライセンス	MIT
主要言語	JavaScript 約58% / TypeScript 約35% / Shell / Python
規模	約9.9k stars・1.3k forks・372コミット・コントリビューター29名（調査時点）
最新リリース	v1.6.0（Foundry funnel + loop-gate）
対象ツール	Grok Build / Claude Code / Codex / Cursor / Windsurf / OpenClaw / Opencode / Hermes / GitHub Actions

ディレクトリ構成の読み方

loop-engineering/
├── docs/          # 概念・プリミティブ・安全・アンチパターン・失敗モード・チェックリスト
├── patterns/      # 7パターンの定義 + registry.yaml（機械可読インデックス）
├── starters/      # クローンして動く scaffold（ツール別・パターン別）
├── skills/        # SKILL.md 群（triage / verifier / budget-negotiator など）
├── templates/     # STATE.md / loop-budget.md / loop-constraints.md などの雛形
├── tools/         # npm CLI 群（loop, loop-audit, loop-init, loop-cost, ...）
├── examples/      # ツール別・GitHub Actions・MCP の設定例
├── stories/       # 実運用の成功談と「何が壊れたか」の失敗談
├── LOOP.md        # このリポジトリ自身を保守するループの定義（ドッグフーディング）
├── STATE.md       # ループが毎日書き換える状態ファイル
├── loop-budget.md / loop-run-log.md / loop-constraints.md / gate.yaml

注目すべきは LOOP.md と STATE.md の存在です。このリポジトリ自身が daily triage ループで運用されており、chore (loop): daily triage update STATE.md + run log [automated] という bot コミットが日々積まれています。「自分で自分の主張を運用している（L3 dogfood）」ことが、最大の説得力になっています。

3. 語彙を揃える：Harness / Loop / 3つの負債

docs/concepts.md 系の中核概念です。ここを押さえると以降が一気に読みやすくなります。

Harness = 単一セッションのセットアップ（ツール・権限・ルール）
Loop    = Harness + スケジュール + 状態 + 検証チェーン

用語	意味	対策プリミティブ
Intent Debt（意図の負債）	エージェントは毎セッション記憶ゼロで始まる。慣習やビルド手順を毎回説明する羽目になる	Skills（一度書いて毎回読ませる）
Comprehension Debt（理解の負債）	ループが速く出荷するほど、自分が書いていないコードとの理解ギャップが広がる	ループ出力を読む運用・L1期間の確保
Orchestration Tax（統率税）	並列エージェントによるレビュー帯域・マージ競合・文脈切替のコスト	Worktrees による機械的衝突の排除
Maker / Checker	実装者と検証者の分離。実装者に自分の答案を採点させない	Sub-agents

4. 5つのプリミティブ + Memory

ツール名は違っても、能力（capability）は収束するというのがこのリポジトリの立場です。docs/primitives-matrix.md には Grok / Claude Code / Codex / OpenClaw / Opencode / Cursor / Windsurf / Hermes の8環境について、プリミティブごとの対応表が載っています。

プリミティブ	ループ内での役割	具体例
Automations / Scheduling	一定周期で仕事を発見・トリアージする心拍	`/loop`、cron / systemd、GitHub Actions、Codex Automations、`hermes cron`
Worktrees	安全な並列実行。1修正 = 1 worktree、失敗したら破棄	`git worktree`、subagent の `isolation: worktree`
Skills	プロジェクト知識の永続化（トリアージ手順・最小修正・検証手順）	`SKILL.md` / `CLAUDE.md` / `AGENTS.md`
Plugins & Connectors	実ツールへ手を伸ばす	MCP（GitHub / Linear / Slack）
Sub-agents	Maker（実装者）と Checker（検証者）の分離	implementer / verifier エージェント
+ Memory / State	会話の外側にある耐久性のある背骨	`STATE.md`、run log、budget ファイル

さらに横串の概念として Run-until-done（/goal など、検証可能な停止条件を満たすまで走り続ける仕組み）が matrix に含まれています。

5. ループの解剖

1サイクルの標準形はこうです。

リポジトリの docs/architecture-diagrams.md には、これをさらに分解した アクターレベルのシーケンス図、Run lifecycle のステートマシン（Scheduled → LoadingContext → RunningTriage → WorkingInWorktree → Verifying → AwaitingHumanGate → Applied / Rejected / Failed / BlockedBudget / IdleNoop）、L1〜L3の遷移図が用意されています。

ポイントは、「予算超過（BlockedBudget）」と「何もしない（IdleNoop）」が正規の状態として設計されていること。ループの品質は、走らせる設計より「走らせない条件」の設計で決まります。

6. 自律レベル L0 → L3

レベル	意味	現場での運用
L0	Draft — 意図を文書化しただけ	LOOP.md を書いた段階
L1	Report-only — 観察して報告するだけ	Week 1 は必ずここから。自動修正なし
L2	Assisted — worktree + verifier 付きで小さな修正を実行、人間ゲートあり	トリアージ精度を測ってから昇格
L3	Unattended-capable — denylist・予算・ゲートが実証済みの範囲で無人実行	事故やコスト急増があれば kill switch で即降格

昇格条件は「audit スコアが上がり、かつ人間が OK を出したとき」、降格条件は「インシデントまたはコスト急増」。降格経路が最初から設計に含まれているのがこのリポジトリらしい点です。

7. 7つの本番パターン

patterns/registry.yaml に機械可読な形で定義され、CLI からも参照されます。

パターン	周期	Week 1 の推奨	トークンコスト	何をするか
Daily Triage	1日〜2時間	L1 report	Low	CI・Issue・コミットの朝スキャン。最初の1本はこれ
Issue Triage	2時間〜1日	L1 propose-only	Low	Issue の重複排除・優先度付け・ラベル提案
Changelog Drafter	1日 or タグ	L1 draft	Low	マージ済み PR からリリースノート草案。低リスク高レバレッジ
Post-Merge Cleanup	1日〜6時間	L1 off-peak	Low	TODO・非推奨・技術的負債の後追い。夜間に小さな PR
Dependency Sweeper	6時間〜1日	L2 patch-only	Medium	依存更新・CVE パッチ。メジャー更新は人間ゲート
PR Babysitter	5〜15分	L1 watch	High	PR のレビュー・CI・rebase 支援。判断は人間の席に残す
CI Sweeper	5〜15分	L2 cautious	Very high	失敗 CI への最小修正。flaky 分類と早期エスカレーション必須

迷ったら docs/pattern-picker.md（インタラクティブ版もあり）で診断できます。

複数ループを併走させるときの優先順位は、CI Sweeper → PR Babysitter → Dependency Sweeper → Post-Merge / Changelog（オフピーク）→ Daily Triage（レポート）の順で整理されています（docs/multi-loop.md）。

8. CLI ツール群 — このリポジトリの実体

8.1 フロントドア（推奨）

# 1コマンドで scaffold + Loop Ready スコア表示
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok

# audit + sync + ファイル検査を束ねて「次にやるべき3つ」を提示
npx @cobusgreyling/loop doctor .

# コスト見積り / バッジ / Day-2 ダッシュボード
npx @cobusgreyling/loop cost --pattern daily-triage --level L1
npx @cobusgreyling/loop badge .
npx @cobusgreyling/loop status .

--tool は grok / claude / codex / opencode を切り替え可能。旧来の npx @cobusgreyling/loop-init . も引き続き動作します（フォークは変更不要）。

8.2 個別 CLI 一覧

パッケージ	役割
`@cobusgreyling/loop`	統合フロントドア（init / doctor / status / audit / cost）
`@cobusgreyling/loop-audit`	Loop Readiness Score（0–100 / L0–L3）、改善提案、README バッジ
`@cobusgreyling/loop-init`	starter・budget・run-log・constraints の scaffold
`@cobusgreyling/loop-cost`	パターン × 周期 × レベルごとのトークン消費見積り
`@cobusgreyling/loop-sync`	`STATE.md` と `LOOP.md` のドリフト検出
`@cobusgreyling/loop-context`	長時間実行向けメモリ管理 + サーキットブレーカー
`@cobusgreyling/loop-worktree`	修正試行ごとの隔離 worktree 管理（ロック・待ち行列付き）
`@cobusgreyling/loop-gate`	`gate.yaml` に基づく denylist / auto-merge allowlist の機械的強制
`@cobusgreyling/loop-sandbox`	一時 worktree による隔離実行 + パッチ捕捉
`@cobusgreyling/loop-mcp-server`	パターン・スキル・状態を MCP 経由で参照
`loop-action`	ループを CI で回す GitHub Composite Action

loop-gate と loop-context は 終了コード2でエスカレーション、0で続行という同じ規約を採用しているため、制御スクリプトから素直にチェーンできます。この「規約を揃える」設計は地味ですが実装上とても効きます。

9. loop-audit を深掘りする（本リポジトリの核心）

loop-audit は「Scan → Signal → Score」のパイプラインで、リポジトリを走査して 15以上のシグナルの有無を判定し、重み付けして 0–100 のスコアと L0–L3 のレベルを返します。主観評価を決定論的アルゴリズムに置き換えるのが狙いです。

使い方

npx @cobusgreyling/loop-audit .            # 人間向け出力
npx @cobusgreyling/loop-audit . --json     # 機械可読
npx @cobusgreyling/loop-audit . --md       # Markdown レポート
npx @cobusgreyling/loop-audit . --suggest  # テンプレからのコピーコマンド + 改善ヒント
npx @cobusgreyling/loop-audit . --badge    # README 用バッジ

スコアが 40 未満なら終了コード 2。ループが成熟してきたら CI ゲートとして使えます。

チェックされるシグナル（v1.7+）

カテゴリ	シグナル	判定内容
状態	State file	`STATE.md` またはパターン別の状態ファイル
スキル	Triage / Verifier skill	`loop-triage` / `loop-verifier` 等を `.grok/skills`・`.claude/skills` 等から検出
設定	LOOP.md / AGENTS.md / CLAUDE.md	周期・上限・ハンドオフ・プロジェクト規約
安全	Safety docs	`safety.md` と LOOP.md 内のゲート記述
自動化	`.github/` + workflows	ドッグフーディングの有無
接続	MCP / connectors	設定ファイルまたは記述
隔離	Worktree evidence	ドキュメント上の隔離パターン
インデックス	`patterns/registry.yaml`	機械可読インデックス
コスト可観測性	`loop-budget.md` / `loop-run-log.md` / LOOP.md の budget 節	トークン上限・kill switch・追記専用の実行履歴
権限	Least-privilege tool scope	`SKILL.md` の `allowed-tools` 等、役割に必要な権限のみか
停滞検知	Stall / no-progress detection	サーキットブレーカー、台帳、最大試行回数ルール
退避	Human-escalation path	いつ止めて人間に渡すかの定義
動的証拠	`loopActivity`	状態ファイルの「Last run」、ループ関連コミット、スケジュール済みワークフロー、実行ログ
ランタイム	Harness Runtime（v1.7）	`.foundry/stack.yaml`、セッション/トレース等

レベル判定ロジック

L0：スコア 38 未満。意図は文書化されているがプリミティブが欠けている状態。
L1：stateFile と triage skill が必須。
L3：verifier + state + コスト可観測性（budget・run log・LOOP.md の budget 節）に加えて、実際にループが動いた証拠が必要。

最後の条件が重要です。「ファイルが disk 上にあるだけ」では L3 にならない——設計書ではなく運用実績を要求する、という思想が採点器に埋め込まれています。

10. 5分クイックスタート（実コマンド）

# 1. scaffold（Loop Ready スコアが自動表示される）
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok

# 2. ヘルスチェック（audit + sync + ファイル検査 → 次の3手）
npx @cobusgreyling/loop doctor .

# 3. コスト見積り
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

# 4. スコアが 空 → L1 → L2 と上がる様子をデモで確認
bash scripts/before-after-demo.sh

# 5. まずは report-only で回す（Grok の例）
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

loop-cost は各見積りを4シナリオで出します：早期終了（no-op）／フルトリアージ／毎回アクション（最悪ケース）／レベル別の現実的ブレンド。「最悪ケースの日次コスト」を先に見てから周期を決められるのが実務的です。

starter の中身

starter	対応ツール	配置先
`minimal-loop`	Grok	`.grok/skills/`
`minimal-loop-claude`	Claude Code	`.claude/skills/` + `.claude/agents/`
`minimal-loop-codex`	Codex	`.codex/skills/` + `.codex/agents/`
`minimal-loop-opencode`	Opencode	`skills/` + `AGENTS.md`

L2 系（pr-babysitter / ci-sweeper / dependency-sweeper / post-merge-cleanup / changelog-drafter / issue-triage）も各ツール向けに用意されています。

11. 安全設計 — ここが一番読む価値がある

docs/safety.md と SECURITY.md は「ループを本番オペレーターとして扱え」という前提で書かれています。

パス denylist

人間の承認なしにループが編集してはいけないパス群が明示されています。

.env / .env.*
**/secrets/** / **/credentials/**
**/*_key* / **/*_secret*
.terraform/**
k8s/production/**
**/migrations/**   （明示的なマイグレーションループ以外）
auth/** / payments/** / billing/**

重要なのは、この denylist を「スキルに書いて祈る」のではなく loop-gate で機械的に強制する設計になっている点です。

loop-gate check --action <type> --paths <changed files>
# 終了コード 2 = エスカレート / 0 = 続行

自動マージポリシー

デフォルトは auto-merge なし。許可する場合も範囲は極小です。

許可されうる	許可されない
コメント・ドキュメントの typo 修正	挙動を変える変更
テストファイル限定の lint 自動修正	依存バージョンの更新
import の並び替え	ロックファイルの変更
allowlist 済み `docs/` 配下の設定	denylist 該当パス全般

MCP コネクタの最小権限

コネクタ	Read	Write
GitHub	issues, PRs, checks	コメント・ラベルのみ（既定でマージ不可）
Linear	チームの Issue	コメント・ステータス（削除不可）
Slack	チャンネル履歴	`#loop-escalations` への投稿のみ
Database	—	本番書き込みは一切禁止

無人運用のリスクと緩和策

リスク	緩和策
悪意ある依存の自動マージ	denylist + verifier + 初週は auto-merge 禁止
MCP の過剰権限	L1 は read-only、書き込みは PR コメントに限定
プロンプト経由の秘密情報流出	認証情報パスを denylist、STATE.md に秘密を書かない
無限修正ループによる予算消尽	試行回数のハードキャップ、LOOP.md に kill switch
ループ産 PR のサプライチェーン	allowlist 外は必ず人間レビュー

12. アンチパターン（設計時の地雷）

docs/anti-patterns.md から主要なものを。

#	アンチパターン	なぜ壊れるか	代わりにやること
1	同一エージェントが実装と検証を兼ねる	確証バイアス。弱いテストが追認される	verifier を分離。検証者の既定スタンスは REJECT
2	試行回数の上限なし（「CI が緑になるまで」）	無限修正・トークン燃焼・誤った修正のマージ	上限3回程度 → 文脈付きでエスカレート
3	トリアージ出力が散文	ループが優先度をパースできず、人間も STATE.md を読まなくなる	構造化 Markdown + 明示的な「Suggested loop action」
4	L1 の品質を確認する前に L3	悪いシグナルの上で行動し、理解の負債が爆発	初週は report-only。トリアージ精度を計測してから L2
5	スキーマなしの共有状態	状態の腐敗・矛盾するアクション・ゴースト項目	パターンごとに状態ファイルを分離 + prune ルール
6	MCP に write-everything 権限	1回の誤判断の爆発半径が巨大	L1 は read-only。信頼を得てから拡張
7	kill switch がない	通知疲れ・予算超過・週末のインシデント	LOOP.md と budget テンプレに停止条件を明記

13. 失敗モードカタログ（運用時の地雷）

docs/failure-modes.md は、実際に起きた事故をインシデント形式で分類しています。

深刻度：S1 = 時間とトークンの浪費 / S2 = 誤ったコードのマージ・通知疲れ等の実害 / S3 = セキュリティ・データ損失・本番障害。

失敗モード	症状	深刻度	主な緩和策
Infinite Fix Loop	同じ PR / CI に5回以上の自動修正が入り収束しない	S2	試行上限 → エスカレート、verifier を別モデル化、flaky はコード修正でなく隔離
State Rot	STATE.md がマージ済み PR やクローズ済みチケットを参照し続ける	S1→S2	毎回 prune、Last run タイムスタンプ、ID を実 API と突合
Verifier Theater	verifier は「承認」するが CI で落ちる／レビューで明らかなバグ	S2	verifier にテスト実行と出力報告を義務付け、指示を「却下理由を探せ」に、無人ループでは強いモデルを充てる
Notification Fatigue	5分おきの通知でチームが bot をミュート	S1→S2	通知の集約・閾値設計

「State Rot が S1 から S2 に昇格する」——つまりゴーストに対してループが行動を起こした瞬間に実害になる、という記述の解像度が高く、ここだけでも読む価値があります。

14. エコシステムとしての位置づけ

このリポジトリは単体で完結せず、5層スタックの「設計層」として位置づけられています。

memory-engineering → loop-engineering → harness-foundry → outerloop → fleet-engineering
     (永続化)            (パターン)         (ランタイム)       (判定)      (集団統治)

層	得られるもの
Memory	記憶のティア分け、想起予算、Memory Ready スコア
Design（本リポジトリ）	パターン、starter、Loop Ready スコア
Runtime（harness-foundry）	バージョン管理されたハーネス、トレース、進化
Govern（outerloop）	証拠 → 評決 → 説明責任
Fleet	レジストリ、受信箱、予算、kill switch

スケール方針も明快です。セッション横断で忘れるなら memory 層を足す。チームで多数のループが走り出したら fleet 層を足す。 Loop Ready 80点以上になったら、loop-init --with-foundry でランタイム化する導線が CLI 側から自動で提示されます。

15. 導入ロードマップ（実務向けの現実解）

時期	やること	判断基準
Day 1	`loop init` → `loop doctor` → `loop cost` でスコアと最悪コストを把握	L0 なら LOOP.md と STATE.md から
Week 1	Daily Triage を L1 report-only で固定。auto-fix は禁止	トリアージ出力を毎朝人間が読む
Week 2–3	トリアージ精度を計測。denylist を `gate.yaml` に落とし、`loop-gate` を配線	誤検知率が許容範囲か
Week 4〜	verifier を分離して L2 へ。worktree 隔離と試行上限を必須化	audit スコアと run log の実績
その後	allowlist 内に限り L3。kill switch と予算上限を先に整備	動的証拠（loopActivity）が揃っているか

16. 正直な限界（README の Caveats より）

このリポジトリが良心的なのは、宣伝の隣に限界を並べていることです。

ループは判断を増幅する。良い判断も悪い判断も等しく増幅される。
サブエージェントと長時間実行でトークンコストは容易に爆発する。
検証責任は依然としてあなたにある。
無人ループは無人のまま間違える。
ループが出荷したコードを読まない限り、理解の負債は加速度的に増える。
同じループを2人が回して正反対の結果になることがある。ループはそれに気づかない。あなたは気づける。

つまりこのツール群は、「エンジニアの判断力を不要にするもの」ではなく、「判断力がボトルネックであることを可視化するもの」です。

17. まとめ

読者タイプ	まず読む/触るべきもの
とりあえず動かしたい	`npx @cobusgreyling/loop init .` → `loop doctor .`
概念を理解したい	`docs/concepts.md`、`docs/primitives.md`
自チームの現状を測りたい	`loop-audit . --suggest --md`
本番導入の可否を判断したい	`docs/safety.md`、`docs/anti-patterns.md`、`docs/failure-modes.md`
複数ループを運用中	`docs/multi-loop.md`、`docs/operating-loops.md`

Loop Engineering の本質は「自動化」ではなく 「発見・実行・検証・記憶・エスカレーション」を明示的に設計すること です。単なる cron ジョブとの違いは、状態を持ち、検証され、境界が定義され、停止条件を持っているかどうか。このリポジトリは、その境界線を引くための最も具体的な教材です。

参考リンク

リポジトリ本体: https://github.com/cobusgreyling/loop-engineering
インタラクティブ・ショーケース / パターンピッカー: https://cobusgreyling.github.io/loop-engineering/
loop-audit（npm）: https://www.npmjs.com/package/@cobusgreyling/loop-audit
安全ガイド: docs/safety.md ／アンチパターン: docs/anti-patterns.md ／失敗モード: docs/failure-modes.md
原典エッセイ: Cobus Greyling「Loop Engineering」（Substack）、Addy Osmani「Loop Engineering」

本記事の数値（stars、バージョン等）は 2026年8月時点の調査結果です。リポジトリは日次ループで更新されているため、最新の状態は必ず一次ソースでご確認ください。