build-iterated-agentic-loop

Build Iterated Agentic Loop の構築

ユーザーが、繰り返し実行するエージェントタスクを、リポジトリ内のスキルと、スケジュール実行、手動実行、またはその両方でコーディングエージェントを実行する GitHub Actions ワークフローにしたい場合に、このスキルを使用します。

目指すのは、反復型エージェントループです。特化したスキルでエージェントの判断を定義し、ワークフローでリポジトリ固有のプロンプトを使ってコーディングエージェントを呼び出し、エージェントメモリファイルで実行間の継続的なフィードバックを引き継ぎます。また、各ワークフローで PR にラベルを付けることで、各ループの未完了 PR が常に 1 つだけになるようにします。具体的な参考パターンとして、narrow-react-prop-types スキルを使用します。

出力

対象リポジトリで、次のファイルを作成または更新します。

• .claude/skills/<skill-name>/SKILL.md：リポジトリ内のエージェントの動作を定義します。
• .github/workflows/agent-<task-name>.yml：定期的に実行するコーディングエージェントの自動化を定義します。
• .github/agent-memory/<task-name>.md：継続的なフィードバックとスコープの制約を記録します。
• 任意の参照資料を .claude/skills/<skill-name>/references/ に置きます。テンプレート、例、または長い補足資料がスキルに必要な場合に使用します。

ワークフロー

1. 対象リポジトリを調査する

セットアップについて質問する前に、次を確認します。

• 既存の .github/workflows/*.yml と .github/actions/** を確認し、ランナー、チェックアウト、依存関係のインストール、キャッシュ、PR のパターンを把握します。
• package.json、bun.lock、pnpm-lock.yaml、yarn.lock、package-lock.json、pyproject.toml、go.mod、Cargo.toml などのパッケージマネージャー関連ファイルを確認します。
• 既存の検証スクリプトを確認します。特に、型チェック、リント、テスト、品質チェック、フォーマット、パッケージ単位のコマンドを確認します。
• 既存の .claude/skills と .agents/skills を確認し、既存の規約との重複を避けます。

完了条件：リポジトリのパッケージマネージャー、インストールコマンド、想定される検証コマンド、既存のワークフロー規約を把握していること。

2. セットアップについて質問する

ユーザーが以下の項目を決められるように案内します。空欄のフォームを提示するのではなく、リポジトリの情報をもとにデフォルト値を提案してください。

1. コーディングエージェント：Claude Code、Codex、OpenCode、CodeLayer のいずれか。推奨する選択肢に必要なシークレットとヘッドレスコマンドを説明します。references/agent-runner-templates.md を使用してください。CodeLayer は Humanlayer の超軽量なエージェントハーネスです。
2. 実行頻度：毎日、毎週、平日、毎月、手動のみ、またはカスタム cron。タスクのリスクとレビューの負担に基づいて実行頻度を提案してください。多くの場合、平日、毎日、または毎週が適切です。
3. タスク：エージェントのループでどのタスクを実行しますか？

• このタスクを実行する既存のスキルはありますか？（ユーザーに質問する前に調査してもかまいません）
• 参考情報として、最近の PR、git 履歴、またはコードベースの特定の部分を確認するか、ユーザーに尋ねてください。

4. 対象範囲：ループで変更可能なディレクトリ／パッケージと、検査のみ可能なディレクトリ／パッケージ
5. 検証：エージェントがコミットする前に成功していなければならないコマンド（先ほどの調査に基づいてユーザーに提案し、確認を求めてください）
6. PR の上限：エージェントによるオープン PR がすでに存在する場合、スケジュール実行を何もせず終了するか、またその場合、新しい実行をブロックする前に許可するオープン PR の数をユーザーに尋ねてください。

• 推奨：エージェントのループごとにオープン PR を 1 件までに制限します。 これにより、エージェントが人間のレビューよりも速いペースで処理待ちの作業を増やし続けるのを防げます。上限がない場合、毎日実行するエージェントは 1 週間でレビューされていない PR を 5 件以上作成し、レビュー疲れやマージコンフリクトを引き起こす可能性があります。
• ワークフローではラベル（例：agent-<task-slug>）を使って、各エージェントのループが作成した PR を識別します。スケジュール実行では gh pr list --label <label> --state open を確認し、件数が上限以上であればスキップします。
• 手動の workflow_dispatch 実行では上限のチェックを迂回するため、必要に応じて強制実行できます。

7. PR のメタデータ：ラベル名、PR タイトルのプレフィックス、ブランチのプレフィックス。

• 例として、[MM/DD][Agent: <Agent Name>]: <Concise Description> をテンプレートとして提案します。例：[6/23][Agent: Effect Migrator]: Migrate XYZ module

8. 応答形式：CI エージェントの最終応答（PR 本文になるもの）をどのような形式にしますか？

• 例として、変更／移行、生成、リファクタリング用の references/response-template.md をユーザーに提示します。
• 要約統計、リスクレベル、検証手順、ファイル一覧など、レビュー担当者に必要な情報を尋ねます。
• 生成するスキルが references/ ディレクトリ内で参照する、カスタマイズした応答テンプレートを作成します。

9. 反復時の動作：/iterate コメントによって既存の PR を更新するかどうか。

• 有効にする場合は、references/agent-iteration.ts をリポジトリにインストールします。配置場所は .github/scripts/、ci-scripts/、scripts/ のいずれかからユーザーに希望を尋ねます。
• スクリプトには 2 つのモードがあります。footer は PR 本文にマーカーを追加し、prompt は PR のコンテキストから反復プロンプトを作成します。
• 無効にする場合は、ワークフローから issue_comment トリガーと、反復にのみ使用するステップを削除します。

完了条件：ワークフロー、プロンプト、メモリテンプレートのすべてのプレースホルダーに、選択した値または明示的なデフォルト値が設定されていること。

3. エージェントの作業を定義する

エージェントが実行する、最小単位の繰り返し可能な作業を抽出します。ユーザーと一緒に、次の3つの質問を検討してください。

何を見つけますか？ エージェントは今回の実行で、どのように対象を特定しますか？

• 問題を報告するCLIツール（例：bunx react-doctor、eslint --format json）
• 検索パターン（例：カバレッジのない*.test.tsに一致するファイル、非推奨のAPIを使用しているコンポーネント）
• 差分または変更履歴（例：前回のリリース以降の新しい依存関係、PRで変更されたファイル）
• 新しいパターンに置き換える、または新しいフレームワークに移行すべき古いパターン
• 過去のCI実行に基づく不安定なテスト

何を変更しますか？ エージェントは各対象にどのような変換を適用しますか？

• 修正：報告された問題をその場で解決します
• 移行：あるパターンから別のパターンへコードを更新します
• 生成：既存のソースに基づいて新しいファイルを作成します
• リファクタリング：動作を変えずに構造を変更します

どのように検証しますか？ 変更が正しいことを何で証明しますか？

• ビルド／型チェックが成功する
• テストが成功する（または指定したサブセットが成功する）
• 問題を検出したツールが、解決済みと報告する
• リントまたはフォーマットのチェックが成功する

完了条件：作業を1文で説明できます。例：「react-doctorの違反を5件見つけて修正し、型チェックと品質チェックが成功することを確認する。」

4. スキルを書く

このタスクに関するエージェントの判断をまとめた、リポジトリ内のスキルを書きます。このスキルはリポジトリ内に置かれるため、リポジトリ固有のパス、パッケージ名、規約を含めてもかまいません。

スキルを書く際は、次のルールに従ってください。

• 順序立てた作業手順を、スキルディレクトリ内のSKILL.md（リポジトリのパターンとユーザーの希望に応じて.claude/skill-slug-hereまたは.agents/skill-slug-here）に記載し、確認可能な完了条件を設ける
• 長いテンプレートや例は同階層の参照ファイルに移し、SKILL.mdから参照する
• 各ルールの情報源は1つにします。同じ指針をスキル、プロンプト、メモリファイルで繰り返さないでください
• CIエージェントが最終出力をどのように整形するかを定義した応答テンプレートを、参照ファイル（例：スキルディレクトリ内のreferences/response-template.md）として用意します。スキルでは、PR本文として使用される最終応答を整形する際に、このテンプレートを読み、それに従うようエージェントに指示してください
• references/skill-template.mdのスキルテンプレートを使用してください。スキルの例はreferences/example-skill.mdにあります
• スキルの仕様を理解するには、https://agentskills.io/specification を参照してもかまいません。

重要：SKILL.mdのフロントマターにあるnameフィールドは、スキルのスラッグと一致している必要があります。たとえば、nameがfix-eslint-issuesのスキルは、.claude/skills/fix-eslint-issues/SKILL.mdまたは.agents/skills/fix-eslint-issues/SKILL.mdに置きます。

完了条件：最終応答の形式も含め、追加の指示がなくてもエージェントが従えるよう、スキルで作業内容が明確に説明されていること。

5. ワークフロープロンプトを書く

リポジトリ固有の対象指定は、汎用スキルではなくGitHub Actionsのプロンプトに記載します。次の内容を含めてください。

• Begin by using the <skill-name> skill.
• スコープ：エージェントが変更および調査してよいディレクトリ／パッケージ
• 指示：レビュー可能な作業単位、避けるべきこと、検証方法
• 該当する場合は、フェンス付きのbash形式で検証コマンドを記載
• .github/agent-memory/<task-name>.mdからエージェントメモリを展開すること
• 完了時の要件：検証、コミット、プッシュを行い、PRにそのまま使える要約を返すこと

ベーステンプレートとしてreferences/workflow-template.ymlを使用してください。埋め込みプロンプトの作成にはreferences/prompt-template.mdを使用してください。

完了条件：無人実行に必要なリポジトリ固有の制約が、プロンプトにすべて含まれていること。

6. メモリファイルをインストールする

references/memory-template.md を出発点として、.github/agent-memory/<task-name>.md を作成します。メモリファイルには、今後の実行に影響を与えるべき継続的なフィードバックを記載します。簡潔に保ってください。

良いメモリエントリ:

• 恒久的なスコープ除外。
• 既知の誤検出領域。
• 今後のエージェント選択を変えるべきレビューフィードバック。

悪いメモリエントリ:

• 一度限りのタスク指示。
• 単一の実行による検証出力。
• スキルにすでに記載されているルール。

完了基準: メモリファイルを削除すると、単なる履歴ではなく、今後の実行に役立つコンテキストが失われること。

7. ワークフローを作成する

references/workflow-template.yml から .github/workflows/agent-<task-name>.yml を作成し、すべてのプレースホルダーを置き換えます。

必要なカスタマイズ:

• ワークフロー名、cron、ブランチプレフィックス、ワークフロー ID、エージェントラベル、PR タイトル。
• リポジトリのランナーラベルとセットアップ手順。
• 依存関係のインストールコマンド。
• コーディングエージェントのインストール、シークレット、ヘッドレス実行コマンド（references/agent-runner-templates.md から）。
• レスポンス抽出ステップ: 各エージェントの出力は異なります（JSON、stream-json、プレーンテキスト）。references/agent-runner-templates.md のエージェント固有の抽出を使用して、最終レスポンスを PR 本文用に /tmp/pr-body.md へ出力します。
• スキル名、スコープ、検証コマンド、メモリパス。
• PR バウンディングゲート: ワークフローは実行前に、エージェントラベルが付いたオープン PR を確認します。ステップ 2 でのユーザーの選択に基づいて上限を設定します（デフォルト: 1）。ゲートは gh pr list --label "$AGENT_LABEL" --state open を使用し、件数を比較します。バウンディングが無効になっている場合は、ゲートステップを完全に削除します。
• /iterate が有効な場合: references/agent-iteration.ts をユーザーの希望する場所にインストールし、一致するようにワークフローのパスを更新します。このスクリプトは、PR フッターの生成とイテレーションプロンプトの構築の両方を処理します。このファイルは、ユーザーの希望する TypeScript ツールチェーン（node の type-stripping、Bun（推奨）、Deno、tsx など）で実行できます。また、ユーザーの要望に応じて別の言語に書き換えることもできます。

/iterate が無効な場合は、issue_comment トリガー、イテレーション専用のステップを削除し、agent-iteration.ts のインストールをスキップします。

完了基準: ワークフローが、存在しないファイルに依存することなく workflow_dispatch から実行できること。

8. 検証と確認

ワークフロー YAML を検証する: コミットする前に、ワークフローファイルをパースして構文エラーを早期に発見します。次のいずれかを使用します:

# Node.js / bun (js-yaml)
bunx js-yaml .github/workflows/agent-<task-name>.yml > /dev/null && echo "Valid YAML"

# Python
python -c "import yaml; yaml.safe_load(open('.github/workflows/agent-<task-name>.yml'))"

# yq (if installed)
yq eval '.name' .github/workflows/agent-<task-name>.yml

パーサーが失敗した場合は、先に進む前に YAML 構文を修正してください。

参照とパスを確認する: スキル、ワークフロー、メモリファイルで指定されたすべてのパスが存在するか、このタスクによって意図的に作成されることを確認します。

完了基準: ワークフロー YAML がエラーなくパースされ、参照されているすべてのファイルが存在すること。

9. ワークフローをドライランする

GitHub Actions ワークフローは、少なくとも一度実行されるまで workflow_dispatch で手動ディスパッチできません。ワークフローをブートストラップするには:

1. 現在のブランチ（main でない場合）に一時的に push トリガーを追加します:

   on:
     push:
       branches:
         - <current-branch-name>  # Remove after first run
     schedule:
       - cron: "0 13 * * *"
     workflow_dispatch:
       # ...
   

2. すべての新しいファイル（ワークフロー、スキル、メモリファイル、スクリプト）をコミットしてプッシュします。

3. ワークフローがプッシュでトリガーされます。Actions タブを監視して、正常に実行されることを確認します。

4. 最初の実行が成功したら、一時的な push トリガーを削除して再度プッシュします。これで、Actions UI または gh workflow run からワークフローを手動でディスパッチできるようになります。

5. ドライランで PR が作成された場合は、それをレビューしてエージェントの動作を確認し、適切にクローズまたはマージします。

完了基準: ワークフローが Actions タブに表示され、workflow_dispatch でトリガーできること。

参照ファイル

• references/workflow-template.yml - コーディングエージェント用 GitHub Actions ワークフローのひな形。
• references/agent-runner-templates.md - Claude Code、Codex、OpenCode、CodeLayer 向けのヘッドレスコマンドとシークレット。
• references/agent-iteration.ts - /iterate 対応用ヘルパースクリプト（PR フッターと反復プロンプトの作成）。ユーザーの好みに応じて .github/scripts/、ci-scripts/、または scripts/ にインストールします。
• references/prompt-template.md - ワークフローに埋め込むプロンプトの構成。
• references/memory-template.md - エージェントメモリーファイルのひな形。
• references/skill-template.md - 生成されるタスクスキルのひな形。
• references/response-template.md - CI エージェントが最終応答（PR 本文）を作成する際の形式の例。
• references/example-skill.md - スキルの例