| name | prd-loop |
| description | PRDを不変入力として、ギャップ分析、Issue化、実装PR、敵対レビュー、マージ、台帳同期、独立最終レビューを完了または明示停止条件まで反復する。"$prd-loop path/to/prd.md"、"PRDを完了まで回して"で使う。完了可否のレビューだけならprd-completion-review、単一Issueの実装ならissue-to-prを使う。 |
PRD Loop
PRD の Acceptance Criteria / 完了条件を満たすまで、実装ループを反復する。
1周は、ギャップ分析 → $issue-creater → $issue-to-pr → $review-pr →
マージと台帳同期で構成する。全条件が満たされた候補状態でのみ
$prd-completion-reviewを実行する。
監査は二層構造とする。周回側は次の1周を選ぶための差分駆動の作業判定、
完了の最終判定は $prd-completion-review の全数・独立監査である。
周回側の記録(台帳・checklist)は進行ログであって証拠ではないため、
最終監査が独立に再抽出する情報を周回側で複製・維持しない。
実装前のshadow実装、大規模または恒久的なevidence packet、または事前監査だけを目的とする全条件の
実装対応表を作らない。
実装・検証の証拠はPRの固定headとその検証結果に一本化する。
入力
- PRD ファイルパスは必須。
$prd-loop docs/prd/<prd-file>.md のように受け取る。
見つからない場合だけ短く確認する。
- 任意入力:
max-iterations <N>: この実行で回す最大周回数。既定は無制限であり、
完了または他の停止条件に達するまで回り続ける。明示指定された場合のみ
budget として扱う。- 対象の絞り込み(例: 「R1-R2 のみ」「schema 関係だけ」)。指定があれば
ギャップ分析の対象をその範囲に限定する。
基本方針(ループ工学)
- 完了判定は二段階で行う。 周回側のギャップ分析は次の1周を選ぶための
作業判定であり、差分駆動でよい(手順1)。すべて満たしたように見える場合でも、
tracking Issue を close する前に
$prd-completion-review を最終達成条件
レビューとして実行する。達成済み 以外なら完了扱いにせず、finding を
次のギャップとして扱う。全数の実体照合は最終レビューの責務であり、
最終監査の強度を各周回に持ち込まない。
- 状態は GitHub に置く。 ループの進行状態(どの完了条件が満たされ、どの Issue / PR が
対応するか)は tracking Issue とその sub-issue / PR に記録する。セッション内の記憶に
依存しない。これにより、ループは中断後も新しいセッションで同じ地点から再開できる。
- 1周 = 1 Issue = 1 PR。 小さく切り、レビュー可能な単位で回す。複数の完了条件が
単一の実装で自然に閉じる場合だけ、1 Issue にまとめてよい。
- PRD はループの不変条件である。 ループ中に PRD を編集しない。実装の途中で
PRD 自体の欠陥(矛盾、実装不能な要求、誤った理論参照)が判明したら、それを直さずに
停止し、欠陥の内容と修正案を報告する。PRD の変更は人間の判断である。
- 進捗ゼロを検出して止まる。 同じ完了条件で2周連続して PR がマージに至らない場合、
その条件を
stalled として停止条件に従う。回り続けることより、止まって報告することを優先する。
- PRD が要求していない巨大な一般 claim を、未完了タスクとして追加しない
(
docs/workflow/guideline.md「完了レビューの判定範囲」)。ギャップ分析は PRD の完了条件の文言に限定する。
- 完了への最安経路を塞ぐ(インセンティブ規律)。 ループは放置すると
「マージが通る最も安い経路」(記載の付け替え、条件の再解釈)へ収束する。次を禁止する。
- 実装・証明・発火を要求する完了条件を、docs / 台帳記載のみの PR で check しない。
docs-only PR で check してよいのは、PRD がその条件に docs 処置を要求している場合だけ。
- 処置種別の降格(昇格 → 実質化 / 宣言 / 削除 など)は、PRD が明示的に許可した項目
(等級リスト等)に限る。許可外の降格が必要と判明した項目は
blocked として
ユーザーへエスカレートする。降格を Issue や台帳の文言で再定義しない。
- stall 回避のために完了条件を再解釈・降格しない。進まない項目は stalled として
正直に止まる。止まることは失敗ではなく、ループの仕様である。
- Issue の受け入れ要件は PRD 文言の引用で書く。 採否規律・中心方針を弱める再表現
(降格許容対象の拡大、限定の削除)を sub-issue に持ち込まない。
sub-issue と PRD が食い違う場合は PRD が正である。
- 完了まで回り続ける。 既定では周回数に上限を置かない。止まるのは、完了したとき、
または停止条件(全 blocked / stall / PRD 欠陥 / 明示指定された budget)に
該当したときだけである。
サブエージェント活用
次の工程を明示的にレビューgateへ委譲する。レビューgateが実行不能、またはBlockedを
返した場合は、本体が代替せず該当工程を Blocked に落とす(fail-closed)。
- レビュー(手順4):
$review-pr を実行する。
PR のレビュー責務は $review-pr 側に閉じる。
- 再レビュー(手順4): Needs changes後の修正と確認は、共有review protocolの
「レビューバッチと修正後確認」に従う(直接対応の資格条件と確認subagentの検査義務は
同節が正本)。修正はfindingをまとめて行う。直接対応の確認が未解消または資格喪失を
返した場合は、
Needs changes 1回として数える。
- エスカレーション(手順4): 同一 Issue で
Needs changes が2回続いたら、
3回目は同じレビューを繰り返さず、より強いゲートに切り替える。Lean 系は
$math-lean-review の正式判定に切り替える。それでも通らなければ
従来どおり stalled として停止する。
ゲートのセマンティクスは math-lean-review 側の定義が正であり、
ここでは「いつ呼ぶか」だけを規定する。
- 自己点検(手順3内):
$issue-to-pr のローカル自己点検・検証・
PR 規律を周回を急ぐ目的で省略しない。
- ギャップ分析(手順1): 完了条件の項目数が多い場合、項目群ごとの実装照合を
サブエージェントへ分割して並列実行してよい。結果の統合、分類の最終判断、
次周回の対象選定は本体が行う。
- 最終達成条件レビュー(手順6):
$prd-completion-review を実行する。
PRD 完了レビューの責務は $prd-completion-review 側に閉じる(実行不能または
Blocked の場合は fail-closed で停止。本体の順次実行での代替は不可)。
ループを進めた本体の
「全部満たしたはず」という前提を渡さず、PRD パス、tracking Issue、
関連 PR / Issue、現在の main の状態だけを raw context として渡す。
サブエージェントには、対象(PR 番号、完了条件の項目、照合対象ファイル)と
期待する出力形式を明示して渡す。本体の推測や途中経過は渡さない。
ループ台帳(tracking Issue)
台帳は進行ログであり、証拠ではない。最終達成条件レビューは PRD から条件・
拘束・must-not-remain を独立に再抽出し、台帳を監査対象として扱う。
したがって台帳には再開に必要な最小情報だけを置き、PRD の内容を複製しない。
- 初回実行時、対象 PRD の tracking Issue を探す。タイトル
PRD Loop: <PRD ファイル名> で
open Issue を検索し、なければ作成する。
- tracking Issue の本文には次だけを置く。
- PRD パスとコミット時点の参照
- 完了条件の checklist(PRD の Acceptance Criteria を1項目1行で写す)
- 各項目の分類:
実装検証系(コード・テスト・fixture で検証する)/
PRD 記述系(PRD 本文自体が満たしている。初回に check 済みにする)
- 各周回の終わりに、tracking Issue へコメントを1件追加する。
- 形式:
iteration N: <対象完了条件> → Issue #X → PR #Y → merged | needs-changes | blocked
- 完了条件を満たした項目は checklist を check し、根拠として PR 番号と
実行した検証コマンドを併記する。証拠の資格判定(条件文言と assertion
内容の対応を含む)は最終達成条件レビューが一次証拠で行う。
- すべて check されても、
$prd-completion-review の総合判定が 達成済み になるまでは
tracking Issue を close しない。
- 最終達成条件レビューの結果は tracking Issue にコメントする。
達成済み: レビュー結果、検証、main commit を記録して close する。未達あり / 未確認あり / PRD欠陥あり: finding を未達ギャップとして記録し、
対応 Issue を作成または既存 Issue に紐付け、ループを継続または停止条件に従う。
標準手順
-
前提を確認する。
git status --short --branch で作業ツリーを確認する。未コミット変更があれば
ループを開始せず報告する(ユーザー変更を勝手に戻さない)。git switch main と git pull --ff-only で最新化する。- PRD ファイルを読み、冒頭の「## 問い」と Acceptance Criteria / 完了条件の節に加えて、
改修 / Implementation Plan / 現状診断 / Failure Contract /
Changed / Removed Fields を確認し、次に実装する対象だけを選ぶ。
requirement matrix と must-not-remain リストの全数抽出は、最終達成条件レビューに委ねる。
- PRD が Lean 実装(
Formal/)を要求する場合、作業ごとに指定された
target statementの一次仕様を一意に特定し、実装中に参照できることを確認する
(docs/aat/lean_quality_standard.md §5: target claim、必要な結論、明示された
仮定・受け入れ条件)。完全Lean signatureは任意の補助情報とする。一次仕様から対象 claimを
特定できなければ、ループを開始せず PRD 欠陥 として停止・報告する。
- ループ台帳(tracking Issue)を確認または作成する。
-
ギャップ分析(プランニング)。
- 差分駆動で行う。 現在の対象と、その実装に必要な直接依存だけを
現状の実装(対象コード、schema、テスト、fixtures、docs)と突き合わせる。
未着手の全条件を事前監査したり、完成形の実装を先取りして作らない。
- 照合は文言ではなく実体で行う: 完了条件が要求するテスト・fixture・検証が
実際に存在し、通ることを確認する(必要なら
cargo test 等を実行する)。
- Lean 実装系の完了条件では、指定された一次仕様のtarget claimと
実装 declaration を直接突合する(
docs/aat/lean_quality_standard.md
§5.2)。完全Lean signatureがある場合はそれも照合する。premise の追加・結論の弱化・対象の縮小があれば、AC が check 済み
でも 未達 に戻す。固定 statement の変更が必要と判明した場合は
PRD 欠陥 としてユーザーへエスカレートする(§5.3 drift 規則。
ループ内で PRD を編集しない既存規律の適用)。
- tracking Issue の checklist が check 済みであることを
満たした の根拠にしない。
check は「過去の周回がそう主張した」ことしか意味しない。疑いがあれば実体を再確認する。
- 現在の対象が満たされたら、PRDを索引として読み、未着手の受入条件から次の対象を選ぶ。
この選定では全条件の実装照合、対応表、旧構造の全数検索を行わない。
- 未着手の受入条件と、既知の未達 / blocked / stalled 項目がなければ、tracking Issue を close せず
手順6の最終達成条件レビューへ進む。
PRD全体の全数照合は、この時点で一度だけ行う。
- 次の対象は、他の完了条件の前提になるもの(例: schema・入力契約が evaluator より先)、
依存が少ないもの、の順に選ぶ。
blocked(設計判断・理論証明・ユーザー入力が必要)は対象にせず、台帳に理由を記録する。
-
Issue を作成する。
$issue-creater を使い、選んだ完了条件のギャップを Issue 化する。- ループ内の sub-issue 起票では、重複照合は tracking Issue の既存 sub-issue と
この PRD に関連する open Issue に限定してよい(
$issue-creater の
全件走査は省略できる。Issue 本文の規律はそのまま適用する)。
- Issue は tracking Issue の sub-issue として紐付ける。
- Issue の
受け入れ要件 には、PRD のどの Acceptance Criteria 項目に対応するかを明記し、
該当 AC の文言を引用する。その条件に関わる拘束(降格可否、要求される処置種別)も併記する。
- 既存の open Issue が同じギャップを既に扱っている場合は、新規作成せずそれを使う。
停止条件
次のいずれかで、ループを止めて報告する。止まることは失敗ではなく、ループの仕様である。
完了: すべての完了条件が「満たした」かつ `$prd-completion-review` が `達成済み`。
tracking Issue を close する。
全 blocked: 未達項目がすべて blocked / stalled で、この実行で進められるものがない。
stall: 同一の完了条件が2周連続でマージに至らない。
budget: max-iterations が明示指定された場合のみ。その周回数に達した。
PRD 欠陥: 実装中に PRD 自体の矛盾・実装不能が判明した。
final review gap:
`$prd-completion-review` が未達 / 未確認を返し、この実行では新規周回に進めない。
既定では budget 停止はなく、完了まで回り続ける。
stall / 全 blocked / budget で止まった場合も、状態はすべて tracking Issue に残っているため、
次回 $prd-loop を同じ PRD で実行すれば同じ地点から再開できる。
報告形式
終了時に次の順で報告する。
- 終了理由:
完了 / 全 blocked / stall / budget / PRD 欠陥 / final review gap
- 完了条件スコアボード: 満たした / 未達 / blocked / stalled の項目数と一覧
- 最終達成条件レビュー結果:
$prd-completion-review の総合判定、findings、未達 / 未確認項目
- この実行の周回ログ: iteration ごとの Issue / PR / 結果
- マージした PR と main の最新コミット
- blocked / stalled / final review gap 項目の理由と、人間の判断が必要な点
- 次回再開時に最初に扱うべき項目
ループ固有の安全規則
- マージは
$review-pr の Mergeable 判定、または共有review protocolに従う直接対応確認、
CI green、修正後確認を含むレビュー監査記録のPR投稿済み、の3条件が揃った場合だけ行う。
- 1周の中で複数 PR を並行して open しない。レビュー・マージの追跡可能性を優先する。
