概要
テスト・ビルド・静的解析で囲った開発ループ(ハーネス)が保証するのは「仕様どおりに動くか」まで。仕様そのものが間違っていれば、エージェントは間違ったものを高速に作り続ける。人間なら曖昧な仕様を聞き返せるが、自律型エージェントは「それらしいコード」を大量に書き、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 つ目のスキルの前に書く。人間の判断をスキルが推測で埋めてはいけない。
実装後の姿: 版ごとの仕様とスクリプトの関門
プラグインとして形になった後の構成では、仕様は docs/v<n>/ に版ごとの差分として置き、スクリプトで重ね合わせて版の全体を組み立てる。リリースした版は凍結し、v2 以降の提案書には前の版との比較(追加・変更・削除)を載せる。機械で決められる関門はスクリプトが判定する。
check-signoff.py— 要求確定と予算の 2 つのサインオフのタグが同じ共有の範囲を指すかを照合し、一致しなければ提案書を作らないcheck-spec-exit.py— Q&A 表に未反映の行がないこと、仕様にTBD・未定などの印が残っていないことを判定するscaffold.py— Issue や Red テストを作る前に同じ関門を自分で通し、暫定の回答が残っていれば何も作らない
機械で決められない条件(チェックリストやテストケースの欠け、形式検査の反例)は、書き込みツールを持たない判定役 3 体と見積りの検証役を、仕様を書いたモデルとは別のティアで走らせて判定する。版の全体を残すので仕様の膨張は実際に起き、ある案件では要求 190 行・決定表 15 行に対して仕様 768 行・テストケース 300 件になった。テストケースが要求と決定表より速く増えたら「減らす見直し」をする歯止めを入れている。
Formal Checker と TLC:設計と実案件で見えた穴
TLC を使うのは spec-loop の spec-review だけで、dev-loop には TLA+ も TLC も出てこない(dev-loop へは scaffold が作る Red テストと Issue を通じて間接的につながる)。定義は agents/formal-checker.md(使い方の本体)、skills/spec-review/SKILL.md(TLC の有無の確認)、references/tree.md(モデルの置き場所 spec/formal/)に分かれている。
- 対象を選ぶのは Planner:決定表・計算ルールは Z3、並行・リトライ・取り消しを含む業務フローは TLA+(TLC)、権限・ロールは Alloy。TLC の対象は、状態を持つ業務フローを新しく足すか既存フローの状態・遷移を変えるときだけで、既存の書き手に排他を足すだけなら性質とテストで受ける。フローが前からあるかは要求と既存システムを読み合わせないと決まらないので、選ぶのは仕様を書く Planner で、Formal Checker は選び方が規則に反すれば指摘する
- 起動前に道具を確かめる:Java と
tla2tools.jarが無ければ判定役を 1 体も起動せず、用意するか進めるかを利用者に訊く。プラグインが自分で入れることはしない - 形式化の決まり:性質(不変条件)の水準で書き、ロック方式や書き込み順はモデルに入れない。構成は性質が破れうる最小(ふつう 2〜3)から。モデルは
$TMPDIRに書いて全文を報告に含める。時間切れの検査を「反例なし」と書かない - 「反例なし」の条件:正常な状態に到達できることと、ルールを 1 つ壊した版で反例が出ること(陽性対照)の 2 つを示す。示せなければ「判定できなかった」
- 代用しない:決定表は道具が無ければ Python 標準ライブラリで総当たりするが、業務フローは「実行順の爆発を手で区切ると、区切り方が結果を決める」ので「検査できなかった」と報告する
実案件(ラベル体系の入れ替え)では、spec-review を抜けるまで約 23 時間・14 回・指摘のべ約 312 件かかった。10 回目は TLC が無く抜けられず(→ 起動前の確認を追加)、11 回目に TLC が「処理の途中で版が切り替わると、下落監視と表示が別の行を選ぶ」反例を見つけ、11〜13 回目は書き手 7〜10 人の構成で検査が膨らんで一度判定できなかった(→ 対象を改修の性質で選ぶ・構成は最小から)。
評価すると、判定を LLM ではなく検査器に置く、空振りを陽性対照で疑う、代用しない、状態爆発を運用の規則で抑える、の 4 点はよくできている。穴は 2 つある。
- 線引きが本物の反例まで外に出す:「排他を足すだけ」を対象外にした結果、11 回目の反例は Red Team が見つけるしかなく、見つかる保証は無い。膨らんだ原因は構成の大きさで、それは「最小から」で既に抑えている。性質が複数のステップ・版・処理の途中をまたぐなら最小構成(書き手 2 人)の TLC を残す、という線を提案した
- モデルと反例トレースが残らない:置き場所
spec/formal/は定めてあるのに、Formal Checker はモデルをリポジトリの外に書き、spec-review には保存する手順が無い。そのため毎回モデルを組み直して前回の「反例なし」と比べられず、トレースも scaffold の Red テストに落ちず dev-loop に届かない
先に直すべきなのは 2 のモデルの保存とトレースの引き渡し。モデルが残らないと、線を見直しても前後の検査結果を比べられない。
同名の dpolivaev/spec-loop は、方向が決まった後の実装の一歩一歩を開発者と回すもので、重なるのはこのプラグインではなく後ろの dev-loop である。比較と取り入れ方は 仕様駆動開発(SDD) にまとめた。
cc-sdd を軸にした外部のフローと比べて見えた不足
非エンジニアの社長が Claude Code で作った巨大 PR を受け止めるため、cc-sdd を軸に役割別エージェント・計画段階の CTO レビュー・CodeRabbit・Takumi Guard・司令塔エージェントを組んだ事例がある。そこから読み取れる原則は、人間のゲートを前(計画)に寄せる、書く役と見る役を分け、別系統のレビューを重ねる、自動化できない判断(リリース判断)だけを人間に残すの 3 つ。
| 要素 | 外部のフロー | spec-loop / dev-loop |
|---|---|---|
| 実装前の人間のゲート | 計画の PR を CTO がレビュー | 要求と予算の承認をスクリプトで照合(dev-loop 単独では無し) |
| 作業とレビューの自動ループ | 司令塔エージェント | cruise / autopilot |
| 実装の検証 | レビュアーと CodeRabbit | 別ティアの Verifier と /code-review の 2 関門 |
| 形式検査 | 記載なし | TLA+ / Alloy |
| 依存パッケージの安全性 | Takumi Guard | なし |
| 系統の違うレビュアー | CodeRabbit | なし |
| 持ち込まれたコードの扱い | 社長の PR を起点にする | 入口がない |
| 依頼の振り分け | /kiro-discovery | なし |
仕様の厳密さ・検証・承認(判定役にファイルを書かせない、検証通過を停止条件にする、形式検査、承認範囲の機械照合)は spec-loop / dev-loop のほうが踏み込んでいる。欠けていたのはコードの外側の守りと入口で、次の 3 件を起票した。
- 依存パッケージが悪性でないかを見る関門(利用者不在の周でエージェントが依存を足しても誰も見ない)
- 外部レビュー bot のコメントを指摘の採否表に取り込む(関門には格上げせず、信頼できない入力として扱う)
- 持ち込まれた動くコードから要求の候補と暗黙の業務ルールを抜き出して Q&A 表に起票する(コードはマージせず、確定は利用者の回答で)
依頼の振り分けは未起票の検討課題。dev-loop は「小さいから」で手順を省かない設計なので、変えるべきは周の厳密さではなくどのループに乗せるかの入口である。入口がないと小さな依頼まで重い仕様のループに乗り、非エンジニアが使い続けにくくなる。
関連ページ
- 仕様駆動開発(SDD) — SDD の全体像と、実装側を受け持つ同名の dpolivaev 版との比較
- 形式手法(Formal Methods) — Formal Checker の道具と反例の扱い
- TLA+ と TLC — Formal Checker が業務フローの検査に使うモデル検査器
- ハーネスエンジニアリング — 開発ループ側の実行環境の設計
- ループエンジニアリング — 合格条件と人間のゲートの置き方
- 作る役と確かめる役の分離(maker-checker) — Planner と批判役、判定役を分ける理由
- BDD と Gherkin 構文 — 日本語シナリオを実行可能な仕様にする
- Claude Code — プラグインとスキルの実行基盤
- cc-sdd — 比較対象にした Kiro 式の SDD スキル
ソース記事
- 要求仕様書作成ループ — コーディングエージェントの開発ハーネスの手前に「要求確定」と「仕様レビュー」のループを置く — 2026-10-09
- 要求仕様ループを Claude Code プラグインにする — dev-loop と分けて 1 プラグイン・複数スキルで組む — 2026-10-12
- AI 仕様駆動開発の 2 つの spec-loop を比べる — 実装ループと要求確定ループ — 2026-10-25
- spec-loop は TLC をどう使っているか — Formal Checker の設計と、実案件で見えた 2 つの穴 — 2026-11-08
- 非エンジニアの社長が出した巨大 PR をどう受け止めるか — cc-sdd・CodeRabbit・Takumi Guard で組む AI 駆動開発フロー — 2026-11-13