要求仕様書作成ループ

コーディングエージェントの開発ループの手前に、利用者と回す要求確定ループ、エージェント同士の仕様レビューループ、並行する実現性・コストのループを置き、確定仕様からテストと契約を生成して開発ループへ渡す構成

概要

テスト・ビルド・静的解析で囲った開発ループ（ハーネス）が保証するのは「仕様どおりに動くか」まで。仕様そのものが間違っていれば、エージェントは間違ったものを高速に作り続ける。人間なら曖昧な仕様を聞き返せるが、自律型エージェントは「それらしいコード」を大量に書き、Garbage In, Garbage Out がエージェントの速度で増幅される。

そこで開発ループの手前に、要求を確定させるループと仕様をレビューするループを置き、並行して予算のループも回す。品質確保を上流へ前倒しするシフトレフトをエージェント開発に当てはめた形である。

ループ	保証するもの	問い	終わる条件
要求確定・仕様レビュー	Validation	作るべきものは正しく定義されているか	利用者のサインオフ
実現性・コスト（上流と並行）	Feasibility	この予算と期間で作り、運用できるか	予算責任者のサインオフ
開発ループ	Verification	作ったものは仕様どおりに動くか	テストが Green

仕様の段階で直すならかかるのはトークン代だけだが、開発ループに持ち込むとコード修正・テスト・環境リセットの重い往復になる。

詳細

第 1 ループ: 利用者と回す要求確定ループ

利用者が気にするのは OpenAPI ではなく「業務ルールが漏れなく矛盾なく反映されるか」なので、技術用語を使わず業務の言葉で回す。Requirement Agent がヒアリングメモを業務ルール・決定表・ユースケースに構造化し、Business Red Team Agent が「もし〇〇の場合は？」を洗い出して起票し、利用者と合意する。確認に使う成果物は 4 つ。

Q&A 表（qa.csv） — 未決定事項の台帳でループの軸。列は No・起票元・質問・選択肢・回答・反映先・状態（＋費用への影響）。ヒアリングの台本、回答を反映した証拠、利用者へのフィードバックを兼ねる
決定表 — 条件を全部掛け合わせると、誰も口にしなかった組み合わせが「未定義」の空欄として浮かぶ
日本語の Gherkin — # language: ja で利用者が業務の流れとして読める。後段でそのままテストの元になる（BDD と Gherkin）
画面プロトタイプ — 利用者はテキストより画面の動きで矛盾に気づく

コツは、エージェントに異常系の意地悪な質問を作らせること、オープンクエスチョンにせず**仮説付きの選択肢（A / B）**で聞くこと、サインオフの対象を「Q&A 表の未回答 0 件＋シナリオの承認」と定義すること。実践では MkDocs を正本にし、レビュー会ごとに Claude Code で PPTX を生成している。

第 2 ループ: エージェント同士で回す仕様レビューループ

役割	仕事
Planner	確定した要求を入出力・エラー・状態遷移まで含む開発向け仕様に書き下す
Red Team	通信断・連打・空入力などのエッジケースや矛盾を突く
Domain Checker	既存システム・社内規約・セキュリティポリシーとの不整合
Formal Checker	決定表・計算ルール（Z3）、並行・リトライ・取り消しが絡むフロー（TLA+）、権限（Alloy）を形式化して検査器に探させる

指摘は振り分ける。リトライ回数のように開発者が決めてよいものは仕様に書き、通信断で注文を残すかのように利用者の判断が要るものは業務の言葉に直して Q&A 表で要求確定ループに差し戻す。開発者が勝手に決めてはいけない論点を黙って仕様に埋め込まないための関所が Q&A 表である。

形式検査の反例は具体的な入力なので Q&A 表と相性が良い（「3,001 円の注文でクーポンを使うと下限の 1,800.6 円を割ります。A と B のどちらにしますか？」）。回答待ちの反例は xfail(strict=True) などの「失敗するはず」のテストで残す。形式化の前提（端数処理など）も利用者に確認し、「反例なし」は空振りを疑う（形式手法）。形式手法は仕様内部の整合性しか見ないので、要求確定ループの代わりにはならない。

抜ける条件: TBD と Q&A 表の未回答が 0 件、仕様チェックリスト（入出力・エラー・境界値・状態遷移）が埋まっている、決定表の全行と全シナリオに対応するテストケースが 1 つずつ書ける（テストを書き起こせない仕様は未確定）、形式検査の対象で反例なし。

並行ループ: 予算責任者と回す実現性・コストのループ

決める人（利用者 vs 予算責任者）、知識、終わる条件が違うので別ループにし、コストが範囲とトレードオフなので並行で回す。途中成果物から規模を機械的に数えて開発費を、基盤案を IaC で書いて Infracost などで運用費を出す（エージェントが文章で答えた概算は使わない）。運用費を決める非機能要求（夜間停止の可否、データ保持期間）は利用者しか答えられないので、「費用への影響」列付きで Q&A 表に起票し、利用者が機能と費用を同じ表で比べて選べるようにする。

成果物は正本リポジトリ 1 つに置き、docs/shared/（qa.csv・決定表・非機能要求）、requirements/（利用者向け）、feasibility/（予算責任者向け）、proposal/（決裁者向け提案書の手書き部分）に分け、MkDocs のサイトは読者ごとにビルドする（利用者向けは exclude_docs で内訳を除外）。サインオフは req-signoff-v3 / budget-signoff-v2 のような git タグで記録し、両タグ時点の docs/shared/ が一致することを CI で確かめてから先へ進む。提案書とマイルストーンは正本から生成する。

仕様駆動のスキャフォールディング

確定仕様から開発ループの起点を一括生成する。入力がテンプレートではなく確定仕様で、生成物の一部（テストと型）は読み取り専用のゴールである点が普通の雛形と違う。

構造化 — 仕様を LLM が誤解なく扱える中間表現 spec_ir.json に（エンドポイント、正常・異常・境界値の条件、データモデル）
契約 — LLM が openapi.yaml を生成しリンター（Redocly CLI、Spectral）で検査。型は openapi-typescript で LLM を通さずに生成
テストハーネス — 契約テスト、境界値・状態遷移からの Red テスト、MSW のモックとシードデータ。生成後に全テストが失敗することを確認する
引き渡し — 実装エージェントに「tests/generated/ を全部 Green にせよ」と指示

ガードレールは 2 つ。LLM の出力は tsc --noEmit・ESLint・Spectral などの決定論的ツールで二重チェックする。テストは読み取り専用にし、CI で git diff --exit-code tests/generated/ を走らせる（書き換えられるならテストを緩めるのが最速の Green になる）。

Claude Code プラグインにするなら（設計案）

要求側は dev-loop（Issue 1 件を verify 通過で 1 周させるプラグイン）とは別の 1 プラグインにし、中にループごとのスキルを置く。

dev-loop と分ける理由 — dev-loop は verify で止まるが、要求側は人間の判断（利用者の回答、予算責任者の合意、決裁者の承認）を待って止まる。1 周の単位も Issue 1 件とレビュー会 1 回で違う。境界は Issue と spec_ir.json・Red テストというファイルで表せる。開発中に見つかった仕様の穴を Q&A 表へ差し戻す取り決めは dev-loop 側に新たに足す
要求側を 1 プラグインにまとめる理由 — ツリー構成・qa.csv の列・タグの命名というデータの決まりを references/ の 1 か所に置き、写しの更新漏れと、利用者の手元でプラグインの版がそろわない食い違いを防ぐ
1 スキルにしない理由 — 1 回の実行は「次の人間の判断まで」。再開点は会話ではなく Q&A 表の状態とタグに残す

スキルは req-loop・spec-review・feasibility・proposal・scaffold の 5 つ。dev-loop から、書き込みツールを持たない別ティアの判定役を agents/ に置く（maker-checker）、CSV 検証やタグ照合など答えが一意の処理は scripts/ にする、プロジェクト固有の事情は対象リポジトリの CLAUDE.md から読む、の 3 つを持ち込む。最初は手作業でいちばん繰り返している req-loop だけを作り、references/ は 2 つ目のスキルの前に書く。人間の判断をスキルが推測で埋めてはいけない。