要求仕様ループを Claude Code プラグインにする — dev-loop と分けて 1 プラグイン・複数スキルで組む

要求仕様書作成ループでは、コーディングエージェントの開発ループの手前に、要求確定・仕様レビューのループと、並行して回す実現性・コストのループを置く構成を整理しました。

開発ループのほうは、Claude Code のプラグイン dev-loop として作ってあります。GitHub Issue 1 件を、検証（verify）が通ることを停止条件にして 1 周させるプラグインです。

では、要求側のループ（要求確定、仕様レビュー、実現性・コスト、提案書の生成）も、同じようにプラグインにしたほうがよいのでしょうか。分け方には、少なくとも次の 3 通りが考えられます。

ループごとに別々のプラグインを作る
dev-loop も含めて 1 つの大きなハーネスにし、複数のスキルで構成する
要求側だけを 1 つのプラグインにまとめ、その中にループごとのスキルを置く。dev-loop とは分ける

この記事の結論は 3 です。要求側は 1 つの Claude Code プラグインにまとめ、ループごとにスキルを分け、dev-loop とは別のプラグインにします。なお、ここで書くのはまだ作っていない設計案で、dev-loop を作ったときの経験から考えたものです。

前の記事の用語を、この記事で使う範囲で説明しておきます。

Q&A 表（qa.csv）：利用者に聞く未決定事項の台帳。質問と選択肢を 1 行ずつ書き、回答と状態（確認中・反映済み）を追う
正本リポジトリ：要求・見積り・提案書の元ファイルをすべて置く、1 つの git リポジトリ
サインオフ：利用者や予算責任者の承認。git のタグで記録する。開発に進む前には、2 つのサインオフがそろっているかを確かめる関門を置く
スキャフォールディング：確定した仕様から、仕様の中間表現（spec_ir.json）、OpenAPI と型定義、Red テスト（まだ実装がないので失敗するテスト）を生成する工程

要求仕様のループを dev-loop と分ける理由（案 2 を採らない）

止まる理由が違う

dev-loop は、verify が通ることを停止条件にして自動で回ります。人間に確認するのは、周の割り目（続けるか区切るか）、環境では証明できなかった項目のレビュー、本番反映のような不可逆な操作の前に限られます。

要求側のループは違います。人間の判断を待つことが、止まる理由そのものです。

ループ	何を待って止まるか
要求確定	レビュー会での利用者の回答
実現性・コスト	予算責任者の合意
提案書	決裁者の承認

仕様レビューだけは、エージェント同士で回るので人間を待ちません。ただし、利用者の判断が要る指摘は Q&A 表に差し戻すので、結局は要求確定ループの回答待ちに合流します。

1 周の単位も違います。dev-loop の 1 周は Issue 1 件ですが、要求確定ループの 1 周はレビュー会 1 回です。止まり方も周の数え方も違うものを 1 つのハーネスにまとめると、どちらの停止条件も曖昧になります。

受け渡しの契約がはっきりしている

要求側の最後の工程はスキャフォールディングです。ここで出てくる spec_ir.json、OpenAPI と型定義、Red テストを Issue に分けて登録すれば、dev-loop の入力（Issue 1 件）にそのままつながります。

つまり、2 つのプラグインの境界は Issue と、そこから参照するファイル（spec_ir.json・Red テスト）です。境界がファイルで表せるので、プラグインを分けても受け渡しで迷いません。

逆方向の流れも決めておきます。開発中に仕様の穴が見つかったら、実装で勝手に決めず、要求側の Q&A 表に起票して差し戻す、という取り決めです。今の dev-loop にはこの規定がないので、要求側のプラグインを作るときに、dev-loop 側にも足す必要があります。

要求側はループごとに分けず、1 つのプラグインにする（案 1 を採らない）

データの決まりを 1 か所にするため

要求側の 4 つのループは、同じデータの決まりを共有します。

正本リポジトリのツリー構成（docs/ の下の shared/・requirements/・feasibility/・proposal/）
Q&A 表（qa.csv）の列（No・起票元・質問・選択肢・回答・反映先・状態・費用への影響）
サインオフのタグの命名（req-signoff-v3・budget-signoff-v2 など）

ループごとに別のプラグインにすると、この決まりの写しがプラグインごとにでき、いずれずれます。

ずれ方は 2 通りあります。1 つは、同じ決まりを何か所にも書くと、直すときに一部だけ直し漏れることです。dev-loop でもこれが起きました。手順の決まりを README・設計ページ・SKILL.md など約 20 か所に書いていたところ、更新漏れが何度も出ました（#94）。そこで、決まりの原本を SKILL.md に寄せ、ほかの場所はそこを指すだけにしました。

もう 1 つは、プラグインの版が利用者の手元でそろわないことです。プラグインは導入したときの版のまま使われ続けることがあり、dev-loop でも古い版が長く使われていた例がありました。プラグインが分かれていると、「要求確定は新しい列を書くのに、見積りは古い列しか読まない」といった食い違いが起きます。

1 つのプラグインにまとめ、データの決まりはプラグインの references/ に 1 回だけ書き、各スキルはそこを読むようにすれば、どちらのずれも防げます。

スキル 1 つにはまとめない — 1 回の実行は次の人間の判断まで

案 3 の中での粒度の話です。要求側の全部を 1 つのスキルにまとめるのもよくありません。各ループは人間の判断を待つ地点で必ず止まるので、1 回の実行で最後まで進むことがないからです。

スキルの 1 回の実行は「次の人間の判断まで」と区切ります。どこまで進んだかは、会話ではなくファイルに残します。Q&A 表の各行の状態とサインオフのタグがあれば、次の実行はそこから再開できます。dev-loop が再開点を計画ファイルに書くのと同じ考え方です。

Claude Code プラグインの構成案（spec-loop）

dev-loop の作りに合わせると、次のような構成になります。4 つのループに、dev-loop への引き渡しを担う scaffold を加えた 5 つのスキルです。

plugins/spec-loop/
├── skills/
│   ├── req-loop/       # 1 周 = レビュー会 1 回：Q&A 起票 → PPTX 生成 → 回答の反映
│   ├── spec-review/    # Planner が書き下し、3 役のレビューで抜ける条件を判定
│   ├── feasibility/    # 見積りとスケジュールの更新、費用付きの質問の起票
│   ├── proposal/       # 関門の確認（タグの照合）と提案書の生成
│   └── scaffold/       # spec_ir.json → OpenAPI・型・Red テスト → Issue 化（dev-loop への引き渡し）
├── agents/             # red-team / domain-checker / formal-checker / 見積りの検証役
├── references/         # データの決まり（ツリー構成・qa.csv の列・タグの命名）
└── scripts/            # 決定論的な処理：CSV の検証、タグの照合、ガントチャートとサイトの生成

各スキルの役割と、止まる地点は次のとおりです。

スキル	1 回の実行でやること	止まる地点
req-loop	未決定事項を Q&A 表に起票し、レビュー会用の PPTX を生成する。前回の回答を仕様に反映する	利用者の回答待ち
spec-review	Planner が仕様を書き下し、Red Team・Domain Checker・Formal Checker の 3 役がレビューして、指摘を振り分ける	ループを抜ける条件を満たすか、Q&A 表に差し戻すまで
feasibility	途中成果物から規模を数え、開発費・運用費・スケジュールを更新する。費用付きの質問を起票する	予算責任者の合意待ち
proposal	2 つのサインオフのタグが同じ範囲を指すかを確かめ、提案書を生成する	決裁者の承認待ち
scaffold	確定した仕様から OpenAPI・型・Red テストを生成し、Issue に分けて登録する	Issue の登録まで（以降は dev-loop）

dev-loop から持ち込む 3 つの考え方

判定は、書き込みツールを持たない別のエージェントにさせます。 dev-loop の検証役（dev-loop-verifier）は、Read・Grep・Glob・Bash だけを持ち、ファイルを書くツールを持ちません。呼ぶときは、実装とは別のティア（性能や系統の段階が違うモデル）を指定します。同じモデルだと、実装した側と盲点を共有してしまうからです。

要求側でも、Red Team・Domain Checker・Formal Checker・見積りの検証役を同じ形で agents/ に置きます。仕様を書いた側と、仕様を批判する側を分けるためです。Planner は書く側なのでスキル本体が担い、批判する側だけを agents/ に置きます。

答えが一意に決まる処理は、スクリプトにします。 たとえば、Q&A 表の CSV が決まりどおりの列を持っているか、利用者のサインオフのタグ（req-signoff-v3）と予算責任者のタグ（budget-signoff-v2）の時点で docs/shared/ の中身が一致しているか、schedule.csv からガントチャートを生成する処理です。これらを LLM に毎回判断させると、結果がぶれます。dev-loop も、worktree の準備や PR の前提条件の確認をスクリプトに切り出しています。

プロジェクト固有の事情は、対象リポジトリの CLAUDE.md から読みます。 dev-loop は、実機検証のコマンドやデプロイの経路を、対象リポジトリの CLAUDE.md から見つけて従います。見つからなければ、汎用の手順で進めます。要求側のプラグインでも、ドキュメントのツール（MkDocs か、別のツールか）、レビュー会のスライドの形式、形式検査の対象などは、プロジェクトの CLAUDE.md に書いてもらい、プラグインには持たせません。

要求側プラグインを作るときの注意

最初から 5 つのスキルを作らない。 まずは、手作業でいちばん繰り返している req-loop（Q&A 表の起票と PPTX の生成）から作り、残りは手作業で回しながら決まりを固めます。references/ のデータの決まりは、2 つ目のスキルを作る前に書いておきます。
人間の判断を、スキルの中で代わりにしない。 利用者の回答、予算責任者の合意、決裁者の承認は、スキルが推測で埋めてはいけません。スキルの仕事は、判断に必要な材料（選択肢付きの質問、費用への影響、生成元のタグ）をそろえて止まることです。
dev-loop との境界を Issue の形で決めておく。 scaffold が作る Issue に、どの受入基準・どの Red テスト・どの Q&A の回答に対応するかを書いておけば、dev-loop は Issue 1 件を読むだけで周を始められます。仕様の穴を Q&A 表に差し戻す規定も、このとき dev-loop 側に足します。

まとめ

dev-loop とは分ける。dev-loop は verify で止まるが、要求側は人間の判断を待って止まり、1 周の単位もレビュー会 1 回と違う
2 つのプラグインの境界は Issue と、そこから参照するファイル。scaffold が仕様から Issue を作り、dev-loop がそれを 1 件ずつ回す。仕様の穴を Q&A 表に差し戻す取り決めは、新たに dev-loop 側に足す
要求側の 4 つのループは 1 つのプラグインにまとめる。データの決まり（ツリー・qa.csv の列・タグの命名）を references/ の 1 か所に置き、写しと版のずれを防ぐため
スキル 1 つにはまとめない。各スキルの 1 回の実行は次の人間の判断までで、再開点は Q&A 表の状態とタグに残す
dev-loop から、書き込みツールを持たない別ティアの判定役、決定論的な処理のスクリプト化、CLAUDE.md からのプロジェクト設定の発見を持ち込む
最初は req-loop だけを作り、references/ の決まりは 2 つ目のスキルを作る前に書く