cobusgreyling/loop-engineering

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

Loop Engineering – 自動化 AI エージェントループの設計・実行・評価

何であるか – CLI で駆動されるフレームワーク。手動のプロンプトを繰り返し可能な「ループ」に置き換え、作業を発見し、LLM ベースのエージェント（Claude、Grok、Codex、Opencode など）に割り当て、出力を検証し、状態を記録する。任意のコードリポジトリに接続可能な、あらかじめ用意された パターン（デイリートリアージ、PRベビーシッター、CIスイーパーなど）のライブラリを同梱。ローカルまたは GitHub Actions で実行可能。

なぜ重要か – 信頼性の高い AI エージェントパイプラインを構築するのは難しい：ループの実行タイミング、自身の作業のスコアリング方法、コストの管理を決定する必要がある。Loop Engineering は構造化されたチェックリスト、ループの知識を記録する STATE.md ファイル、および L1–L3 のスコアリングシステムを提供。これにより、「レポートのみ」から完全に監視不要な自動化へ移行できるタイミングを明確に示す。

コアコンセプト

コンセプト	説明
パターン	事前に定義されたワークフロー（例：`daily-triage`）。実行頻度、初期の安全レベル（L1–L3）、想定コストを指定。
ツール	エージェントに使用される基盤となるLLM（デフォルトは `claude`、`grok`、`codex`、`opencode` に対応）。
STATE.md	ループの学習済み状態を永続化する Markdown ファイル。CLI が初回起動時に作成手順を案内。
ループ準備スコア	ループの設計の質を示す数値スコア（最近の実行が重みづけされる）。
レベル	L1＝レポートのみ、L2＝支援付き、L3＝監視不要。1週間の正しく検証された実行後のみ昇格可能。

セットアップ（5分クイックスタート）

# 現在のリポジトリにループを初期化
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# ヘルスチェックを実行
npx @cobusgreyling/loop doctor .

# 選択したパターンのコスト見積もりを確認
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

--tool を省略すると、CLI はデフォルトで Claude を使用。

このコマンドにより STATE.md ファイルと、ループが監視する内容（イシュー、CI、依存関係など）を記述する設定ファイル群が作成される。1週間後には L1レポート が生成され、ループが何を実行していたかを確認できる。検証が一貫して正しければ、レベルを上げてループを自動実行可能にする。

主なパターン（1つ選んで開始）

パターン	実行頻度	1週目出力	一般的なコスト
デイリートリアージ	1日 – 2時間	リポジトリの健全性に関するL1レポート	低
PRベビーシッター	5–15分	入ってくるPRのL1監視	高
CIスイーパー	5–15分	L2で慎重なフラキーコード修正	非常に高
依存関係スイーパー	6時間–1日	L2でのパッチのみの更新	中
CHANGELOGドラフト	1日またはタグ作成時	L1のCHANGELOGドラフト	低
マージ後クリーンアップ	1日–6時間	L1のオフピーク掃除	低
イシュートリアージ	2時間–1日	L1での提案のみのイシュー処理	低

各パターンは patterns/ ディレクトリにあり、Markdown 説明と patterns/registry.yaml へのYAMLエントリを持つ。インタラクティブな選択ツールはショーケースサイトで利用可能。

例のワークフロー

Claude Code – Claude を使ってコード変更を生成し、VS Code プラグインを含む。
Grok デイリートリアージ – 新規リポジトリで Grok ベースのトリアージループを実行。
GitHub Actions 用軽量ループ – 単一のワークフローファイルでリポジトリに追加可能。追加の STATE.md は不要。

すべての例は examples/ ディレクトリにあり、同じCLIコマンドで実行可能。

セーフティと運用ガイド

失敗モード – docs/failure-modes.md に記載（例：トークン使用量の暴走、架空の修正）。
アンチパターン – docs/anti-patterns.md で、検証なしに過剰自動化するなどの一般的な落とし穴を紹介。
セーフティチェックリスト – docs/loop-design-checklist.md は、レベルアップ前にループを検証する手順を案内。
ストーリー – 実際の成功例・失敗例は stories/ に収集され、コミュニティからの学びを提供。

本プロジェクトは、ループが人間の判断を強化することを強調。監視不要なループは高コストのミスを引き起こす可能性があるため、L1→L2→L3 の段階的進化は必須である。

コミュニティと貢献

採用者リスト – 「add-adopter」イシューテンプレートでプロジェクトを追加。
初心者向けイシュー – 新規参加者向けにラベル付き。メンテナーアイドルは48時間以内に応答を目標。
補完リポジトリ – memory-engineering、outerloop など、ループが信頼性を証明した後の段階向けのオプション拡張。

ライセンス

MIT – 無償で使用・改変・配布可能。

結論 – Loop Engineering は、LLMエージェントをコードベース周辺の繰り返し可能で監査可能な自動化ループに変換する実用的でパターンベースのツールキット。明確なオンボーディングパス、セーフティのための構造、スコアリングシステムにより、ループが自立して行動できるタイミングを把握できる。