同じ「spec-loop」という名前を持つ 2 つのフレームワークを比べます。一方は実装の一歩一歩を、もう一方は開発の手前での合意を受け持ちます。違いと共通点、組み合わせ方を整理します。
前回の記事 では、dpolivaev さんの Spec Loop を紹介しました。「次の小さな仕様だけを書き、レビューし、テスト付きで実装する」を繰り返す、設計先行型のスキル集です。
実は筆者も、同じ spec-loop という名前の Claude Code プラグインを hdknr/claude-code-setup で作っています。考え方は 要求仕様書作成ループ に、プラグインとしての構成は 要求仕様ループを Claude Code プラグインにする に書きました。
以下、区別のために前者を「dpolivaev 版」、後者を「hdknr 版」と呼びます。
一言でいうと: 受け持つ工程が違う
- dpolivaev 版: 作業の方向が決まった後、実装の一歩一歩を「調査 → 設計 → 承認 → 実装 → レビュー」で統制する。相手は開発者
- hdknr 版: 開発ループの手前で、「何を作るか」「いくらかかるか」を確定させ、Issue にして渡す。相手は利用者・予算責任者・決裁者
hdknr 版では、Issue を受け取ってから実装・検証までを回すのは、別プラグインの dev-loop です。dev-loop は GitHub Issue 1 件を、検証（verify）が通ることを停止条件として 1 周させます。
図のとおり、hdknr 版で dpolivaev 版と重なるのは spec-loop ではなく、その後ろの dev-loop です。dpolivaev 版の比較ドキュメントは、自身の「広い問題領域の分析から始める」を 5 段階の ★★ と評価し、「作業の方向が決まった後に最も強い」としています。つまり、ちょうど hdknr 版の spec-loop が受け持つ部分を、dpolivaev 版は守備範囲外としているわけです。
dpolivaev 版と hdknr 版の比較表
用語を 2 つ補足しておきます。正本リポジトリは、要求・仕様・Q&A 表などの原本を 1 か所に置くリポジトリです。Red テストは、実装がまだないので失敗するテストで、実装が満たすべき振る舞いを先に固定します。
| 観点 | dpolivaev 版 | hdknr 版 |
|---|---|---|
| 受け持つ工程 | 方向が決まった後の調査・計画・実装・レビュー | 要求確定・仕様レビュー・見積り・提案書・Issue への引き渡し |
| 人間の相手 | 開発者 1 人 | 利用者・予算責任者・決裁者（レビュー会） |
| 仕様の単位 | 次の小さな仕様 1 つ（タスクファイル） | 版ごとの仕様全体（docs/v<n>/） |
| 仕様の寿命 | タスクファイルは短命。リリース後に削除 | 正本リポジトリに残り、リリースした版は凍結 |
| 未決定事項の扱い | clarify-task で対話して解消し、Analysis に判断を記録 | Q&A 表（CSV）に選択肢・推奨・理由付きで起票し、回答待ちで止まる |
| 人間の関門 | PLAN → EXECUTION、EXECUTION → DONE の承認 | 要求確定と予算のサインオフ（git タグ）、決裁者の承認 |
| 関門の判定 | 承認は人間。ルールは文章で書き、エージェントが従う | 照合・終了条件の一部を Python スクリプトが判定する（LLM に判断させない） |
| レビュー役 | 人間がタスクファイルと実装をレビュー | ファイルを直接書くツールを持たない判定役 3 体＋見積りの検証役を、別ティアのモデルで走らせる |
| 形式手法 | なし（PlantUML の図でレビューしやすくする） | 改修の性質に応じて、決定表・業務フロー・権限を形式化し、検査器で反例を探す |
| テストの扱い | Test specification に検証項目を書き、実装で満たす | 仕様にテストケースを書き、scaffold で Red テストを生成して渡す |
| 共有言語 | プロジェクト用語集（AsciiDoc）を重視 | 決定表と Q&A 表が中心 |
| 配布形態 | npx skills add。複数のエージェントに対応 | Claude Code プラグイン（マーケットプレイス経由） |
太字の観点を、以下の「違い 1〜4」で詳しく見ていきます。
違い 1: 誰と回すループか
dpolivaev 版のループは、開発者とエージェントの 2 者で閉じています。ドキュメント「Governance, Review, and Traceability」には「人間の開発者が理解と意図の主たる源泉であり続ける」とあり、承認するのも、レビューするのも、done にするのも開発者です。
hdknr 版は、開発者の外にいる人を相手にします。
- 利用者: 要求確定のループ（
req-loop）。Q&A 表の質問にレビュー会で答えてもらう - 予算責任者: 実現性・コストのループ（
feasibility）。費用が変わる選択肢に答えてもらい、合意を得る - 決裁者: 提案書のループ（
proposal）。2 つのサインオフがそろった後に、提案書で承認を得る
このため hdknr 版は、1 回の実行が「次の人間の判断」で止まるように作っています。req-loop は利用者の回答待ち、feasibility は予算責任者の合意待ち、proposal は決裁者の承認待ちで止まります。回答をスキルが推測で埋めることはありません。再開点は会話ではなく Q&A 表の状態から読むので、日をまたいで別のセッションで呼び直しても続きから始まります。
dpolivaev 版も、承認が要る場面で止まる点は同じです。ただ、承認するのは目の前の開発者なので、会話の中で次の承認がすぐ返ってくることを前提にできます。
違い 2: 仕様をどの単位で、どのくらい残すか
dpolivaev 版は、ウォーターフォールの失敗を避けようとしています。完全な仕様は事前に書けず、書いても膨らむか無視される、という失敗です。そのため、仕様を「次の一歩」に必要な範囲だけに絞ります。タスクファイルは短命な作業成果物で、リリースタグを作ったら作業ツリーから消します。長く残すのは「生きたドキュメント」（仕様・ADR・用語集など）だけで、その範囲も狭く保ちます。
hdknr 版は逆に、版ごとに仕様全体を正本リポジトリに残します。docs/v<n>/ に版ごとの差分を置き、スクリプトで差分を重ね合わせて、ある版の時点での仕様全体を組み立てます。リリースした版は凍結し、直されていないかをスクリプトで確かめます。
この違いは、相手の違いから来ています。利用者や決裁者に見せて「この版で何を作るか」を合意するには、版の全体が要ります。v2 以降の提案書には前の版との比較（追加・変更・削除）を載せるので、前の版も残しておく必要があります。
ただし、全体の仕様を持つ hdknr 版では、dpolivaev 版が警告する「仕様が膨らむ」問題が実際に起きています。ある実案件では、要求 190 行・決定表 15 行に対して、メインの仕様ファイルが 768 行、テストケースが 300 件になりました。そこで、テストケースの増え方が要求と決定表の増え方より速ければ「減らす見直し」をする、という歯止めを入れています。
違い 3: 関門を誰が判定するか
dpolivaev 版の関門は、人間の承認です。ルールは丁寧に文章で書かれていて、たとえば「done への移動は常にユーザーだけが行う」「承認を求める前に、タスクが要件を満たすかをエージェントが自己チェックする」と決めています。ただし、そのルールに従うのはエージェント自身です。
hdknr 版は、機械で決められる関門をスクリプトに判定させます。
check-signoff.py: 要求確定と予算の 2 つのサインオフのタグが、同じ共有の範囲を指しているかを照合する。一致しなければ提案書を作らないcheck-spec-exit.py: 仕様レビューを抜ける条件のうち、Q&A 表に未反映の行がないこと、仕様にTBD・未定などの印が残っていないことを判定するscaffold.py: Issue や Red テストを作る前に、自分で同じ関門を通す。暫定の回答が残っていれば何も作らない
機械で決められない条件（仕様チェックリストの欠け、テストケースの欠け、形式検査の反例）は、ファイルを直接書くツールを持たない判定役に、仕様を書いたモデルとは別のティア（Opus と Sonnet のような、性能帯の違うモデル）で判定させます。同じモデルは同じ思い込みを共有するので、書き手と判定役のモデルを分けて盲点をずらすためです。
dpolivaev 版がこうした仕組みを持たないのは、欠点というより設計の選択でしょう。開発者 1 人が毎回承認する前提なら、人間の目が最後の関門になります。hdknr 版は、承認する人が仕様の細部を読まない（利用者や決裁者は Q&A 表と提案書を見る）ので、細部の検査を機械と別のモデルに任せる必要がありました。
違い 4: 実装への渡し方
dpolivaev 版では、計画と実装が同じループの中にあります。タスクファイルの Design が実装の契約になり、Test specification に書いた検証を実装の中で満たします。
hdknr 版では、spec-loop と dev-loop の間にはっきりした受け渡しの契約があります。scaffold が確定した仕様を中間表現（spec_ir.json）に書き起こし、OpenAPI・型・Red テスト・Issue の本文を生成して、1 機能 = Issue 1 件で登録します。dev-loop は Issue 本文の印で spec-loop から来たことを知り、開発中に仕様の穴を見つけたら、Q&A 表に起票元「開発」で差し戻します。
2 つの spec-loop の共通点
工程も相手も違いますが、根っこの考え方には共通点が多くあります。
- 推測で埋めない: dpolivaev 版は、未解決の重要な分岐に当たったら推測せずに
clarify-taskに戻る。hdknr 版は、未決定事項を Q&A 表に起票するかTBDなどの印を残し、黙って決めない - 人間の判断を飛ばさない: どちらも、承認が要るところでエージェントが止まる。「惰性で進めない」という狙いも同じ
- 小さく回す: dpolivaev 版は「次の小さな仕様」、hdknr 版は「1 回の実行はレビュー会 1 回分」「1 機能 = Issue 1 件」
- テストを仕様の一部にする: dpolivaev 版は Test specification がないと承認に進めない。hdknr 版は「テストケースを書き起こせない仕様は、まだ確定していない」とする
- 決まりの住所を 1 つにする: dpolivaev 版は生きたドキュメントの一覧を 1 か所に置く。hdknr 版はデータの決まりを
references/にだけ書き、他はそこを指す
互いに取り入れられそうな点
hdknr 版が dpolivaev 版から学べること
- Research を書き残してから設計する: 今のタスクに必要な範囲に絞った調査結果を残し、コードを書く前に「正しい箇所を調べたか」を人間が確かめられるようにする。dev-loop の文脈収集の成果物の形として参考になる
- + / = / ± の変更記号: 設計のクラス図やテスト項目に「追加・再利用・変更」を付ける。dev-loop の計画のレビューで、差分の意図を読み取りやすくなる
- 生きたドキュメントを同じ増分で更新する: 仕様・ADR・用語集の更新をタスクの Design に列挙し、コードと一緒にレビューする。dev-loop の「経験の還元」と組み合わせられる
- 用語は綴りではなく意味で比べる: 新しい用語を足す前に、既存の抽象と同じ意味かを確かめる。hdknr 版の仕様が膨らむ一因である重複を減らせる
dpolivaev 版の使い手が hdknr 版から試せること
- 関門をスクリプトに判定させる: たとえば「Design と Test specification がそろっていなければ承認を求めない」のような、機械で確かめられるルールを検査に置き換える
- 別ティアの判定役: タスクファイルの承認前の自己チェックを、ファイルを書けない別のモデルに任せる
- 未決定事項を表に残す: 会話の中で解消した論点を、セッションをまたいでも追える形で残す
2 つの spec-loop を組み合わせるなら
2 つは工程が重ならないので、組み合わせることもできます。hdknr 版の spec-loop で要求と仕様を確定させ、scaffold が作った Issue 1 件を、dpolivaev 版のタスクファイル 1 つ（または、サブタスクを持つタスク 1 つ）の入力にする形です。dpolivaev 版の Research には Issue と Red テストを、Design には確定した仕様の該当部分を入れることになります。
ただし、この場合は dev-loop と dpolivaev 版の役割が重なります。どちらも「Issue（タスク）1 件を、検証が通るまで 1 周」させるものです。関門の置き方も違い、dev-loop は verify と別モデルの検証、dpolivaev 版は人間の承認です。両方を同時に使うより、計画の書き方は dpolivaev 版から借り、停止条件は dev-loop のまま、という取り入れ方のほうが現実的だと考えています。
まとめ
- 同じ「spec-loop」でも、dpolivaev 版は実装の一歩一歩を、hdknr 版は開発の手前の合意を扱う。hdknr 版で dpolivaev 版と重なるのは dev-loop のほう
- 違いの多くは相手の違いから来ている。開発者 1 人と回すなら人間の承認が最後の関門になり、利用者・予算責任者・決裁者と回すなら、細部の検査を機械と別のモデルに任せる必要がある
- 仕様の残し方も相手で決まる。dpolivaev 版は次の一歩だけを短命なタスクファイルに書き、hdknr 版は合意のために版ごとの全体を残す。全体を残す側では、仕様の膨張への歯止めが要る
- 実装への渡し方は、dpolivaev 版が同じループの中、hdknr 版が Issue と Red テストという明示的な契約
- 「推測で埋めない」「人間の判断を飛ばさない」「小さく回す」「テストを仕様の一部にする」という根っこは共通している
- 取り入れるなら、計画の書き方（Research・変更記号・生きたドキュメント・用語の扱い）は dpolivaev 版から借り、停止条件は dev-loop のままにする