🪄

ハーネスエンジニアリングの先へ — VSDD × CoDDで「実装品質」と「変更時の整合性」を両立させてみた

2026/04/02に公開

 はじめに以前、私はAI支援開発の品質問題を解決するVSDDという手法をプラグイン化したvsdd-claude-codeを作りました。
https://zenn.dev/sc30gsw/articles/1373752d9713b3
VSDDとは、Verified Spec-Driven Development（検証済み仕様駆動開発） のことで、SDD（仕様駆動開発）・TDD（テスト駆動開発）・VDD（検証駆動開発）という3つの手法を1つのワークフローに統合するハーネスエンジニアリングの1つです。
一方、ハーネスエンジニアリングとは、AIエージェントの行動をHook・Skill・ルールなどの仕組みで構造的に制御し、信頼性の高い開発を実現するアプローチです。

馬具（ハーネス）で馬の力をコントロールするように、強力だが制御しにくいAIの出力を「正しい方向へ導く」ためのエンジニアリングです。
昨今プロンプト→コンテキスト→ハーネスと重要視される点が変わってきてますが、この背景にあるのが、近年深刻化している AIスロップ（AI slop） の問題です。

 AIスロップという問題AIスロップ（AI slop）とは、AIが生成するコードが「実際に動くが品質が低い」、あるいは「動くように見えるが隠れた欠陥を抱えている」状態を指します。

これが、不要な設計、浅いロジック、意味のないテストが積み重なり、長期的にプロジェクトを蝕んでいきます。
VSDDは、このAIスロップを敵対的レビューと仕様ファーストの強制で排除するために生まれた、ハーネスエンジニアリングの実践の一つでした。


カテゴリ
例


構造的スロップ
使われない抽象化、不要なインターフェース設計、過剰なレイヤー分離

ロジックスロップ
ハッピーパスのみ対応、バリデーションが浅い、エラーが silent failure になる

テストスロップ
実装をそのままコピーしたミラーテスト、アサーションが弱い、過剰なモックで本物を検証していない


 VSDDの限界とCoDDとの出会いVSDDを実際に使って開発を始めたころ、ほぼ同じタイミングでこの記事が執筆されました。
https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence
この記事ではVSDDを含め、これまで未解決だった問題に対して、CoDD（Coherence-Driven Development、整合性駆動開発） というアプローチでの解決法が紹介されていました。
その課題というのが以下です。
要件が変わったとき、どの設計書・コード・テストが影響を受けるかを追跡できない。
VSDDでも「最初にどう作るか」の品質や開発途中・開発後の品質は担保できても、「途中で変わったときにどうするか」には対応できません。
そこで、私は、VSDDにCoDDのエッセンスを加えることができれば、現時点におけるハーネスエンジニアリングの完成形に近づくのではと考えました。
この記事では、VSDDにCoDDを統合し、 VCSDD（Verified Coherence Spec-Driven Development, 整合性保証型仕様駆動開発） としてプラグイン化し、実際にReact + TypeScriptで決算データ可視化アプリを開発してみたので、その仕組みの解説と所感をお伝えできればと思います。
!※ VCSDDは私の造語です。
https://github.com/sc30gsw/vcsdd-claude-code

 CoDDとはVSDDは前述した通り、仕様と敵対的レビューで「仕様・実装・テストの品質」を構造的に担保する仕組みです。
一方で、CoDD（Coherence-Driven Development） は、以下のように定義されています。
CoDD — Coherence-Driven Development（整合性駆動開発）。設計の整合性を保つことで開発を駆動する方法論。
つまり、設計書・コード・テスト間の依存関係を記録し、要件変更時に影響を自動で追跡する仕組みです。
今回はCoDDのライブラリ（codd-dev）をそのまま使うのではなく、そのコアコンセプトをVCSDDプラグイン内にネイティブ実装する形でCoDDのエッセンスを取り入れました。
具体的に、vcsdd-coherence.js がこのコアコンセプトを再現している部分となります。
CoDDの仕組みや詳細についてはおしおさんの以下の記事をご参照ください。
https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence

 VCSDDが解決する課題VSDDとCoDDをそれぞれ単独で使うだけでも、かなりの問題は解決できます。しかし、2つを組み合わせることで初めて両立できる課題があります。
それが 「実装品質」と「変更時の整合性」の両立 です。


課題
SDD
VSDD
CoDD
VCSDD


AIスロップの排除
❌
✅
❌
✅

敵対的AIレビュー（Adversary）
❌
✅
❌
✅

仕様・テスト・実装の品質保証
△（仕様のみ）
✅
❌
✅

形式検証（プロパティテスト・ファジング）
❌
✅
❌
✅

成果物の来歴トレース（なぜこのコードがあるか）
❌
✅
❌
✅

変更時の影響トレース（何が影響を受けるか）
❌
❌
✅
✅

依存グラフの自動構築
❌
❌
✅
✅

要件変更時の影響範囲の自動伝播
❌
❌
✅
✅

設計の整合性維持
❌
❌
✅
✅

変更によるテスト・仕様の陳腐化防止
❌
❌
✅
✅

このように、VSDDとCoDDは、互いに補完し合う関係といえます。
つまり、2つを両立させることは両者のジンテーゼとなり、それぞれの弱点を補うことができると私は考えています。
それでは、VCSDDとは何なのか解説していきたいと思います。

 VCSDD（整合性保証型仕様駆動開発）とはVSDDは「実装品質」を担保し、CoDDは「変更時の整合性」を担保します。
この2つを融合したのが VCSDD（Verified Coherence Spec-Driven Development） です。
構成としてはVSDDを基盤として、CoDDのコアコンセプトである整合性追跡の仕組みを各フェーズに組み込んだものとなっています。
つまり、設計思想としてはコードの正しさを担保しながら、整合性も同時に維持するというものになっています。

 VCSDDの基盤：VSDDVSDDを既に知っている方は復習として、初めての方は入口として、全体像だけ簡単に解説します。
詳細は以下の記事をご参照ください。
https://zenn.dev/sc30gsw/articles/1373752d9713b3
まず、VSDDの構成要素は以下の3つになります。
6つのフェーズ
4つの役割
Adversary（敵対的レビュー）
それぞれ概要レベルで解説していきます。

 6フェーズパイプラインVSDDは以下の6つのフェーズで構成されます。

VCSDDではここにCoDDの整合性チェックが組み込まれます。


フェーズ
内容
CoDD連動


Phase 1: 仕様結晶化
EARS形式で振る舞いを仕様化し、検証アーキテクチャを定義する

coherence: frontmatter記述 → CEGにノード・エッジ登録

Phase 2a: テスト生成（Red）
失敗するテストを生成する

CEG構造検証がゲート — 整合性違反・循環依存があればブロック

Phase 2b/2c: 実装・リファクタ
テストをGreenにし、コードを整える
—

Phase 3: 敵対的レビュー
別AIがPASS/FAILを判定する
CEGの状態もレビュー対象に含まれる

Phase 4: フィードバック統合
FAILの指摘を適切なフェーズに自動で差し戻す
仕様変更 → 影響する下流ノードを自動特定

Phase 5: 形式的硬化
プロパティテスト・ファジング等で形式的に検証する
—

Phase 6: 収束判定
仕様・テスト・実装・証明の4つが揃って初めて完了
CEGの整合性も収束条件に含まれる

ポイントは直線ではなくループという点です。
Phase 3でFAILが出ると差し戻し先のフェーズから修正・実装・レビューのサイクルを繰り返し、AdversaryがPASSを出して初めて次へ進めます。

 4つの役割VSDDには4つの役割があり、それぞれ明確に責務が分かれています。


役割
担当
責務


Architect
人間
戦略的ビジョン、仕様承認

Builder
LLM（Sonnet）
仕様執筆、テスト生成、実装

Adversary
LLM（Opus、毎回新規コンテキスト）
超批判的レビュー、ゼロトレランス

Verifier
LLM（Sonnet）
形式検証の調整


 Adversary（敵対的レビュー）VSDDの核心はAdversaryです。Adversaryは毎回フレッシュコンテキスト（会話履歴ゼロの状態） で起動し、ディスク上の成果物だけを読んで判定します。
なぜこれが重要かというと、LLMは長い会話の中で「なぜその実装になったか」という経緯を知ってしまうと、意図せず正当化する方向に引っ張られるからです。
これをVSDDではエントロピー抵抗の欠如と呼んでいます。会話が長くなるほどAIは同調バイアスが強くなり、本来見つけるべき欠陥を見逃しやすくなります。
フレッシュコンテキストのAdversaryは経緯を一切知らないため、成果物そのものだけを純粋に評価できます。
この同調バイアスをコンテキスト分離によって構造的に排除する仕掛けこそが、VSDDの品質ゲートを機能させている核心です。
つまり、簡単に言ってしまえば、Adversaryはお世辞を言わないということです。
「全体的に良いと思います」という評価はせず、必ず具体的な証拠を示した上でPASS/FAILを判定 します。
ここまでが、VSDDの基本となります。

ここからは、VCSDDにおけるCoDDの解説をしていけたらと思います。

 VCSDDにおけるCoherence Engineの動作VCSDDがVSDDと決定的に異なる点は、Coherence Engine（CEG）がフェーズゲートに組み込まれていることです。

 CEG（Conditioned Evidence Graph）とはCEGは仕様書・実装モジュール間の依存関係を有向グラフとして管理するものです。
!有向グラフとは以下のように、頂点（ノード）同士を結ぶ辺（エッジ）に「向き（矢印）」がついているグラフのことをいいます
ここでは、矢印の向きは「依存の方向」を表します。これにより、data-schema が変更されたとき、下流の ComparisonChart と SectorFilter が影響を受けることを自動的に追跡できます。
CEGの主な構成要素は以下の通りです。

ノード: 仕様書・設計書・実装モジュールなど

エッジ: 依存・派生関係（信頼度スコア付き）

信頼度バンド: Green（90%以上） / Amber（50%以上） / Gray（50%未満）

保存先: .vcsdd/features/<name>/coherence.json
CEGを有効化するには、仕様書のMarkdownファイル先頭のメタデータ（frontmatter）に coherence: ブロックを追記するだけです。これだけでCEGが自動構築されます。
---
id: spec:behavioral-spec
coherence:
  depends_on:
    - design:data-schema
    - design:ui-components
---
逆に、このブロックを書かなければCEGは無効のままで、VSDD単体と同じ動作になります。

つまり、CoDD機能はオプトインということです。

 Phase 2a進入前の整合性チェックVCSDDの整合性強制の核心は、テスト生成（Phase 2a）に入る前のチェックポイントにあります。
テストを書き始める前に、CEGの構造検証が自動実行されます。問題があればテスト生成はブロックされ、整合性が修正されるまでフェーズが進みません。
CEGが検出するのは主に以下の2種類です。
循環依存 — ノード同士が互いに依存し合い、無限ループになっている状態
# NG: behavioral-spec と data-schema が互いに依存し合っている
behavioral-spec → data-schema → behavioral-spec → ...（終わらない）
存在しないノードへの依存 — frontmatterに依存先として書いたノードが、どこにも定義されていない状態
# NG: behavioral-spec が定義されていない auth-schema を依存先に指定している
behavioral-spec → auth-schema  ← どこにも定義されていない
このゲートがVSDD単体では存在しなかった仕組みです。整合性が壊れた状態でテストを書かせない、これがVCSDDの整合性維持の源泉です。

 仕様変更時の影響伝播Phase 4（フィードバック統合）またはPhase 1aへの差し戻し後に仕様が更新されると、Coherence Engineは変更されたノードから順に、依存している全ノードへ影響を自動で伝播します。
!この伝播はBFS（幅優先探索）というアルゴリズムで行われます。変更されたノードに直接依存するノードを先にすべて処理し、その次の階層、またその次・・・と順番に広がっていく探索方法です。これにより、影響範囲の取りこぼしなく検出できます。
design:data-schema が変更された場合:
  → spec:behavioral-spec（依存）
    → test:integration-tests（依存）
      → impl:ComparisonChart（依存）
        → impl:SectorFilter（依存）
  → design:ui-components（依存）
これにより「どの設計書・テスト・実装が影響を受けるか」が即座に特定でき、更新漏れを構造的に防ぎます。

 VSDD単体・CoDD単体との違い「2つのツールを別々に使えばよいのでは」という疑問には以下で答えられます。


比較項目
CoDD単体
VSDD単体
VCSDD（融合）


変更時の影響追跡
✅ 自動で特定
❌ 手動で確認
✅ 自動で特定

実装品質の保証
❌ 品質ゲートなし
✅ Adversaryが検証
✅ Adversaryが検証

整合性違反の強制ブロック
⚠️ 人間承認が必要（自動ブロックではない）
❌ そもそも整合性を追跡しない
✅ テスト生成前にブロック

変更後のテスト生成前チェック
❌
❌
✅ CEGが自動検証

仕様→テスト→実装の完全トレース
❌
✅ Chainlink Bead
✅ Chainlink Bead + CEG

単に「両方使う」だけでは、CoDDの整合性チェックはVSDDのフェーズゲートと無関係に動きます。
VCSDDではCEGの検証をテスト生成前のチェックポイントに強制組み込みすることで、整合性が壊れた状態でテスト生成・実装が進んでしまうことを構造的に不可能にします。
つまり、CoDDの整合性検証をVSDDのフェーズに強制組み込みしたいという意図があり、プラグイン内への直接実装をしているということです。
2つのツールを行き来するのではなく、単一のワークフローとして完結させることを目指す、それがVCSDDを作った理由です。
ここまで、VCSDDの仕組みを解説しました。

最後に、実際に実例を作ってみましたので、紹介します。

 実例：決算データ可視化アプリこちらが、VCSDDで作られたアプリです。

複数企業の売上高・営業利益・純利益をグラフで比較するWebアプリです。
なお、今回は実例のため、あえて途中途中に仕様を変更するよう最初のPlanningで仕込んでいます。
https://github.com/sc30gsw/financial-viz

 6スプリントの全体像開発は6スプリントに分けて進めました。各スプリントでテスト数とCEGのノード数がどう推移したかをまとめます。


Sprint
内容
テスト数
CEGノード数


1
基本機能（ComparisonChart、企業選択UI）
21
—

2
セクター分析追加（Adversary FIND-001から1a差し戻し→修正）
27
—

3
データスキーマ変更（flat JSON → nested JSON）
27
—

4
リアルタイム価格取得 + CoDD検証
30
14ノード

5
TanStack Query + up-fetch導入、仕様途中変更のCoDD検証
40
16ノード / 45エッジ

6
TrendChart実装 + Adversary FAIL → PASS 検証
71
18ノード / 52エッジ

Sprint 1で21本だったテストが、Sprint 6では71本に成長しました。そして Coherence Graph は最終的に 18ノード / 52エッジ を持つ依存グラフになりました。

 Sprint 2：Adversaryが仕様の穴を発見Sprint 1内のAdversaryレビューは PASS していました。しかし、Sprint 2の開始時に改めてレビューを実施したところ FAIL が出ました。
注目すべきは、21件のテストはすべて通過していたという点です。
コードは完璧に動作していましたが、仕様レベルに穴があったのです。
FAILした次元は5次元中「Spec Fidelity（仕様適合性）」の1次元のみで、指摘内容（FINDING）は「業界セクター分類がデータ定義に含まれていない」というものでした。
実際に記録されたFINDINGは以下の通りです。
!FINDING とは、AdversaryがPASS/FAILを判定する際に出力する指摘のことです。何が問題か・証拠となるファイルと行番号・どのフェーズに差し戻すかが構造化されて記録されます。
FIND-001.json
{
  "findingId": "FIND-001",
  "dimension": "spec_fidelity",
  "category": "spec_gap",
  "severity": "medium",
  "description": "The behavioral specification omits sector/industry classification as a data dimension for company comparison. The design:data-schema node and design:ui-components node must be updated to include sector metadata from Yahoo Finance summaryProfile. Without this, ComparisonChart cannot group or filter by industry sector.",
  "evidence": {
    "filePath": ".vcsdd/features/financial-viz/specs/behavioral-spec.md",
    "lineRange": "1-44",
    "snippet": "Requirements REQ-001..004 do not mention sector/industry classification as a data field"
  },
  "routeToPhase": "1a"
}
この時は、routeToPhase: "1a" により仕様フェーズへ自動ルーティングされ、仕様を修正した後にTDDを再実行しました。

 Sprint 5：途中で仕様が変わったときのCoDDSprint 5の開発中に、仕様に2つの要件（キャッシュTTL5分、リトライ×3回）を追記しました。
この変更の影響を /vcsdd-coherence-impact で分析したところ、影響ノードが自動検出されました。
面白いのは、2つの変更で波及範囲が異なった点です。

req:api-fetching への変更 → 3ノードに波及

design:data-schema への変更 → 6ノード（module:data-loader、module:chart-renderer、module:comparison-engine、design:fetch-layer、req:api-fetching、test:strategy）に波及
手作業なら設計書を一枚一枚確認する必要がありましたが、数秒で影響範囲が特定されました。
実際の解析結果は以下の通りです。
coherence-impact-change.json
{
  "impactFrom_req_api_fetching": {
    "count": 3,
    "nodeIds": ["design:fetch-layer", "module:data-loader", "test:strategy"]
  },
  "impactFrom_design_data_schema": {
    "count": 6,
    "nodeIds": [
      "module:data-loader", "module:chart-renderer", "module:comparison-engine",
      "design:fetch-layer", "req:api-fetching", "test:strategy"
    ]
  }
}
ここでは、「本当に整合性を自動的に担保できるのか」と驚きを感じつつも、CoDDのアイデア、課題感、そして仕組みに感動した瞬間でした。

 Sprint 6：意図的なFAIL → PASSの体験Sprint 6では、わざと未実装のまま Adversaryレビューにかけるテストを行いました。
TrendChartのYoYの前年比機能を意図的に実装せずにPhase 3へ進んだところ、Adversaryが6件のFINDINGを出して FAIL（1回目）しました。
E21-adversary-fail.txt
result: FAIL / total_findings: 6

F1: YoY growth rate mode not implemented; mode toggle absent; 5 PROPs untested
F2: buildTrendChartData(mode='yoyGrowth') falls through to buildAbsoluteData
F3: excludedCompanies always []; companies with <2yr not excluded in yoyGrowth
F4: TrendChart has no mode toggle buttons; no useState for mode
F5: excluded note UI exists but never populated; no test for note appearing
F6: no test verifying growth rate values match normalizeToGrowthRate() output

earliest_phase_routing: 2a
ここからが予想外の展開でした。YoY機能を実装して再レビューしたところ、今度は意図していなかった本物のバグが発見されました。
2回目 FAIL — tooltipとY軸がモード切替に追従していないバグ
3回目 FAIL — activeDot のテストが不足
結局、合計4回目のレビューでようやく PASS しました。
「意図的にFAILを体験する実験」のつもりが、その過程でAdversaryが実装上の問題を2件見つけてくれました。
これがVCSDDの品質ゲートが機能している最も説得力のある場面だったと感じています。

 最終成果最終的には、以下のような結果となり、完全にAIが手放しで開発をしても、品質から整合性まである程度担保できると感じました。
実際のコードベースを見ても、VibeCodingのような1ファイルに大量に書き込まれていたり、リファクタできる箇所が大量にあるなどが見当たらず、比較的品質の高いものが出来たのではと思います。
もちろん、実際のプロジェクトでは再度AIにレビューさせて、最終的に人間のレビューをするなどの工程は必要な品質ですが、1つのワークフローサイクルとしては上出来だと思います。

※ 現在のコードベースはVCSDDの再テストも兼ねて機能を追加したり、バックエンドのAPI構築なども含まれています
また、技術選定だったり、rulesやCLAUDE.mdなど各種AI環境に必要なドキュメントを事前に整えることで、VCSDDはより効果を発揮するとも感じました。

※ このアプリ作成では/initによるCLAUDE.md生成やrulesの整備は一切行っておりません。
最終的な数値としては、以下の結果が得られました。
71テスト全PASS

Adversary PASS（Sprint 6、4回目のレビューで合格）

18ノード / 52エッジ のCoherenceグラフで仕様変更に追従
要件から実装まで Chainlink Beadで完全トレース可能

 完成したアプリこちらが、実際に完成したアプリの概要と画面です。

具体的な機能としては以下の機能があります。

リアルタイム株価取得 — Yahoo Finance APIから最新の株価データを取得

ポートフォリオ評価損益パネル（Portfolio PnL Breakdown） — 保有数量と取得単価（現地通貨建て、1株あたり）を入力すると、評価損益を円換算で表示

企業比較チャート（ComparisonChart） — 複数企業の売上高・営業利益・純利益を棒グラフで並べて比較

トレンドチャート（TrendChart） — 企業ごとの業績推移を折れ線で表示。「絶対値」と「前年比（YoY）%」の切り替えが可能

セクター分析 — 業種別のグループ化・フィルタリング（Sprint 2でAdversaryに指摘されて追加した機能）


ダッシュボード画面


比較チャートの表示（売上高・絶対値）


比較チャートの表示（純利益・前年比%）


企業情報詳細

 まとめVSDDは「AIが書いたコードをAIに攻撃させる」という逆説的なアプローチで、AI開発の品質問題を構造的に解決します。
そこにCoDDの変更時の整合性維持を融合したVCSDDにより、AIが生成する仕様書・設計・実装が高品質かつ壊れにくく、乱れにくい仕組みが実現できました。
特に、設計の整合性が取れることのメリットは、プロジェクトが長期化・大規模化するほど大きくなると感じています。
従来のハーネスエンジニアリングで整合性を担保しようとすると、敵対的レビュー用のエージェントを増やしたり、rulesやCLAUDE.mdに失敗パターンを追加したりするアプローチが一般的でした。
しかし、これらはどれも対症療法に過ぎず、トークン効率の悪化やコンテキストの圧迫といったデメリットを抱え、半永久的に続けられるものではありません。
重要なのは、VCSDDがハーネスによる思想や習慣ではなく、仕組みによる強制である点です。
ゲートチェックフックが「仕様の前にコードを書く」ことをブロックする
Adversaryは「馴れ合い」が起きないよう毎回コンテキストをリセットする
CoDDは「設計が腐っていく」問題を依存グラフで自動追跡する
Chainlink Beadは「なぜこのコードがあるのか」を要件まで遡れるようにする
こうしたワークフローをハーネスエンジニアリングの一環として体系的に構築していくスキルは、今後ますます重要になると考えています。
今回の開発体験を通じて、AI支援開発が浸透すればするほど、「AIが働く環境をどう設計するか」「どんな仕組みであれば持続的に品質を保てるか」という問いへの答えが、開発の成否を分けると強く実感しました。
もちろん、将来的にモデル自体が進化すればワークフローの必要性が減る可能性もあります。しかし、AIがより強力になるほど、人間が「環境を構築する」役割は逆に大きくなっていくでしょう。
この記事が、少しでも皆さんのAI開発の参考になれば幸いです。

 参考文献https://gist.github.com/dollspace-gay/d8d3bc3ecf4188df049d7a4726bb2a00
https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence
https://github.com/yohey-w/codd-dev
https://zenn.dev/sc30gsw/articles/1373752d9713b3

 おまけVCSDDに興味を持っていただけた方向けに、実際の使い方と利用できる機能の一覧を紹介します。

 始め方（クイックスタート）以下、2通りの導入方法があります。

 インストールClaude Codeプラグイン経由（推奨）：
/plugin marketplace add sc30gsw/vcsdd-claude-code
/plugin install vcsdd@vcsdd-claude-code
/reload-plugins
スクリプト経由：
git clone https://github.com/sc30gsw/vcsdd-claude-code
cd vcsdd-claude-code
bash install.sh --profile standard

 基本フロー# 1. フィーチャーパイプラインを初期化（feature名はkebab-case）
/vcsdd-init user-auth

# 2. EARS形式で仕様を書き、検証アーキテクチャを定義する
/vcsdd-spec

# 3. Adversaryが仕様をレビューする
/vcsdd-spec-review

# 4. 失敗するテストを生成する（全テストがREDになること）
/vcsdd-tdd

# 5. 実装してテストをGreenにし、リファクタリングする
/vcsdd-impl

# 6. Adversaryが5次元でレビューする
/vcsdd-adversary

# 7. FAILの指摘を正しいフェーズに自動ルーティングする（FAILの場合）
/vcsdd-feedback

# 8. プロパティテスト・ファジング等を実行する
/vcsdd-harden

# 9. 4つの収束条件を確認して完了判定する
/vcsdd-converge

# 現在のフェーズと状態を確認する（いつでも実行可）
/vcsdd-status
!モードの切り替えについて
初期化時に --mode オプションで動作モードを選択できます。
/vcsdd-init user-auth --mode lean    # デフォルト。プロダクト開発・プロトタイプ向け
/vcsdd-init user-auth --mode strict  # 金融・セキュリティ等の高保証作業向け



Lean
Strict


スプリント契約
任意
必須

Phase 1c承認
AI判定のみ
人間承認も必須

Adversaryレビュー上限
3回
5回

証明義務
選択的
強制

迷ったら Lean から始めることをおすすめします。

 利用できるコマンド一覧
 パイプライン操作6つのフェーズを順に進めるコアコマンドです。各コマンドはフェーズゲートを通過した後でないと実行できません。


コマンド
フェーズ
何をするか


/vcsdd-init <feature> [--mode lean|strict]
init
フィーチャーパイプラインを初期化する

/vcsdd-spec
1a + 1b
EARS形式で仕様を書き、検証アーキテクチャを定義する

/vcsdd-spec-review
1c
Adversaryが仕様をレビューする

/vcsdd-tdd [--framework vitest|pytest]
2a
失敗するテストを生成する（全テストがREDになること）

/vcsdd-impl
2b + 2c
実装してテストをGreenにし、リファクタリングする

/vcsdd-contract-review
2c
Strictモード専用：スプリント契約をレビューする

/vcsdd-adversary [--sprint N]
3
Adversaryが5次元でレビューする

/vcsdd-feedback
4
FAILの指摘を正しいフェーズに自動ルーティングする

/vcsdd-harden [--tier 1|--skip-optional]
5
プロパティテスト・ファジング等を実行する

/vcsdd-converge
6
4つの収束条件を確認して完了判定する

使用例
# 新機能の開発を開始する（TypeScriptプロジェクトの場合）
/vcsdd-init user-auth --mode lean --language typescript

# 仕様とテストを書いて実装する
/vcsdd-spec
/vcsdd-spec-review
/vcsdd-tdd --framework vitest
/vcsdd-impl

# Adversaryレビューを実施し、FAILなら差し戻す
/vcsdd-adversary
/vcsdd-feedback       # FAILの場合のみ。差し戻し先フェーズから再開する

# 形式検証を実行して完了判定する
/vcsdd-harden
/vcsdd-converge

 ユーティリティフェーズに関わらずいつでも使えるサポートコマンドです。


コマンド
何をするか


/vcsdd-status [--all-features|--json]
現在のフェーズと状態を確認する

/vcsdd-trace <bead-id> [--check-completeness]
要件→テスト→実装のトレースチェーンを表示する（例: REQ-001）

/vcsdd-commit [--message "note"|--tag-only]
フェーズタグ・ビードサマリー付きでコミットする

/vcsdd-escalate [--phase N --reason "..."]
Adversaryレビューの上限に達した際にArchitectが承認する

使用例
# 現在どのフェーズにいるかを確認する
/vcsdd-status

# 複数のfeatureを管理している場合は全件表示
/vcsdd-status --all-features

# 「このコードはなぜ存在するか」を要件まで遡って確認する
/vcsdd-trace REQ-001

# フェーズ完了時にコミットする（自動でフェーズタグが付く）
/vcsdd-commit

# Adversaryレビューが上限（Lean: 3回、Strict: 5回）に達した場合に人間が判断する
/vcsdd-escalate --phase 3 --reason "構造的な問題は修正済み。残る指摘は許容範囲内"

 Coherenceコマンド（CoDD機能）仕様書のfrontmatterに coherence: ブロックを追記すると有効になるCoDD機能のコマンドです。仕様変更の影響範囲をグラフで追跡します。


コマンド
何をするか


/vcsdd-coherence-scan
spec frontmatterからCEGを再構築する

/vcsdd-coherence-validate
参照整合性チェックと循環依存検出を実行する

/vcsdd-coherence-impact [node_id|--diff HEAD~1]
変更の影響ノードを伝播分析する

使用例
# 仕様書を編集した後、CEGを最新状態に再構築する
/vcsdd-coherence-scan

# Phase 2aに入る前に、グラフに循環依存や参照ミスがないか確認する
/vcsdd-coherence-validate

# 直前のコミットからの変更を自動検出して影響ノードを分析する
/vcsdd-coherence-impact

# 特定のノードを起点に影響を分析する
/vcsdd-coherence-impact design:data-schema

# 特定のコミットとの差分を起点に影響を分析する
/vcsdd-coherence-impact --diff HEAD~1

 スキル（内部実装）コマンドから自動で呼び出される内部スキルです。ユーザーが直接呼び出す必要はありませんが、各コマンドの実際の処理はこれらのスキルが担っています。


スキル
担当するコマンド・役割


vcsdd-spec-crystallization

/vcsdd-spec — EARS形式の仕様記述ガイダンス

vcsdd-adversarial-refinement

/vcsdd-adversary — Finding分類・Adversaryキャリブレーション

vcsdd-feedback-routing

/vcsdd-feedback — フェーズへのルーティングテーブル

vcsdd-formal-hardening

/vcsdd-harden — 言語別検証ツール選択

vcsdd-convergence-detection

/vcsdd-converge — 4次元収束分析

vcsdd-traceability

/vcsdd-trace — Chainlink Beadの作成・走査

vcsdd-git-integration

/vcsdd-commit — コミットメッセージ形式・タグパターン

vcsdd-sprint-contracts

/vcsdd-contract-review — スプリントコントラクトテンプレート

vcsdd-language-typescript

/vcsdd-harden — TypeScript向けfast-check/Stryker統合

vcsdd-language-rust

/vcsdd-harden — Rust向けKani/proptest/cargo-fuzz統合

vcsdd-language-python

/vcsdd-harden — Python向けHypothesis/mutmut統合


 利用できるエージェントVCSDDは内部で4つのエージェントが連携して動作します。ユーザーが直接呼び出す必要はなく、各コマンドが自動で起動します。


エージェント
モデル
役割


vcsdd-orchestrator
Sonnet
パイプラインの調整・ゲートチェックの実行

vcsdd-builder
Sonnet
仕様の執筆・テスト生成・実装

vcsdd-adversary

Opus（フレッシュコンテキスト）
敵対的レビュー・PASS/FAIL判定

vcsdd-verifier
Sonnet
形式検証（Phase 5）の調整


 VCSDDが生成するディレクトリ構成/vcsdd-init を実行すると、以下の構成が自動生成されます。各ファイルがフェーズをまたいだ成果物の受け渡し口になります。
.vcsdd/
├── index.json                        # 全featureの一覧とアクティブなfeature
├── history.jsonl                     # 全操作の追記専用監査ログ
└── features/
    └── <feature-name>/
        ├── state.json                # パイプラインの現在状態（唯一の真実）
        ├── coherence.json            # CEG依存グラフ（coherence有効時のみ）
        ├── specs/
        │   ├── behavioral-spec.md    # Phase 1a：EARS形式の行動仕様
        │   └── verification-architecture.md  # Phase 1b：検証アーキテクチャ
        ├── reviews/
        │   └── sprint-{N}/
        │       ├── input/manifest.json        # レビュー対象の成果物一覧
        │       └── output/
        │           ├── findings/FIND-NNN.json  # Adversaryの個別指摘
        │           └── verdict.json            # PASS/FAIL判定結果
        ├── evidence/
        │   ├── sprint-{N}-red-phase.log       # REDフェーズの証拠（テスト失敗）
        │   └── sprint-{N}-green-phase.log     # GREENフェーズの証拠（テスト通過）
        └── verification/
            ├── verification-report.md         # Phase 5：検証レポート
            ├── security-report.md             # Phase 5：セキュリティレポート
            └── purity-audit.md                # Phase 5：純粋性監査

スキル	担当するコマンド・役割
`vcsdd-spec-crystallization`	`/vcsdd-spec` — EARS形式の仕様記述ガイダンス
`vcsdd-adversarial-refinement`	`/vcsdd-adversary` — Finding分類・Adversaryキャリブレーション
`vcsdd-feedback-routing`	`/vcsdd-feedback` — フェーズへのルーティングテーブル
`vcsdd-formal-hardening`	`/vcsdd-harden` — 言語別検証ツール選択
`vcsdd-convergence-detection`	`/vcsdd-converge` — 4次元収束分析
`vcsdd-traceability`	`/vcsdd-trace` — Chainlink Beadの作成・走査
`vcsdd-git-integration`	`/vcsdd-commit` — コミットメッセージ形式・タグパターン
`vcsdd-sprint-contracts`	`/vcsdd-contract-review` — スプリントコントラクトテンプレート
`vcsdd-language-typescript`	`/vcsdd-harden` — TypeScript向けfast-check/Stryker統合
`vcsdd-language-rust`	`/vcsdd-harden` — Rust向けKani/proptest/cargo-fuzz統合
`vcsdd-language-python`	`/vcsdd-harden` — Python向けHypothesis/mutmut統合

カテゴリ	例
構造的スロップ	使われない抽象化、不要なインターフェース設計、過剰なレイヤー分離
ロジックスロップ	ハッピーパスのみ対応、バリデーションが浅い、エラーが silent failure になる
テストスロップ	実装をそのままコピーしたミラーテスト、アサーションが弱い、過剰なモックで本物を検証していない

課題	SDD	VSDD	CoDD	VCSDD
AIスロップの排除	❌	✅	❌	✅
敵対的AIレビュー（Adversary）	❌	✅	❌	✅
仕様・テスト・実装の品質保証	△（仕様のみ）	✅	❌	✅
形式検証（プロパティテスト・ファジング）	❌	✅	❌	✅
成果物の来歴トレース（なぜこのコードがあるか）	❌	✅	❌	✅
変更時の影響トレース（何が影響を受けるか）	❌	❌	✅	✅
依存グラフの自動構築	❌	❌	✅	✅
要件変更時の影響範囲の自動伝播	❌	❌	✅	✅
設計の整合性維持	❌	❌	✅	✅
変更によるテスト・仕様の陳腐化防止	❌	❌	✅	✅

フェーズ	内容	CoDD連動
Phase 1: 仕様結晶化	EARS形式で振る舞いを仕様化し、検証アーキテクチャを定義する	`coherence:` frontmatter記述 → CEGにノード・エッジ登録
Phase 2a: テスト生成（Red）	失敗するテストを生成する	CEG構造検証がゲート — 整合性違反・循環依存があればブロック
Phase 2b/2c: 実装・リファクタ	テストをGreenにし、コードを整える	—
Phase 3: 敵対的レビュー	別AIがPASS/FAILを判定する	CEGの状態もレビュー対象に含まれる
Phase 4: フィードバック統合	FAILの指摘を適切なフェーズに自動で差し戻す	仕様変更 → 影響する下流ノードを自動特定
Phase 5: 形式的硬化	プロパティテスト・ファジング等で形式的に検証する	—
Phase 6: 収束判定	仕様・テスト・実装・証明の4つが揃って初めて完了	CEGの整合性も収束条件に含まれる

役割	担当	責務
Architect	人間	戦略的ビジョン、仕様承認
Builder	LLM（Sonnet）	仕様執筆、テスト生成、実装
Adversary	LLM（Opus、毎回新規コンテキスト）	超批判的レビュー、ゼロトレランス
Verifier	LLM（Sonnet）	形式検証の調整

比較項目	CoDD単体	VSDD単体	VCSDD（融合）
変更時の影響追跡	✅ 自動で特定	❌ 手動で確認	✅ 自動で特定
実装品質の保証	❌ 品質ゲートなし	✅ Adversaryが検証	✅ Adversaryが検証
整合性違反の強制ブロック	⚠️ 人間承認が必要（自動ブロックではない）	❌ そもそも整合性を追跡しない	✅ テスト生成前にブロック
変更後のテスト生成前チェック	❌	❌	✅ CEGが自動検証
仕様→テスト→実装の完全トレース	❌	✅ Chainlink Bead	✅ Chainlink Bead + CEG

Sprint	内容	テスト数	CEGノード数
1	基本機能（ComparisonChart、企業選択UI）	21	—
2	セクター分析追加（Adversary FIND-001から1a差し戻し→修正）	27	—
3	データスキーマ変更（flat JSON → nested JSON）	27	—
4	リアルタイム価格取得 + CoDD検証	30	14ノード
5	TanStack Query + up-fetch導入、仕様途中変更のCoDD検証	40	16ノード / 45エッジ
6	TrendChart実装 + Adversary FAIL → PASS 検証	71	18ノード / 52エッジ

	Lean	Strict
スプリント契約	任意	必須
Phase 1c承認	AI判定のみ	人間承認も必須
Adversaryレビュー上限	3回	5回
証明義務	選択的	強制

コマンド	フェーズ	何をするか
`/vcsdd-init <feature> [--mode lean\|strict]`	init	フィーチャーパイプラインを初期化する
`/vcsdd-spec`	1a + 1b	EARS形式で仕様を書き、検証アーキテクチャを定義する
`/vcsdd-spec-review`	1c	Adversaryが仕様をレビューする
`/vcsdd-tdd [--framework vitest\|pytest]`	2a	失敗するテストを生成する（全テストがREDになること）
`/vcsdd-impl`	2b + 2c	実装してテストをGreenにし、リファクタリングする
`/vcsdd-contract-review`	2c	Strictモード専用：スプリント契約をレビューする
`/vcsdd-adversary [--sprint N]`	3	Adversaryが5次元でレビューする
`/vcsdd-feedback`	4	FAILの指摘を正しいフェーズに自動ルーティングする
`/vcsdd-harden [--tier 1\|--skip-optional]`	5	プロパティテスト・ファジング等を実行する
`/vcsdd-converge`	6	4つの収束条件を確認して完了判定する

コマンド	何をするか
`/vcsdd-status [--all-features\|--json]`	現在のフェーズと状態を確認する
`/vcsdd-trace <bead-id> [--check-completeness]`	要件→テスト→実装のトレースチェーンを表示する（例: `REQ-001`）
`/vcsdd-commit [--message "note"\|--tag-only]`	フェーズタグ・ビードサマリー付きでコミットする
`/vcsdd-escalate [--phase N --reason "..."]`	Adversaryレビューの上限に達した際にArchitectが承認する

コマンド	何をするか
`/vcsdd-coherence-scan`	spec frontmatterからCEGを再構築する
`/vcsdd-coherence-validate`	参照整合性チェックと循環依存検出を実行する
`/vcsdd-coherence-impact [node_id\|--diff HEAD~1]`	変更の影響ノードを伝播分析する

エージェント	モデル	役割
`vcsdd-orchestrator`	Sonnet	パイプラインの調整・ゲートチェックの実行
`vcsdd-builder`	Sonnet	仕様の執筆・テスト生成・実装
`vcsdd-adversary`	Opus（フレッシュコンテキスト）	敵対的レビュー・PASS/FAIL判定
`vcsdd-verifier`	Sonnet	形式検証（Phase 5）の調整

はじめに

AIスロップという問題

VSDDの限界とCoDDとの出会い

CoDDとは

VCSDDが解決する課題

VCSDD（整合性保証型仕様駆動開発）とは

VCSDDの基盤：VSDD

6フェーズパイプライン

4つの役割

Adversary（敵対的レビュー）

VCSDDにおけるCoherence Engineの動作

CEG（Conditioned Evidence Graph）とは

Phase 2a進入前の整合性チェック

仕様変更時の影響伝播

VSDD単体・CoDD単体との違い

実例：決算データ可視化アプリ

6スプリントの全体像

Sprint 2：Adversaryが仕様の穴を発見

Sprint 5：途中で仕様が変わったときのCoDD

Sprint 6：意図的なFAIL → PASSの体験

最終成果

完成したアプリ

まとめ

参考文献

おまけ

始め方（クイックスタート）

インストール

基本フロー

利用できるコマンド一覧

パイプライン操作

ユーティリティ

Coherenceコマンド（CoDD機能）

スキル（内部実装）

利用できるエージェント

VCSDDが生成するディレクトリ構成

Discussion