swe-loop

SWE Loop

prompt → plan → execute → debug パイプラインの execute ステージです。コーディングプロンプトを、動作し、テスト済みで、整理されたコードに変換します。plan-loop を実行して実行可能な tasks.json を取得し、その後、依存関係の順にタスクを進めます。各タスクは、分離された 2 つのサブエージェントによって進められます。コードを書く Engineer と、テストと品質基準を担う QA が、ゲートを満たすまでループします。フィードバックシグナルは、リポジトリ内の他の評価ループと同様に 2 つの要素で構成されます。客観的ゲート（タスクのテストが合格し、回帰テストスイート全体が成功し、tools/quality_check.py がしきい値違反を報告しないこと）と、定性的ゲート（rubrics/quality-rubric.md に基づく QA の評価。シンプルさ、読みやすさ、コメントの適切さ、整理、スタイルの一致）です。1 回の外側のステップで扱うタスクは 1 つ、内側のラウンドで提案する変更は 1 つなので、すべての差分の原因を特定できます。

使用する場面

作業を一度にまとめて書くのではなく、分解して実装・テストしたい場合に、実際のリポジトリでプロンプトを実装するために使用します。また、「完了」とは、テストが成功し、コードがクリーンで、後続のエンジニアが受け入れられる状態を意味します。デフォルトでは、plan-loop の tasks.json をタスクごとに実行します。例外として認められるのは、計画に実際の欠陥がある場合です。その場合は、即興で迂回せず、open_question として人間に確認します。シンプルなほど優れています。テストに合格するために複雑さを増す変更は QA に差し戻されます。計画のみを行う場合（plan-loop）や、完成済みの成果物の指標を最小化する場合（optimize-loop）には使用しません。

セットアップ

バインディングは対話形式で解決します。loop.run.yaml が存在する場合は読み込み、値を 1 行で確認してループに進みます。存在しない場合は、Claude Code（AskUserQuestion ツールを利用可能）の場合、各バインディングの値を推測して推奨します。それ以外のホストでは、それぞれを引用符付きのプロンプトとして質問します。その後、loop.run.yaml（形式は examples/run.example.yaml）を書き込み、何かをビルドする前に確認します。

バインディング	意味	デフォルト	推測方法
<prompt>	実装するコーディングタスク。ファイルパスまたはインラインテキスト	—	ユーザーのリクエスト
<repo>	ビルド対象のプロジェクト。Engineer が編集します	.	作業対象のリポジトリ
<tasks_file>	ループが実行する plan-loop の出力（plan-loop の validate_plan.py で検証）	<sandbox_root>/tasks.json	Phase 0 で plan-loop が生成
<test_command>	プロジェクトのテスト実行方法	—	tasks.json.environment.test_command。なければ、リポジトリから推測（pytest、npm test、…）
<sandbox_root>	計画、イテレーションの成果物、台帳の保存場所	./sandbox	—
<iter_strategy>	branches（保持するタスクごとに git コミットを作成）または snapshots（フォルダーをコピー）	branches	branches にはクリーンなリポジトリが必要
<pr_mode>	保持するタスクを PR にする方法（プルリクエストを参照）：stacked（タスクごとに PR を作成し、それぞれを前の PR に積み重ねる — デフォルト）、single（実行全体で PR を 1 つ作成）、none（ローカルコミットのみ、PR なし）	stacked	小規模な変更、または stacked-PR 用ツールがない場合は single。オフラインの場合、またはリモートがない場合は none
<base_branch>	PR の最終的なターゲットブランチ	main	リポジトリのデフォルトブランチ（git symbolic-ref refs/remotes/origin/HEAD）
<task_budget>	タスクごとの Engineer⇄QA ラウンドの最大数	6	—
<patience>	改善のないラウンドが N 回続いたらタスクを停止	2	—
<quality_thresholds>	quality_check.py のハードリミット：max_comment_block、max_comment_line_len、max_func_loc、max_nesting、max_file_loc	8 / 100 / 60 / 4 / 400	リポジトリの基準に合わせて厳しくする／緩める

<skill_dir> はこのスキルのインストール先フォルダーです。loop.run.yaml には実際のパスを指定してください。各ラウンドの客観的な品質ゲートは次のとおりです。

python3 <skill_dir>/tools/quality_check.py <changed_files> \
  --max-comment-block 8 --max-comment-line-len 100 --max-func-loc 60 --max-nesting 4 --max-file-loc 400

ループ

フェーズ 0 — 計画（1 回のみ）

このチェックリストをコピーして、完了した項目にチェックを入れてください。

• 計画を取得する。 <tasks_file> が存在し、plan-loop の validate_plan.py に合格する場合は、読み込んで、目的とタスク数を 1 行で確認し、実行に進みます。それ以外の場合は、<repo> に基づいて <prompt> に対し plan-loop スキルを実行し、<tasks_file>（および plan.md）を作成して、構築を始める前にユーザーに計画を確認します。
• ベースライン。 <test_command> を実行し、現時点で合格しているテストの一覧を記録します。これは、以降のすべてのタスクで維持すべき回帰テストのベースラインです。台帳にベースラインの行を記録します。
• PR の事前確認（<pr_mode> = none の場合はスキップ）。リモートが存在し、gh が認証済みであることを確認します（gh auth status）。<base_branch> を解決し、今日の日付から実行タグを選んで <run_branch> = swe/<tag> に設定します。自分が所有していないブランチにプッシュしたり、そのブランチを対象に PR を作成したりしないでください。強制プッシュも禁止です。

タスクごと（外側のループ — tasks.json.order のタスク）

依存関係の順序に従って、各タスク T を処理します。depends_on の項目が維持される前に、次のタスクを開始してはいけません。

• チェックポイント。 既知のコミットにあるクリーンなツリーを確認します（T の取り消し地点）。ブランチの方式は <pr_mode> に従います。stacked の場合は、T のブランチ <run_branch>/<T> を 直前に維持されたタスクのブランチから作成します（最初のタスクでは <base_branch> から作成します）。これにより、各タスクは前のタスクの上に積み重なります（order はトポロジカル順であり、すべての depends_on がすでに祖先チェーン内にあるため、これは有効です）。single／none の場合は、1 つの作業ブランチ <run_branch> を使い続けます（最初のタスクで <base_branch> から作成します）。snapshots モードでは、<repo> も <sandbox_root>/iter/<T>/before/ にコピーします。

内側のループ（エンジニア ⇄ QA — pass または <task_budget>／<patience> に達するまで）

• エンジニア（起動、または起動できない場合は代替処理、roles/engineer.md）。T、リポジトリ、および改善ラウンドでは前回の verdict.json を渡します。周辺のコードを読み、ソースのみを編集して T を実装し、change.json（schemas/change.schema.json）を返します。
• QA（起動、または起動できない場合は代替処理、roles/qa.md）。T、エンジニアの変更、リポジトリ、および rubrics/quality-rubric.md を渡します。T の acceptance_criteria に不足しているテストを作成するか（すでに網羅されている場合は品質のみを評価し、テストのみを編集し）、<test_command> を実行して テストスイート全体（T のテストと、それ以前のすべてのタスクのテスト）を実行し、quality_check.py を実行してルーブリックを採点し、verdict.json（schemas/verdict.schema.json）を返します。
• 記録。 このラウンドの台帳の行を記録します。
• 維持または改善。 verdict.pass が真の場合は 維持します。ブランチ方式では T をコミットし、スナップショット方式では作業コピーを昇格させます。その後、<pr_mode> に従って（プルリクエストを参照）、T の PR を 作成または更新します。stacked の場合は <run_branch>/<T> をプッシュし、base = 直前のタスクのブランチ（最初のタスクでは <base_branch>）として PR を作成します。single の場合はコミットのみ行います（PR は最後に 1 つ作成します）。none の場合は何もしません。回帰テストのベースラインに T のテストが加わったら、次のタスクに進みます。それ以外の場合は、verdict.fixes をエンジニアに渡して改善します。<patience> ラウンドのあいだ判定が改善しない場合、またはラウンド数が <task_budget> に達した場合は、タスクを停止します。T を取り消して blocked と記録し、open_question を記録して停止します。未完了のタスクの上に後続のタスクを構築してはいけません（その PR も作成してはいけません）。

order 内のすべてのタスクが維持された場合（プロンプトが実装され、テスト済み）、またはタスクがブロックされた場合にループは終了します。終了時に <pr_mode> = single の場合は、<run_branch> をプッシュし、すべてのタスクを含む 1 つの PR（base <base_branch>）を作成します。成果物は、構築済みリポジトリに加えて、plan.md、tasks.json、台帳、および PR です。

プルリクエスト（タスクごと）

<pr_mode> は、完了として保持されたタスクをリモートに送る方法を制御します。プルリクエストを作成するのは保持されたタスクのみです（blocked のタスクには作成しません）。プルリクエストは、すでにテストに合格したタスクを届けるためのラッパーにすぎないため、スコープ分離ゲートは変更されません。gh で認証済みで、リモートが必要です。作業ツリーに未コミットの変更がある場合、またはリモートがない場合は、none にフォールバックしてユーザーに伝えてください。プッシュ済みのタスクブランチを強制プッシュしてはいけません。

• stacked（デフォルト）— タスクごとに 1 つのプルリクエスト。 各タスクブランチ <run_branch>/<T> は、直前に保持されたタスクのブランチから分岐し、そのプルリクエストはその親タスクをターゲットにするため、スタックは tasks.json の順序を反映します。

  <base_branch> ◄─ PR T1 (swe/<tag>/T1) ◄─ PR T2 (base = T1) ◄─ PR T3 (base = T2) ◄─ …
  

  タスクを保持する際は、git push -u origin <run_branch>/<T> を実行し、続けて gh pr create --base <parent_branch> --head <run_branch>/<T> --title "<T.id>: <T.title>" --body "<what it delivers; Depends on #<parent PR>; tests N/N; quality minK>" を実行します。 下から順にレビューしてマージしてください。親のプルリクエストがマージされると、GitHub は子のターゲットを自動的に <base_branch> に変更します（またはスタックをリベースしてください）。スタックすることで、各プルリクエストが小さく、独立してレビューできる状態に保たれます。これがスタックの目的です。
• single — 1 つの大きなプルリクエスト。 すべてのタスクを <run_branch> にコミットし、ループの最後に実行全体を含む gh pr create --base <base_branch> を 1 回実行します。レビュー担当者が 1 つのレビューを希望する場合や、スタック用ツールが利用できない場合に使用します。
• none — ローカルのみ。 タスクごとにコミットしますが、プッシュやプルリクエストは行いません（元の動作）。オフラインでの作業や、人間が自分でプルリクエストを作成する場合に使用します。

各プルリクエストの URL を台帳の change ノートに記録してください。

台帳

<sandbox_root>/ledger.tsv はタブ区切りです。自由記述にはカンマを使用しません。列は iter task phase tests quality pass note です。

iter	task	phase	tests	quality	pass	note
0	-	baseline	34/34	-	-	clean baseline; 34 passing tests
1	T1	engineer	-	-	-	implement config loader src/config.py
1	T1	qa	36/36	min4	yes	authored 2 tests; rubric all >=4
2	T2	engineer	-	-	-	add retry to client.py
2	T2	qa	37/38	min3	no	test_retry fails; backoff off-by-one
3	T2	qa	38/38	min2	no	tests green but readability=2: nested 5 deep
4	T2	qa	38/38	min4	yes	flattened; kept

tests は全テストスイートでの passed/total、quality は最小軸スコア（min4 は最低軸が 4）、phase は {baseline, engineer, qa, keep, blocked} のいずれかです。保持またはブロックされたタスクについて、最終状態を報告してください。

制約

• 書き込みスコープを分離します。 エンジニアはソースファイルのみを編集し、QA はテストファイルのみを編集します。これがループの要です。作成者が評価対象のテストを弱めることも、批評者がテストに合格させるためにソースを修正することもできません。スコープをまたぐ変更は、ゲートで即時不合格となります。
• 依存関係の順序に従い、タスクは一度に 1 つだけ処理します。 保持されていないタスクを土台にしてはいけません。未完了の依存タスクがあると、それ以降の結果はすべて信頼できなくなります。
• ゲートに例外はありません。 テストに合格し、回帰テストスイート全体が成功した状態を保ち、品質基準を満たした場合にのみ、タスクを保持します。テストに合格していてもコードの品質が低ければ未完了です。コードがきれいでもテストに失敗していれば未完了です。
• テストは強化のみとし、計画に従います。 QA のテストはタスクの acceptance_criteria を証明するものでなければなりません。変更を通すために、合格済みテストを弱めたり、スキップしたり、削除したりしてはいけません。
• 作業を避けるために計画を編集してはいけません。 tasks.json は契約です。実際の欠陥がある場合は、タスクをひそかに書き換えるのではなく、人間に確認する open_question とします。
• 完了または実際のブロッカーに到達するまで自律的に実行してください。「続けてもよいですか？」と尋ねて停止してはいけません。

役割

• roles/engineer.md — コードの作成者です。サブエージェントを起動するか、起動できなければインラインで処理します。Claude Code では、実際に分離されたサブエージェント（Agent/Task ツール）を起動し、それ以外ではインラインで処理します。ソースを編集し、schemas/change.schema.json を返します。
• roles/qa.md — テストの作成者であり、品質の批評者です。同様にサブエージェントを起動するか、起動できなければインラインで処理します。テストを編集し、テストスイートと tools/quality_check.py を実行し、rubrics/quality-rubric.md に基づいて評価して、schemas/verdict.schema.json を返します。

停止条件

このループは、すべてのタスクが実装されて保持されるか、タスクが <task_budget> 回の反復後にブロックされるまで自律的に実行されます。ブロックが発生した場合は停止し、該当タスク、現在の fixes、および open_question を報告してください。テストの意図に反するのに形式上だけ合格する変更を無理に通すより、実際の障害を明らかにすることが重要です。同じ理由でタスクが失敗し続ける場合は、行き詰まった方針を改良し続けるのではなく、エンジニアに別の方法へ pivot するよう指示してください。