sxivansx/loop-engineering

ループエンジニアリング

ループを設定します。自律的にエージェントを動作させるシステムで、あなたが手動でプロンプトを送る必要はありません。目標と停止条件を一度定義すれば、ループが作業を見つけ、実行し、チェックし、結果を記録し、目標が達成されるまで再実行します。このスキルは、既存のプロジェクト内にそのループを立ち上げます。テスト、ビルド、作業追跡の方法を読み取り、汎用的な規約を押し付けるのではなく、プロジェクトの規約に適合させます。

ループは6つのプリミティブから構成されます。目標に必要なものだけを設定してください。

プリミティブ	ループ内での役割	Claude Codeの仕組み
トリガー	各サイクルを開始する（スケジュールまたはイベント）	/goal（条件が満たされるまでターンを跨いで作業）、/loop、スケジュールタスク、フック、GitHub Actions
状態	サイクル間のループのメモリ（ディスク上）	マークダウンファイル（LOOP.md）、またはMCP経由の課題管理システム
発見	このサイクルで何に取り組むかを見つける	CI、課題、差分、キューを読み取るトリアージステップ
メーカー	1単位の作業を行う	.claude/agents/ 内のサブエージェント
チェッカー	メーカーの作業を独立して検証する	.claude/agents/ 内の別のサブエージェント
停止条件	ループを終了させるルール	チェッカーが実行する検証可能なチェック

無人で実行されるループにはモニターを追加します。ループ全体を監視し、逸脱（目標から外れる）、空回り（純粋な進捗がない）、または制限超過（サイクル数過多、時間超過）が発生した場合に停止させる監視エージェントです。メーカーとチェッカーは各アイテムの正確性を保ち、モニターはループ全体を目標に向けさせ、静かに迷走して長時間実行されることを防ぎます。

さらに2つのオプションのアドオンがあります。ワークツリー（git worktree）は並列実行するメーカーを分離し、同じファイルを編集しないようにします。MCPコネクターはループが実際のツール（PRを開く、チケットを更新する、ステータスを投稿する）にアクセスできるようにします。並列性や外部副作用が必要な場合に追加します。

セットアップ手順

この手順は既存のプロジェクト内で実行します。呼び出されたら以下の手順に従ってください。副作用（スケジュールジョブ、プッシュ、チケット書き込み、デプロイ）がある場合は、ユーザーに確認してから行ってください。

1. 最初にプロジェクトを読む。 スキャフォールディングを行う前に、リポジトリを把握します。テスト、ビルド、リントの実行方法（package.json、Makefile、CI設定、CLAUDE.mdを確認）、既存の規約や .claude/agents/ にあるスキルやエージェント、そして作業の発生元（CI、課題管理システム、バックログ、キュー）を確認します。ループはこのプロジェクトに適合しなければなりません。実際のコマンドと規約を再利用し、新しいものを発明しないでください。

2. 目標と停止条件を固定する。 ユーザーにループの1つの目標と、完了を意味する検証可能な条件（テストがexit 0、キューが空、不合格チェックがゼロ）を尋ねます。停止条件のないループは絶対にリリースしてはいけません。ユーザーが条件を指定できない場合は、制限付きのフォールバック（Nサイクル後に停止）を設定し、その旨を明確に伝えます。Claude Codeでは、/goal <条件> で実行可能になります。Claudeは条件が満たされるまでターンを跨いで作業を続け、/goal clear で早期終了します。

3. 状態ファイルを書く。 ${CLAUDE_SKILL_DIR}/templates/LOOP.md をリポジトリルートにコピーし、目標、停止条件、サイクル周期、人間によるゲートを記入します。ループが管理する3つのライブセクションがあります：## Open（発見済み、未完了）、## Done（検証済みのエビデンス付き）、## Blocked（人間の支援が必要）、および ## Rules セクション（ループ内のすべてのエージェントが従う固定指示セット）。ループは毎サイクル最初にこれを読み、最後に書き込みます。

4. メーカーサブエージェントを作成する。 ${CLAUDE_SKILL_DIR}/templates/loop-maker.md を .claude/agents/loop-maker.md にコピーし、ステップ1で見つけた規約とテストコマンドを指すように設定します。## Open から正確に1つのアイテムを処理し、プロジェクトの既存のスキルと規約に従い、自分の作業を自分で完了とマークすることはありません。同名のファイルが既に存在する場合は、上書きせずに更新します。

5. チェッカーサブエージェントを作成する。 ${CLAUDE_SKILL_DIR}/templates/loop-checker.md を .claude/agents/loop-checker.md にコピーします。これはメーカーとは別のエージェントであり、プロジェクトの実際の検証（ステップ1で見つけた実際のテスト、ビルド、またはリントコマンド。説明ではありません）を実行し、アイテムを ## Done に移動できる唯一のエージェントです。

6. モニターサブエージェントを作成する（無人ループには推奨）。 ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md を .claude/agents/loop-monitor.md にコピーし、数サイクルごと、またはループよりも遅いタイマーで実行します。個々のアイテムではなくループ全体を監視します。ループがまだ目標に収束しているかどうかをチェックし、逸脱（目標に貢献しない作業）、空回り（純粋な進捗がない、アイテムがOpenとBlockedの間を行き来する）、または制限超過が発生した場合にループを停止し、人間にエスカレーションします。これにより、ループが静かに迷走して長時間実行されることを防ぎます。

7. コードレビューとセキュリティ監査の周期を設定する（ユーザーに尋ねる）。 ループをそれぞれどの程度の頻度で実行するか尋ね、両方を LOOP.md に記録します。明確なオプションを提示し、常になしを含めます。

   • コードレビュー（/code-review）：変更のたび、各PRまたはマージの前、Nサイクルごと、毎週、またはなし。
   • セキュリティ監査（/security-review）：変更のたび、各PRまたはマージの前、毎週、毎月、またはなし。

   選択された周期で、ループはその組み込みパスを実行し、見つかった問題を新しい作業アイテムとして ## Open に記録します。メーカーが修正し、チェッカーが修正を検証します。ユーザーがなしを選択した場合は、そのパスを完全にスキップし、LOOP.md に なし と記録してループが再導入しないようにします。

8. 発見を定義する。 ## Open を各サイクルで、このプロジェクトの実際の作業が存在する場所（CIステータス、未解決の課題、最近のコミット、作業キュー）から埋めるトリアージステップと、それらの発見を個別にチェック可能なアイテムに変換する方法を記述します。可能な限り決定論的にします。

9. 隔離を選択する（オプション）。 1サイクルに複数のメーカーが実行される場合、各メーカーに独自の git worktree とブランチを割り当て、同じファイルを書き込まないようにします。アイテムごとに1つのワークツリー。

10. コネクターを配線する（オプション）。 ループがPRを開く、チケットを更新する、またはステータスを投稿する必要がある場合は、対応するMCPサーバーを接続します。それ以外の場合、ループの出力はローカルに留まり、人間が中継します。

11. トリガーを設定する。 周期に合った最も軽量なメカニズムを選択します。

    • このセッション内で目標が達成されるまで実行 → /goal <停止条件>（Claudeは条件が真になるまでターンを跨いで作業；/goal clear で早期終了）
    • 周期で繰り返し、オンデマンド → /loop
    • 定期的かつ無人 → スケジュールタスク（またはCIサイドループの場合はcron / GitHub Actions）
    • イベント（プッシュ、PR、ファイル変更）に反応 → フックまたはGitHub Actions

    スケジュールジョブを作成する前にユーザーに確認します。

12. ドライラン、検証、そして有効化。 1サイクルを手動で実行します。生成されたすべての出力を読みます。チェッカーが実際に不良出力をブロックし、状態が書き込まれたことを確認します。その後でのみトリガーを有効にします。

ガードレール（譲歩不可）

• チェッカーはメーカーではない。 コードを書いたエージェントが自分で正しいと宣言することはできません。
• 停止条件は検証可能であり、雰囲気ではない。 「出来たように見える」は停止条件ではありません。exit 0 を返すコマンドが停止条件です。
• 状態は毎サイクル書き込まれる。 ループが試したことを忘れると、同じことを繰り返します。モデルは忘れますが、ファイルは忘れません。
• 不可逆的な操作には人間によるゲートを残す。 リリース、デプロイ、削除、支出。ループがドラフトを作成し、人が確認します。無人ループは無人ミスを犯します。
• ブロックは推測より優れている。 ループが検証できない、または先に進めない場合、## Blocked に書き込んでそのアイテムを停止します。推測をリリースしてはいけません。
• 長時間ループは監視され、制限される。 無人ループはモニターとバウンドとともに実行されます。目標から逸脱した場合、またはバウンドを超えた場合、モニターは停止し、エスカレーションします。ループが間違った方向に永遠に実行されることは決してありません。

ループのセットアップ後の構成

your-project/
├── LOOP.md                   # 目標、停止条件、制限、ルール、Open/Done/Blocked
├── .claude/
│   └── agents/
│       ├── loop-maker.md      # 1単位の作業を実行
│       ├── loop-checker.md    # 独立して検証
│       └── loop-monitor.md    # ループ全体の逸脱と暴走を監視
└── (トリガー: /goal, /loop, スケジュールタスク, または GitHub Actions)

アンチパターン：これらをリリースしてはいけません

• 停止条件のないループ（永遠に実行され、トークンを消費し続けます）。
• 1つのエージェントが自分の作業を書き、評価するもの。
• 状態ファイルのないループ（すべてを再導出し、作業を繰り返し、何が失敗したかを忘れます）。
• モニターやバウンドのない無人ループ（目標から逸脱し、誰も気づかないうちに何時間も実行されます）。
• 不可逆的なアクションに人間によるゲートがない無人リリース。
• 1つのループが多くの無関係なジョブを処理すること。1つのループ、1つの目標、1つの停止条件。残りはそれぞれ独自のループに分割します。

このスキルのファイル

• templates/LOOP.md：ターゲットリポジトリにコピーする状態ファイル。
• templates/loop-maker.md：メーカーサブエージェントの定義。
• templates/loop-checker.md：チェッカーサブエージェントの定義。
• templates/loop-monitor.md：モニターサブエージェントの定義（逸脱と暴走のガード）。
• examples/keep-ci-green.md：目標からトリガーまで、完全に動作するループの例。