Loop Engineering

Design the system that prompts your agents — cobusgreyling/loop-engineering

1 — 概要
何か

Loop Engineering は、個別のプロンプトを書く代わりに、エージェントを反復的に動かす制御システム（ループ）を設計する実践の参照集。Grok・Claude Code・Codex・Cursor などの AI コーディングエージェント向けに、7 本の本番パターン、クローン可能な starter、3 つの npm CLI を公開している。

7
本番パターン
6+1
プリミティブ + Memory
3
npm CLI
L1→L3
段階的ロールアウト
核心: ループは再帰的なゴール。目的を定義し、サブエージェント・検証・外部状態を伴ってエージェントが反復する。完了するか、人間へエスカレートするまで続く。
2 — 概念と語彙
ハーネスとループ

単一セッションの環境（ツール・権限・ルール）がAgent Harness。スケジュール・状態・検証チェーンを足したものがLoop。

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

Intent Debt

セッションごとにエージェントは冷たく始まる。Skills で慣習・ビルド手順を一度書き、毎回読ませる。

Comprehension Debt

ループが速く ship するほど、自分で書いていないコードとの理解の差が広がる。ループの出力を読む運用が必要。

Orchestration Tax

並列エージェントのレビュー帯域・マージ競合・コンテキスト切替のコスト。Worktrees が機械的衝突を減らす。

Maker / Checker

実装者と検証者を分離。実装者が自分の宿題を採点しない構造が、無人ループの前提。

3 — 6 つのプリミティブ + Memory
構成要素
プリミティブループ内の役割
Automations / Scheduling定期実行でワークを発見・トリアージ（/loop、GitHub Actions、cron）
Worktrees並列・安全なコード変更。1 修正 = 1 worktree、検証失敗後は破棄
Skillsプロジェクト知識の永続化。トリアージ・最小修正・検証手順を SKILL.md に
Plugins & ConnectorsMCP で GitHub・Linear 等の実ツールへ到達
Sub-agentsImplementer / Verifier の maker-checker 分割
+ Memory / StateSTATE.md 等、会話外の durable spine
4 — ループの解剖
典型的なフロー
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f5f0e8", "primaryBorderColor": "#1e3a5f", "primaryTextColor": "#1e3a5f", "lineColor": "#1e3a5f", "fontSize": "14px"}, "flowchart": {"curve": "monotoneX"}}}%% flowchart TD A["Schedule / Automation"] --> B["Triage Skill"] B --> C["Read + Write STATE"] C --> D["Isolated Worktree"] D --> E["Implementer Sub-agent"] E --> F["Verifier Sub-agent"] F --> G["MCP / Git / Tickets"] G --> H{"Human Gate?"} H -->|"safe / allowlisted"| I["Commit / PR / Action"] H -->|"risky / ambiguous"| J["Escalate to human"] I --> A J --> A

参照リポジトリ自身も validate-patterns と audit ワークフローで dogfood している。LOOP.md に、このリポジトリを維持するループの定義がある。

5 — 7 本の本番パターン
patterns/registry.yaml
パターン周期Week 1トークン目的
Daily Triage 1d–2h L1 report Low CI・Issue・コミット・チャットの朝スキャン
Issue Triage 2h–1d L1 propose Low Issue の重複排除・優先度・ラベル提案
Changelog Drafter 1d / tag L1 draft Low マージ済み PR からリリースノート草案
Post-Merge Cleanup 1d–6h L1 off-peak Low main マージ後の tech debt フォロー
Dependency Sweeper 6h–1d L2 patch Medium 依存更新・CVE パッチ（worktree で検証）
PR Babysitter 5–15m L1 watch High PR のレビュー・CI・rebase 支援
CI Sweeper 5–15m L2 cautious Very high 失敗 CI への最小修正（早期エスカレーション必須）

段階的ロールアウト

L1 — Report

レポートのみ。人間が判断。Week 1 のデフォルト。

L2 — Assisted

小さな修正を worktree + verifier 付きで実行。人間ゲートあり。

L3 — Unattended

allowlist 内の無人実行。検証と denylist が前提。

複数ループ併走時の優先度: CI Sweeper → PR Babysitter → Dependency Sweeper → Post-Merge / Changelog（オフピーク）→ Daily Triage（レポート）。

6 — CLI ツール
npm パッケージ
CLI役割代表コマンド
@cobusgreyling/loop-init starter の scaffold（pattern + tool 指定） npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
@cobusgreyling/loop-audit Loop Readiness Score、改善提案、README バッジ npx @cobusgreyling/loop-audit . --suggest
@cobusgreyling/loop-cost パターン・周期ごとのトークン見積もり npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
@cobusgreyling/goal-audit Companion: Goal Engineering 向け監査 npx @cobusgreyling/goal-audit

各 starter は Grok / Claude Code / Codex 向けに starters/ 以下に skills・agents・LOOP.md を同梱。examples/ に GitHub Actions と MCP 設定例あり。

7 — クイックスタート（5 分）
初回セットアップ 
# 1. starter を scaffold
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok

# 2. トークン見積もり
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1

# 3. 準備度監査
npx @cobusgreyling/loop-audit . --suggest

# 4. Week 1 はレポートのみ（Grok 例）
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

監査スコアは空 → L1 → L2 と上がる想定。loop-budget.md でトークン上限、loop-run-log.md で実行履歴を追跡する。

8 — 安全と運用
制約と kill switch
  • 検証は人間の責任: 無人ループは無人のミスを増幅する
  • Denylist: コアドキュメント・audit ロジック等は自動変更禁止
  • Auto-merge: trivial dependency patch + verifier のみ例外
  • Kill switch: loop-pause-all ラベル、または STATE.md のフラグ
  • MCP スコープ: L1 では read + comment まで。信頼後に拡張
注意: サブエージェントと長時間ループはトークンコストが急増する。同じループでも結果はチームの判断次第 — ループは知らない、人間が知っている。
公式