対象リポジトリ: 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月時点の調査結果です。リポジトリは日次ループで更新されているため、最新の状態は必ず一次ソースでご確認ください。