design-control-loop

設計コントロールループ

ユーザーが、スケジュールに沿って小さく低リスクでレビュー可能な変更を重ね、コードベースの何らかの特性を目標に近づけたい場合に、このスキルを使用します。これは エージェント型コントロールループ です。

あなたの役割は、ユーザーにヒアリングし、ユーザーと 一緒に ループを設計し、それを構築すること です。設計は、ユーザーのコードベースと、すでに使っているツールに合わせて調整する必要があります。決まったツールセットも、再現すべきテンプレートもありません。リポジトリで確認した内容に基づいて選択肢を提案し、トレードオフを話し合い、設計に合意してから実装します。

基本的な考え方

制御理論を参考にします。コードベースは、チームメイト、依存関係、生成コードといった 外乱 によって継続的に変化する動的システムです。コントロールループは、すべてを一度に変更するのではなく、望ましい状態へと導きます。

• 目標値 — コードベースの特性について、目指す最終状態です。
• センサー — 現在の状態を測定し、目標値との差を算出します。
• コントローラー — 測定結果に基づき、次の小さく低リスクな変更を決定します。
• アクチュエーター — 変更を適用して PR を作成するコーディングエージェントです。
• 結果は次回の実行にフィードバックされます。人間はループに 参加し続け、方向を調整します。

設計を始める前に references/control-loop-taxonomy.md を読み、これらの概念についてユーザーに説明してください。実際に最後まで作り上げた例は references/example-control-loop.md を参照してください。ただし、これは参考例であり、設計図として扱わないでください。

このスキルの進め方

• 質問する前にリポジトリを読む（フェーズ A）。白紙の状態で臨むのではなく、提案を用意してヒアリングに臨みます。
• 各コンポーネントを個別に調整します。 適切なセンサー、コントローラー、アクチュエーターは、ユーザーの課題と技術スタックによって異なります。参考資料にあるリストは話し合いのきっかけとなる例であり、順に適用すべきチェックリストではありません。
• CI に組み込む前に、各コンポーネントをローカルで単独実行できるようにします（フェーズ D）。ワークフローでは、ユーザーが手動で実行できるものだけをオーケストレーションします。
• 構築を始める前に、合意した設計を書面にまとめ、ユーザーが容易に修正できるようにします。

成果物

合意した設計に合わせて、対象のリポジトリ内に以下を作成または更新します。

• バージョン管理され、ユーザーがローカルで実行できるコマンドまたはスクリプトとしての センサー と コントローラー。
• .claude/skills/<skill-name>/SKILL.md — エージェントの判断を記述した アクチュエーター スキル（リポジトリの慣例に応じて .agents/skills/... に配置する場合があります）。
• ループを実行して PR を作成する、定期実行の ワークフロー（デフォルトは GitHub Actions。リポジトリで使われている CI があればそれを使用）。
• 実行間で継続的なフィードバックを引き継ぐ メモリー／フィードバックファイル。
• 必要に応じて、ループによる改善の間に問題の悪化を防ぐ ダンパー（回帰ゲート）。

ワークフロー

フェーズ A — システムを把握する

次の参考資料を読みます： references/example-control-loop.md。

セットアップについて質問する前に、以下を読みます。

• 既存の CI：.github/workflows/*.yml、.github/actions/**、または GitHub 以外のリポジトリで使われている CI 設定。ランナー、チェックアウト、依存関係のインストール、キャッシュ、PR の慣例を確認します。
• パッケージマネージャー関連ファイル（package.json、bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json、pyproject.toml、go.mod、Cargo.toml など）。
• 既存の検証スクリプト：型チェック、リンティング、テスト、品質チェック、フォーマット、およびパッケージ単位のコマンド。
• 既存の .claude/skills／.agents/skills と、既存のエージェントループ（ワークフロー、agent-memory、接続用スクリプトの配置場所など）。新たに作り出すのではなく、慣例に合わせます。
• リポジトリですでに使われている静的解析、リンティング、コード生成、テストのツール。センサーの素材として特に有力です。
• パッケージ、サービス、リポジトリの目的を大まかに把握します。

完了条件：リポジトリのパッケージマネージャー、インストールコマンド、有力な検証コマンド、CI プラットフォーム、既存のループに関する慣例を説明できます。また、含まれるパッケージ、サービス、アプリケーションを大まかに理解しています。

フェーズ B — ユーザーとループを設計する

以下の参考資料を読んでください： references/control-loop-taxonomy.md、references/example-control-loop.md、references/agent-runner-templates.md。

これはインタビューです。以下の各コンポーネントについて検討します。まず、設定値についてユーザーに質問してください。フェーズ A に基づく選択肢を提案し、トレードオフを示しながら、いずれかの選択を押しつけないでください。検討しながら決定事項を記録してください。

1. 設定値。 どの特性をどの目標値に向けて改善しますか？例として、不変条件（「古いパターンを使うプロシージャがない」）、しきい値（「対象パッケージのテストカバレッジ ≥ X」）、方向性（「実行のたびに出現数を減らす」）などがあります。また、スコープも明確にします。ループが変更してよいディレクトリ／パッケージと、読み取りのみ可能なものはどれですか？

2. センサー。 ループは設定値とのギャップをどのように測定しますか？コードベースとユーザーが現在使っているツールを調べ、そのスタックに合った選択肢を提案してください。静的解析または lint ツール、構造検索／AST 検索、テストスイート、型チェッカー、テレメトリまたはエラーのクエリ、カスタムスクリプト、あるいはエージェントベースのチェックなどが考えられます。特定の特性を押しつけるのではなく、ユーザーにとって重要なトレードオフ（安定性、コスト、再現性、測定がひそかに無効化される可能性があるかどうか）を話し合ってください。コントローラーが再現性をもって処理できる測定を目指します。

3. コントローラー。 測定結果から、低リスクでレビューしやすい規模を保ちながら、次の作業単位をどのように選びますか？これをユーザーと一緒に設計します。対象の優先順位、1 回あたりの変更規模、ここでいう「レビュー可能な作業単位」の意味を決めます。コントローラーは、次の対象を選ぶスクリプトのような完全に決定論的なものから、自然言語の基準に基づいて判断するエージェントのような完全にエージェント的なものまであります。また、センサーまたはアクチュエーターと統合される場合もあります。コントローラーは、ループの出力をもとに時間をかけて調整する部分です。まずはシンプルに始め、見直していくことを想定してください。

4. アクチュエーター。 コーディングエージェントとリポジトリ内のスキルで変更を適用します。

   • エージェントと認証情報。 references/agent-runner-templates.md から、CLI コーディングエージェント（Claude Code、Codex、OpenCode、CodeLayer、…）、そのシークレット、ヘッドレスコマンドを選択します。
   • 優れたパターンを先に確認。 自動化する前に、優れた変更とはどのようなものかを明確にします。コードベース内の既存パターンに従うべきかユーザーに尋ね、コードを調べてそのパターンを見つけてください。これらをアクチュエータースキルにまとめます（フェーズ C）。
   • 検証。 エージェントがコミットする前に合格必須とするコマンドを決めます。フェーズ A に基づいて候補を提案し、確認してください。

5. 外乱＋ダンパー（提案）。 ループの外部でシステムを変化させる要因（チームメイトによる同時進行の変更、依存関係の更新、生成コードなど）を挙げます。次に、定期実行されるループが問題を少しずつ解消している間、測定対象の問題が悪化しないようにするダンパーを提案してください。たとえば、センサーの出力をベースラインと比較し、新たに発生した逸脱を検出して通知する（または最終的にブロックする）PR チェックが考えられます。これは任意であり、必要としないループもあります。

完了条件：設定値、センサー、コントローラー、アクチュエーター（エージェント＋スキル＋検証）、外乱／ダンパーを明記した、簡潔な設計書があること。各コンポーネントはユーザーがローカルで実行できるものにしてください。

フェーズ C — アクチュエータースキルを作成する

次のリファレンスを読んでください： references/skill-template.md、references/example-skill.md、references/response-template.md。

このタスクにおけるアクチュエーターの判断基準をまとめた、リポジトリ内のスキルを作成します。リポジトリ内で使用するため、リポジトリ固有のパス、パッケージ名、規約を使用できます。

• SKILL.md には、確認可能な完了基準を含む手順として、順序立てた動作を記述します。長いテンプレートや例は、同じディレクトリ内のリファレンスファイルに移します。
• フェーズ B4 の確立された規約に従うよう、ゴールデンパターンを組み込みます。
• ルールごとに情報源を1つにします。同じガイダンスをスキル、プロンプト、メモリファイルで繰り返さないでください。
• エージェントが最終出力をどのようにフォーマットするかを定めたレスポンステンプレート（例：references/response-template.md）を含めます。このテンプレートが PR の本文になります。スキルには、これを読んで従うよう指示します。
• スキルのひな形には references/skill-template.md を、具体例には references/example-skill.md を使用します。スキルの仕様については https://agentskills.io/specification を参照してください。

重要： スキルのフロントマターにある name は、ディレクトリのスラッグと一致させる必要があります。migrate-foo という名前のスキルは、.claude/skills/migrate-foo/SKILL.md（または .agents/skills/migrate-foo/SKILL.md）に配置します。

完了基準：スキルには、最終出力のフォーマット方法も含め、エージェントが人手を介さずに作業を完了できるだけの明確な説明が記載されています。

フェーズ D — 各コンポーネントをローカルで実行可能にする

次のリファレンスを読んでください： references/agent-runner-templates.md。

CI が存在しない段階では、リポジトリの慣例に従って、センサーとコントローラーをバージョン管理されるコマンドまたはスクリプトとして追加し、手動でループ全体が動作することを確認します。

• センサーを単独で実行し、安定した、実用可能な測定結果が得られることを確認します。
• 実際のセンサー出力を使ってコントローラーを実行し、妥当な次の増分を選択することを確認します。
• コントローラーが選択した対象に対して、ヘッドレス CLI コマンドでアクチュエーターをローカル実行し、変更が加えられ、検証に合格することを確認します。

各要素を単独でローカル実行できるようになってから、CI に進みます。こうすることでループのデバッグが容易になり、ワークフローはユーザーがすでに実行できる処理を薄くオーケストレーションするだけになります。

完了基準：ユーザーがセンサー、コントローラー、アクチュエーターをローカルで個別に実行できます。

フェーズ E — ループを CI に組み込む

次のリファレンスを読んでください： references/workflow-template.yml、references/prompt-template.md、references/agent-runner-templates.md。

コンポーネントを定期実行ジョブとして組み立てます。GitHub Actions は、コード、シークレット、バージョン管理、スケジュール設定やディスパッチにすでに対応しているため、デフォルトの選択肢です。ただし、リポジトリで使用している CI があれば、そちらを使ってください。

• ループは個別のステップ：センサー → コントローラー → アクチュエーターとして実行し、その後、エージェントの最終メッセージを本文としてコミットし、PR を作成します。（コンポーネントが統合されている場合（例：センサーがすでに優先順位付けを行う場合や、1つのエージェントが選択と変更の両方を行う場合）は、単一のステップにまとめます。設計にない分離を作らないでください。）
• 再利用可能なロジックは、カスタムのコンポジットアクションに配置できます。
• タスクのリスクとレビュー負荷に基づいて、実行頻度（毎日、平日、毎週、毎月、手動のみ、またはカスタム cron）を決定します。
• メモリファイル（フェーズ F）をアクチュエーターのコンテキストに組み込みます。
• ベースとして references/workflow-template.yml を、埋め込みプロンプトには references/prompt-template.md を使用します。エージェントの実行手順とレスポンス抽出手順は references/agent-runner-templates.md から取り込みます（エージェントによって出力形式は異なるため、最終レスポンスを /tmp/pr-body.md に取得してください）。

完了基準：存在しないファイルに依存せず、workflow_dispatch からワークフローを実行できます。

フェーズ F — 人間がループに関与できるようにする

次の参考資料を読んでください： references/memory-template.md、references/agent-iteration.ts。

誘導がなければ、スケジュール実行されるループは軌道から外れていきます。人間が利用できるチャネルを2つ用意し、どちらも現在のPRだけでなく、今後の動作を変えられるようにします。

• メモリ／フィードバックファイル。 バージョン管理された Markdown ファイル（例：.github/agent-memory/<task-slug>.md）を、毎回、コントローラーの後にアクチュエーターのコンテキストへ確実に読み込みます。references/memory-template.md を使用してください。適切な記載内容は、恒久的な対象範囲の除外、既知の誤検知が発生する領域、今後の選定に反映すべきレビュー担当者からのフィードバックです。一度限りの指示や、単一実行のログは含めません。
• PR 上での /iterate。 各ループのPRにラベルを付け、各ワークフローが自ら作成したPR上のコメントだけを処理するよう、非表示のマーカーを埋め込みます。メンテナーが /iterate とコメントすると、該当するワークフローがPRのコンテキスト（差分、コメント）とフィードバックを読み込み、エージェントがメモリとPRを更新します。リポジトリのCIスクリプトの保存場所に references/agent-iteration.ts を導入してください（モード：footer、prompt）。

これをユーザーには、時間をかけてコントローラーとスキルを調整する方法として説明します。人間が修正し続けることで、ループは改善していきます。

完了条件：継続的なフィードバックが実行間で保持され、/iterate が有効な場合は既存のPRが更新されること。

フェーズ G — フロー制御

次の参考資料を読んでください： references/workflow-template.yml。

レビューできる速度を超えてループがPRを作成しないよう、進行中の作業量を制限します。推奨されるデフォルト：ループごとにオープンなPRを1件。

• ワークフローは、このループのラベルが付いたオープンなPRを確認し、上限に達している場合はスケジュール実行時に何もせず終了します。手動の workflow_dispatch 実行では、この確認をスキップします。
• PRのメタデータを決定します：ラベル名、PRタイトルのプレフィックス、ブランチのプレフィックス。

これを設定しないと、誰もレビューしていない間に、毎日実行されるループが重複したPRや競合するPRを積み上げてしまう可能性があります。完了条件：このループのオープンPR数が上限に達している場合、スケジュール実行が何もせず終了すること。

フェーズ H — 検証、ドライラン、反復の高速化

次の参考資料を読んでください： references/workflow-template.yml。

ワークフローの YAML を検証します（bunx js-yaml file.yml、python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yml、または yq）。また、スキル、ワークフロー、メモリファイルで指定されたすべてのパスが存在するか、このタスクで作成されることを確認します。

ドライラン。 ワークフローは一度実行されるまで workflow_dispatch で起動できません。一時的に現在のブランチ向けの push トリガーを追加し、プッシュして実行を確認した後、トリガーを削除します。ワークフローが作成したPRを確認し、ループが期待どおりに動作することを確かめます。

反復を高速化する準備が整ったら（ループが調整され、高品質な出力を安定して生成できるようになったら）、スケジュールの頻度を上げる、コントローラーのバッチを拡大する（例：1回の実行で N 個の対象を選択する）、1回のワークフロー実行で認識→制御→実行のサイクルを N 回行う、またはワークフローを複数回実行し、チームメンバーごとに1件のPRを割り当てる、といった方法があります。

完了条件：ワークフローの YAML を解析でき、参照されるすべてのファイルが存在し、ループによってレビュー済みのPRが少なくとも1件作成されていること。

参考ファイル

上記の各フェーズには、そのフェーズに関連する参考資料が記載されています。該当するフェーズに進んだら、それぞれを読んでください。全体の一覧：

• references/control-loop-taxonomy.md — 制御ループの構成要素と、検討すべき設計上の問いです。最初に読み、ユーザーへの説明に活用してください。
• references/example-control-loop.md — 構成要素ごとに注釈を付けた、完全な制御ループの例です。図解であり、テンプレートではありません。
• references/agent-runner-templates.md — Claude Code、Codex、OpenCode、CodeLayer のローカルおよび CI でのヘッドレスコマンドとシークレット、および応答の抽出方法です。
• references/workflow-template.yml — センサー／コントローラー／アクチュエーターを個別のステップとして記述した、定期実行ループのワークフローのひな形です。
• references/prompt-template.md — アクチュエーターのステップに埋め込むプロンプトの構成です。
• references/memory-template.md — メモリ／フィードバックファイルのひな形です。
• references/skill-template.md — 生成されるアクチュエーターのスキルのひな形です。
• references/response-template.md — エージェントの最終応答（PR 本文）のフォーマット例です。
• references/example-skill.md — 適切に構成されたタスクスキルの具体例です。
• references/agent-iteration.ts — /iterate のサポート用ヘルパー（PR フッターマーカーと反復プロンプトの構築）です。