Issue から PR まで自走する GAN ループ型パイプライン spec-orchestrate を公開

ZenChAIne·2026年7月6日

Agent SkillsSpec-Driven DevelopmentClaude Code

はじめに

agent-skills（ZenChAIne がオープンソース公開している仕様駆動開発スキル集）に、新しいスキル spec-orchestrate が加わりました。連載「実践！仕様書駆動開発」の第2回（仕様作成編）と第3回（実装編）で紹介した spec 系スキル群を部品として束ね、GitHub Issue 1本を入力に、仕様生成から敵対的レビュー、実装、受け入れ試験、PR 作成、振り返りまでを一気通貫で走らせる指揮者です。

この記事では、spec-orchestrate の設計を「生成側と批評側を敵対させるループ」という最近のトレンド概念と接続して紹介し、実案件での初回実走データと具体的な使い方まで解説します。

この記事のポイント

spec-orchestrate は、連載②③で紹介した spec 系スキル群を状態機械（ステートマシン。状態と遷移条件をあらかじめ表として固定した制御方式）で束ねるオーケストレーター。自分ではコードも仕様も書かない
Claude が仕様や実装を生成し、Codex が敵対的にレビューするクロスモデルの往復ループ（GAN ライト構成）が中核
レビューループに回数上限は置かず、findings 指紋という同一性キーで「前進しないループ」だけを機械検知して裁定に回す
「テストしました、通りました」という自己申告を信用せず、スクリーンショットやログの実在と sha256 を機械検証する証跡主義
初回実走では、GitHub Issue 1本から人間の入力ゼロで ready PR まで完走。仕様レビューで Codex が CSRF の Critical を検出し、受け入れ試験は13ケース全 PASS
実行後の retrospective が改善候補を抽出し、影響の小さい変更（Tier 1）だけ自動適用する権限階層を持つ

これまでの spec 系スキルに何が足りなかったのか？

足りなかったのは、スキル間の接続を運転し続ける指揮者と、完成物を疑ってかかる検証者です。連載②の3スキル（spec-generator / spec-inspect / spec-to-issue）と連載③の4スキル（spec-implement / spec-code / spec-review / spec-test）で、「ECサイトの仕様を全部作って」から PR までの部品は揃っていました。ただし部品の接続には、次の3つの手動ポイントが残っていました。

1. 各ステップの接続は提案止まりだった

連載②で書いたとおり、spec-generator の完了後に spec-inspect の実行を「提案」し、人間が選択すれば次へ進む設計でした。仕様の生成、検査、Issue 化、実装開始のたびに人間の確認が挟まります。

2. 仕様そのものへの敵対的レビューがなかった

spec-inspect は要件 ID の整合や矛盾を検出する機械検査で、spec-review は実装コードのレビューです。「この設計はセキュリティ的に穴がないか」を仕様段階で、しかも生成した本人とは別のモデルが批判的に読む工程はありませんでした。

3. 受け入れ試験がなかった

spec-test は完了条件からユニットテストを生成しますが、実装者側の視点で書かれるテストです。完成したアプリを実際に起動し、ブラウザを操作して外側から検証するブラックボックス試験（内部実装を知らない立場で入出力だけを検証する試験）は工程に存在しませんでした。

今回のアップデートは、この3つを埋める新要素の追加です。

新要素	役割
`spec-orchestrate`	全工程を状態機械で運転する指揮者。人間の確認ポイントを設計上の1箇所（または0箇所）に圧縮
`spec-evaluate`	test.md に基づく受け入れ試験ランナー。実ブラウザ操作と証跡保存を担当
`agent-delegate`	Claude Code から Codex CLI（またはその逆）へタスクやレビューを委譲する橋渡し。引数と結果ファイルの公開契約だけで結合

ハーネスエンジニアリング入門で紹介した Anthropic の三体構成（Planner / Generator / Evaluator を分離し、外部のオーケストレーターがループを回す設計）を、Claude Agent SDK ではなくスキル機構の上で実装した形、と捉えることもできます。

GAN ループとは何か？

GAN ループとは、成果物を「生成する側」と「粗を探す側」を別のエージェントに分け、批評が通るまで往復させる開発ループの構図です。名前の由来は機械学習の GAN（Generative Adversarial Network、敵対的生成ネットワーク）にあります。2014年に Ian Goodfellow らが提案した枠組みで、よく偽札職人と鑑定士の腕比べに喩えられます。偽札職人（生成器）は鑑定士を騙せる精巧な札を作ろうとし、鑑定士（識別器）は見破る目を鍛える。両者を競わせることで、単独で作るより本物らしい生成物に到達します。

2025年後半からのエージェント開発では、この構図を「モデルの学習」ではなく「開発ループの設計」に借用する流れが広がっています。前述の Anthropic の三体構成はその代表例で、作った本人に評価させると自分の成果物に甘くなる問題を、評価者を独立させることで回避しました。ハーネスエンジニアリングの文脈ではループエンジニアリング（生成と検証の往復をどう設計するかという議論）とも呼ばれます。

spec-orchestrate はこの構図の軽量版です。勾配降下法で両者を学習させる本来の GAN とは違い、借りているのは「生成側と批評側の敵対的往復」という構図だけなので、本記事では GAN ライト構成と呼びます。往復は2つのループで回ります。

仕様ループ: spec-generator（既定は Claude）が仕様4点セット（要件、設計、タスク、受け入れ試験計画）を書き、敵対的レビュアー（既定は Codex）が批判的に読んで findings（指摘事項）を返す。Critical か Improvement が残る限り差し戻す
実装ループ: 実装したタスクを、実装担当の反対側のモデルがレビューする。Codex が書いたコードは Claude が、Claude が書いたコードは Codex がレビューする「レビュアー反転」の規則で、自作自演を構造的に排除する

批評側に別ベンダーのモデルを置くのは、同じモデルは同じ盲点を共有しやすいからです。生成した Claude 自身に「この仕様に穴はないか」と聞いても、生成時に見えなかった穴はレビュー時にも見えにくい。訓練データも推論の癖も異なるモデルを対向させることで、盲点の重なりを減らします。後述する初回実走で、Codex が仕様段階の CSRF 対策漏れを検出できたのは、この構成の狙いどおりの結果でした。

このクロスモデルの往復は、モデルベンダー純正のツールが提供しにくい構成でもあります。Anthropic の三体構成は Claude 系エージェントの枠内で、OpenAI のハーネス事例は Codex の枠内で設計されており、ライバル社のモデルを正式な批評役として自社ツールに組み込む方向には進みにくい。ベンダーに中立なオープンソースのスキル集だからこそ、pipeline.yml の roles と agent-delegate の公開契約という薄い結合を挟むだけで、Claude と Codex を同じパイプラインの対等な担当者として会話させられます。単独モデル構成でも動きますが、この「ベンダーをまたいで競わせられる」自由度そのものが spec-orchestrate の設計上の強みです。

spec-orchestrate の設計

spec-orchestrate の本体は、意外なほど薄い状態機械です。設計の中身は「遷移表」「停滞検知」「証跡主義」の3点に集約されます。

薄い状態機械と役割分担

パイプラインは次の9フェーズを遷移表に従って進みます。

text

intake（受付）
  → spec_generate（仕様4点セット生成）
  → inspect（機械検査）
  → spec_review（敵対的仕様レビュー）⇄ 差し戻し
  → approval（人間の仕様承認。auto モードでは素通り）
  → implement（実装。連載③の spec-implement に委譲）
  → evaluate（受け入れ試験）⇄ 差し戻し
  → pr（証跡付き PR 作成）
  → retrospective（振り返りと自己改善）

spec-orchestrate 自身は仕様もコードもテストもレビューも書きません。SKILL.md には連載③の spec-implement と同じ「orchestrator only」の遮断規則が明記されており、やることは状態ファイルの読み書き、ワーカーの起動、結果の機械検証、次フェーズの選択だけです。安価な機械検査（inspect）を高価な意味論レビュー（spec_review）より先に置くのも設計上の規則で、書式の不備ごときに相手モデルのトークンを使わせません。

各フェーズを Claude と Codex のどちらが担当するかは、.specs/pipeline.yml の roles 設定で解決されます。既定は仕様生成と UI 実装と受け入れ試験が Claude、仕様レビューとバックエンド実装とテスト実装が Codex というクロスモデル構成です。進行状態は pipeline-state.json に書かれ、書き込むのはオーケストレーターだけ。数時間の実行が途中でクラッシュしても、状態ファイルから同じフェーズに復帰します（再開が異常系ではなく通常経路として設計されています）。

findings 指紋による停滞検知と裁定

仕様レビューと受け入れ試験のループには、「最大3回」のような回数上限を置きません（implement フェーズ内部のタスク単位の修正ループには、連載③で紹介したとおり3回上限が残ります）。難しいレビューで10往復するのは正常であり、避けたいのは回数ではなく「前進しないループ」だからです。前進しているかどうかは、findings 指紋という同一性キーで機械的に判定します。

指紋は、指摘が挙げる要件 ID、重大度、対象ファイル、セクション見出し、要旨の先頭80字（空白圧縮と小文字化で正規化）を連結したハッシュ値です。レビュアーがラウンドごとに文言を言い換えても、同じ問題を指していれば同じ指紋になります。各ラウンドの指紋集合を比較して、次の3シグナルを検出します。

S1（再発）: 同じ指紋が3ラウンド連続で残っている。修正が効いていない
S2（非減少）: Critical と Improvement の合計件数が3ラウンド減っていない。修正が作業量を減らせていない
S3（振動）: 指紋集合が2つの状態を交互に往復している。修正が別の問題を生んでいる

シグナルが成立したときだけ、裁定フェーズに入ります。manual モードなら人間に「続行か、方針変更か、引き取るか」を尋ね、auto モードなら担当モデルを反対側に入れ替えて続行します（入れ替えは既定で1回まで）。入れ替えても停滞するなら、未解決の指摘を明記した draft PR（マージ不可の下書き状態の PR）で着地します。無人パイプラインが未検証の作業を「マージ可能」に見せない、という原則です。裁定はすべて状態ファイルに記録されたうえで、Issue 起点の実行なら Issue コメントに、それ以外は PR 本文に転記されます。黙って解決された停滞はバグとして扱われます。

証跡主義による機械検証

受け入れ試験を担う spec-evaluate の中核原則は「自己申告を信用しない」です。評価エージェントが「テストして、通りました」と報告しても、それだけでは PASS になりません。

試験計画（test.md）の各ケースは、検証方法（playwright によるブラウザ操作 / コマンド実行 / ファイル確認）ごとに実行され、スクリーンショットやログを証跡ディレクトリに保存する
結果ファイルの PASS には証跡ファイルへのポインタが必須。ポインタ先が存在しない、または空の PASS は、機械検証が問答無用で FAIL に書き換える
証跡マニフェストの sha256 とファイルサイズを再計算して照合し、不一致も FAIL に落とす

PR 本文も、オーケストレーターの記憶ではなく状態ファイルと結果ファイルから機械生成されます。敵対的レビューの履歴（ラウンド数と最終ゲート）、要件 ID 別の合否表、証跡マニフェスト（ファイル名、サイズ、sha256）が載るため、レビュアーはスクリーンショットの現物を git 履歴に入れなくても「実行後に証跡が差し替えられていない」ことを確認できます。なお、この sha256 マニフェスト方式は最初からあった仕様ではなく、次に述べる初回実走の運用課題から生まれた改良です。

初回実走で何が起きたか

社内の財務系プロジェクトで、GitHub Issue 1本を入力に auto モードの初回実走を行いました。結果は、人間の入力ゼロで ready PR（draft ではない、マージ可能状態の PR）まで完走です。内訳を工程順に示します。

仕様ループは3ラウンドで収束しました。 ラウンド1で Codex レビュアーが、フォーム送信まわりの CSRF 対策（サイトをまたいで偽のリクエストを送り込む攻撃への防御）が仕様に欠けていることを Critical として検出し、spec_generate に差し戻されました。仕様を書いた Claude 側が見落とし、批評側の Codex が拾った実例で、書式チェックでは決して見つからない種類の欠陥です。反映後の再レビューを経て、3ラウンド目でゲート通過となりました。

実装は5フェーズを Claude と Codex の分業で進めました。 roles の既定どおり UI 系タスクを Claude が、バックエンドとテスト系タスクを Codex が実装し、各タスクは実装担当の反対側がレビューしています。

受け入れ試験は13ケース全 PASS でした。 実ブラウザを操作した画面ごとのスクリーンショットが証跡として保存され、PASS の証跡ポインタが実在するかの機械チェック（欠落していれば FAIL に倒す検証）を通過しています。一方でこの実走では、証跡スクリーンショットがそのまま git 履歴にコミットされてしまう課題も見つかりました。稼働システムの画面には個人情報が写り込みうるうえ、バイナリは diff でレビューできません。この反省から、「証跡はローカルに置き、PR には sha256 マニフェストだけを載せる」という前節の現行方式への改良が生まれています。

retrospective は改善候補を「観察」として記録するに留めました。 気づきはあったものの、頻度の裏づけがまだ1実行分しかないため、修正提案には昇格させないという設計どおりの抑制です。

完走という結果そのものより、私たちが収穫だと考えているのは「止まるべき所で止まり、疑うべき所で疑う」挙動が実案件で確認できたことです。CSRF の検出は敵対的レビューが飾りでないことを、全 PASS の裏で働いた証跡の実在チェックは自己申告を信用しない検証が機能していることを、観察止まりの retrospective は自己改善が暴走しないことを、それぞれ示しています。そして、実走で見つかった証跡管理の課題が sha256 マニフェスト方式という改良に還流したこと自体が、走らせるたびにパイプラインが良くなっていく構造（この記事の主題である自己改善）の実例になりました。無人で走らせる自動化の信頼は、成功例の数ではなく、失敗を検出する仕組みが実際に発火した実績から積み上がると考えています。

使い方

インストール

agent-skills を一括インストールすると、spec-orchestrate と依存ワーカーがまとめて入ります。

bash

npx skills add anyoneanderson/agent-skills -g -y

pipeline.yml で担当を決める

フェーズごとの担当は .specs/pipeline.yml の roles で設定します。雛形は連載①で紹介した spec-workflow-init が生成でき、ファイルがなくても既定値で動きます。roles はフェーズ単位、実装はさらにタスク種別（UI、バックエンド、テスト）単位で割り当てられるため、「画面まわりは Claude、レビューとテストは Codex」のように、モデルの得意分野に合わせた適材適所の布陣を組めます。既定のクロスモデル構成も、この考え方で組んだものです。

yaml

roles:
  spec_author: claude      # 仕様を書く
  spec_reviewer: codex     # 仕様を敵対的にレビューする
  impl_ui: claude          # UI 系タスクの実装
  impl_backend: codex      # バックエンド系タスクの実装
  impl_test: codex         # テスト系タスクの実装
  e2e_runner: claude       # 受け入れ試験の実行
app:                       # 受け入れ試験でアプリを起動するレシピ
  start: "npm run dev"
  url: "http://localhost:3000"
  ready_pattern: "ready in"

Codex CLI を導入していない環境や、軽い機能で往復コストを抑えたい場合は、roles をすべて claude にした軽量構成も選べます。

yaml

roles:
  spec_author: claude
  spec_reviewer: claude    # 同一モデル内でも生成と批評のセッションは分離される
  impl_ui: claude
  impl_backend: claude
  impl_test: claude
  e2e_runner: claude

この場合も生成側と批評側は別セッションとして走るため、レビューの独立性はある程度保たれます。ただし同じモデルは同じ盲点を共有しやすいため、クロスモデル構成より欠陥検出の網は粗くなります。なお codex 担当を設定していて Codex CLI が見つからない場合は、manual モードでは確認のうえ、auto モードでは自動で claude に振り替えられ、振り替えの事実が状態ファイルと PR 本文に記録されます。

manual と auto の2モード

text

# manual: 対話で仕様を固め、承認したらあとは任せる
/spec-orchestrate --mode manual
 
# auto: Issue 番号を渡して PR を待つ（--issue の指定で auto になる）
/spec-orchestrate --issue 42
 
# 中断した実行を状態ファイルから再開
/spec-orchestrate --resume

manual モードの人間ゲートは仕様承認の1箇所だけです。対話で要件を固め、敵対的レビューを通過した仕様に人間が承認を出したら、実装から PR までは自走します。auto モードは人間ゲートなしで、Issue が入力、PR が出力です。停滞すれば draft PR で着地するため、ready で出てきた PR は「受け入れ試験を通過した」という主張を伴います。

retrospective は何を自動で直すのか？

パイプラインの最終フェーズ retrospective は、実行記録を集計して自分自身（スキルの指示書）の改善まで行います。ただし何でも自動で書き換えるわけではなく、変更対象によって権限を分ける階層設計です。

改善提案は、ラウンド数や失敗カテゴリ別件数といった機械集計に裏づけられたものだけが作られます（件数の裏づけがない気づきは観察として記録するだけで、対処しません）。提案の適用可否は対象ファイルの Tier で決まります。

対象	Tier	扱い
各スキルの参照指示書（references 配下）	1	改善ブランチから PR を作り自動マージ
SKILL.md 本体、他スキルが依存する公開契約、実行スクリプト、コーディングルール	2	PR を作るが人間レビュー待ちで残す

Tier 1 でも直接 push はせず、ブランチと PR を経由するため、改悪は revert 1回で戻せます。さらに、パスの正規化（../ やシンボリックリンクを使って Tier 2 ファイルを Tier 1 に見せかける細工の拒否）と行数バジェット（LLM の自己改善は指示の追記に偏るため、削除を伴わない純増で300行を超える編集は拒否）というガードレールが適用前に働きます。

多くの自動化は、作った時点が品質の頂点で、あとは現場とのずれが広がっていきます。spec-orchestrate は逆向きです。実行のたびに記録が機械集計され、頻度の裏づけを得た改善だけがスキル自身に還流します。初回実走の証跡管理の改良のように、失敗の学びが次の実行の仕様になる。単発のエージェント実行との一番の違いは、この「走らせるほど良くなる」構造だと考えています。

この権限階層は、AI に与えるコミット権限の設計問題の縮図だと私たちは捉えています。エージェント自身の挙動を決める指示書は AI が実績データに基づいて直してよい。しかし他のスキルとの契約や、実行系そのものに触れる変更は人間が握る。自己改善を「許すか、許さないか」の二択ではなく、変更の影響範囲で権限を刻む設計は、スキルに限らず AI エージェント運用全般に応用できるはずです。

よくある質問

Q. spec-implement と spec-orchestrate はどう違いますか？

A. spec-implement は Issue を入力に実装から PR までを指揮する、実装区間のオーケストレーターです（連載③参照）。spec-orchestrate はその前後、つまり仕様生成、敵対的仕様レビュー、人間承認、受け入れ試験、振り返りまでを含む全区間の指揮者で、implement フェーズでは spec-implement をワーカーとして呼びます。

Q. Codex CLI がなくても使えますか？

A. 使えます。roles をすべて claude にするか、codex 担当のまま実行すれば不在検知時に claude へ振り替えられます（auto モードは自動振り替え、manual モードは確認あり）。ただし異種モデルを対向させることによる盲点低減の効果は薄まります。

Q. レビューループが無限に回りませんか？

A. 仕様レビューと受け入れ試験のループには回数上限がありませんが、無限には回りません。findings 指紋が「同じ指摘の再発」「件数の非減少」「2状態の振動」を検知した時点で裁定に入り、担当交代（1回まで）か draft PR 着地で必ず終端します。なお implement フェーズ内部のタスク単位の修正ループには、従来どおり最大3回の上限があります。

Q. Anthropic や OpenAI の純正機能でも同じことはできませんか？

A. 単一モデル内の分業（サブエージェントや純正ハーネス）は各社のツールでもできます。しかし、ライバル社のモデルを対等な批評役として組み込む構成は、ベンダー純正のツールでは提供されにくいものです。spec-orchestrate はどのベンダーにも属さないオープンソースとして、Claude と Codex を同じパイプラインで対向させ、実行記録から自分自身を改善するところまでを1つのループにしています。「レビューは Codex、UI は Claude」のように得意分野で担当を割り振る自由度も、特定ベンダーの枠内では得にくい点です。

Q. auto モードが作った ready PR はそのままマージしてよいですか？

A. ready PR は受け入れ試験の全 PASS と証跡マニフェストを伴うため、検証済みであることは機械的に裏づけられています。それでも、マージの最終判断は人間のコードレビューを前提にする運用を推奨します。パイプラインが圧縮するのは検証の手間であって、マージ責任ではありません。

まとめ

連載3部作で紹介した9つの部品は、spec-orchestrate、spec-evaluate、agent-delegate の追加によって、人間が接続を確認しながら進む「提案の連鎖」から、証跡付きで自走する一気通貫パイプラインになりました。中核にあるのは、Claude が生成し Codex が批評する GAN ライトの往復ループ、前進しないループだけを検知する findings 指紋、自己申告を信用しない証跡主義、そして影響範囲で権限を刻む自己改善です。このうちクロスモデルの敵対往復、得意分野に合わせた担当割り、そして自己改善のループは、単一ベンダーの純正ツールでは組みにくい、中立なオープンソースならではの強みだと考えています。

初回実走が示したのは「AI が完走できる」ことだけではなく、「疑う仕組みが実案件で発火する」ことでした。仕様段階の CSRF 検出も、sha256 で裏づけられた13ケースの PASS も、観察止まりの retrospective も、その実例です。ZenChAIne では agent-skills を実案件に適用しながら運用データを蓄積しています。フィードバックや Pull Request も歓迎です。

リポジトリ: github.com/anyoneanderson/agent-skills

実践！仕様書駆動開発 ②仕様作成編spec-generator / spec-inspect / spec-to-issue で要件、設計、タスクの3点セットを生成し GitHub Issue 化するフローを解説します。zench-aine.io

実践！仕様書駆動開発 ③実装編spec-implement の指揮で spec-code / spec-review / spec-test が分業し、Issue から PR まで自走する仕組みを解説します。zench-aine.io

ハーネスエンジニアリング入門AI エージェントの品質を環境設計で高めるハーネスエンジニアリングの概念と、Anthropic の三体構成（GAN 型）を解説します。zench-aine.io

参考ソース

🇺🇸 Read in English