AI時代における品質重視型プロジェクト運用モデルの提案（2/3）

SDD中心の「成果物設計」で、AIを“自走”させる（Spec / SC / I/F定義 / Delta）

本トピックは3部構成の第2回となっています。

• AI時代における品質重視型プロジェクト運用モデルの提案（1/3）
• AI時代における品質重視型プロジェクト運用モデルの提案（2/3）（本記事）
• AI時代における品質重視型プロジェクト運用モデルの提案（3/3）

前編（1/3）では、SDD×多層ゲートで「仕様を守らないAI」をCIで止める全体像を紹介しました。
本編（2/3）では、そのモデルを現場に落とすための 成果物（ドキュメント／定義資産／テスト）設計 を具体化します。
※ATDD/TDDの技術詳細（フレームワーク／実装手法）は現場依存が大きいため踏み込みません。ここでは「運用として、何をどう置くか」に絞ります。

先に略語の整理

• SDD：Spec-Driven Development（仕様駆動開発）
• BR：Business Rule（業務ルール）
• SC：Scenario（受入シナリオ。Given/When/Thenで書く）
• I/F：Interface（インターフェース。この記事では UI / API / DB の“外部仕様”をまとめて指します）

※本記事では UI / API / DB の外部仕様（入出力・制約）を、差分が取りやすい形式で管理する資産 をまとめて 「I/F定義」 と呼びます。

伝えたいこと

• SDD（Spec） は「AIが迷わない道しるべ」。ただし、SpecだけではAIは自走しません。
• ATDD/TDD（テスト） は、AIにとっての最強のアクセルです。
  • ゴールが「テストを通過するようにコーディングする」になり、仮説の余地が減る
  • AIは「実装 → テスト実行 → 修正」を高速で回し、壁打ち往復を減らして自走しやすくなる
• ただし 「テストに通れば良い」だけにすると、AIは抜け道実装（テストを通すためだけの実装、テスト改変など）に寄りやすい。
  → だからこそ、Spec（意図・境界）＋レビュー（オラクル防衛）＋CIゲート（機械検査） を“統合”して運用します。

本記事のゴール

この記事を読み終わると、次の状態を作れます。

• チケットを切ったときに 「何を作るべきか」（成果物の最小セット）が明確になる
• Spec・受入シナリオ・I/F定義・テストが どの順番で、どの責務で 更新されるかが分かる
• AIに「曖昧さのないゴール」を与え、壁打ち疲れを減らす運用へ寄せられる

なぜ “成果物設計” が壁打ち疲れに効くのか

AI導入後の疲弊は、根っこを辿るとだいたい次の2つに収束します。

1. ゴールが曖昧
   • 「それっぽく実装して」「良い感じに直して」は、AIに仮説を許します
   • その結果、意図からズレ、壁打ちが増えます（しかも回数が読めない）
2. ゴール（テスト）が壊れる
   • AIがテストまで書き換える／都合よく弱めると、品質のオラクルが崩れます
   • 「通った＝正しい」が成立しなくなり、人間の確認負債が爆発します

ここで効くのが、「仮説の余地がないゴール」を先に置くという考え方です。

AIとATDD/TDDの相性は“加速器”である

ATDD/TDDを「品質ゲート」としてだけ捉えると、AI時代のメリットを取り逃します。

テストはAIへの指示として最も誤解が少ない

• ATDDは Given/When/Then で 前提・操作・期待結果 を固定します
• TDD（単体テスト）は境界・例外・不変条件を、実行可能な形で固定します

AIに対して「テストに通るように実装して」は、（自然言語の指示より）圧倒的にブレません。

壁打ち往復を減らし、AIが自走できる

人間が細部を詰め切る前に、実行可能なゴール（テスト） を置くと、AIは次のループを自走しやすくなります。

• 実装
• テスト実行
• 失敗から修正
• 再実行

人間は、微細な修正指示で壁打ちする代わりに、

• Specで「意図・境界・非ゴール」を固定し
• 受入・単体テストで「期待結果」を固定し
• レビューとCIゲートで「抜け道」を塞ぐ

……という 運用設計 に集中できます。

成果物の最小セット

「ドキュメントが増えてシンドい」問題の多くは、目的が“説明”になってしまうことで起きます。
このモデルでは、成果物を増やす目的をこう定義します。

成果物を増やす目的は “説明” ではなく
機械的に検査できる定義資産を分離し、CIで検知できる状態にすること

レイヤー別：成果物の最小セット

レイヤー	成果物	目的（AIと人間のための役割）
SDD	Spec（＋BR）	意図・境界・非ゴール・用語・業務ルール（判定順序/例外/不変条件）を固定
ATDD	受入シナリオ（SC）	外側から見た期待（Given/When/Then）を固定。AIの実行可能ゴール
I/F	UI / API / DB 定義	“形”を固定（画面構造、API入出力、DB制約）。CIで検知しやすい
ログ	Delta（Decision Log）	なぜそう決めたか／変更の経緯。レビューの摩擦を下げる
下流	テストコード/実装	上流成果物に従って生成（AIの主な作業場所）

参照方向ルール（トップダウンを崩さない）

成果物が増えると、ドキュメント同士が相互参照し始めて「どれが正なのか」が曖昧になります。
この状態を放置すると、AIは参照の網に引っ張られて“それっぽい整合”を取ろうとし、結果として ドリフト（意図と実装のズレ） が加速します。

そこで、このモデルでは 「参照の向き」 を明文化し、上流資産を“単一の正（Single Source of Truth）”として保ちます。

参照方向のルール

• 必須：下流 → 上流
  • 受入シナリオ、テスト、実装が上流IDを参照する（トレーサビリティの起点）
• 禁止（原則）：上流 → 下流
  • Specがシナリオ/テスト/実装を参照しない（トップダウンが崩れるため）
• 許可：受入シナリオ（SC） → UI/API/DB定義
  • “期待結果”がどのI/Fに現れるかを接続する（変更影響が追いやすい）

この施策の優位性

• 上流が汚れない（意思決定のログが残る）
  上流（Spec/SC/I/F定義）が下流（テスト/実装）を参照し始めると、上流が「結果の追認」に引きずられます。
  参照方向を固定することで、上流は常に「意図・境界・期待結果・I/F」を定義する場所であり続けます。
• レビューが現実的になる（見るべき場所が固定される）
  上流に“正”を集約し、下流はID参照で接続するだけにすることで、レビュー対象の分割（PdM/QA/Eng）と相性が良くなります。
• CIで機械的に検査できる（運用を属人化させない）
  「下流が上流IDを参照しているか」「SCがI/Fに接続しているか」は grep/静的検査で落とせます。
  人が“頑張って読む”より、AI時代は“弾ける形”に寄せた方が安定します。

従来のツールとの差

Spec-driven開発支援ツール（例：Spec Kit / cc-sdd）は、フェーズを進めるほど plan/tasks 等のドキュメントが増え、
それぞれが「前提となるドキュメント」や「参照すべきファイル」を列挙していきます。
プロジェクトが育つほど参照が太りやすく、参照方向のルールが無いと、依存関係がスパゲッティ化しやすいのが実情です。

本モデルは特定ツールに依存せず、“どのエージェントを使っても守れる運用ルール” として参照方向を固定します。

※SpecからSCを参照しない欠点は「Spec側からシナリオ一覧が見えない」ことです。
　実務では、検索（grep/Code Search）や、後編で紹介するCIの逆引き生成（任意）で補完できます。

ディレクトリ構成の例

.
├── .github/
│   └── workflows/
│       └── ci.yml
├── docs/
│   ├── specs/
│   │   └── spec-00X/
│   │       ├── spec.md                   # SDD：機能説明＋BR（判定順序・例外・不変条件）
│   │       └── delta.md                  # Decision Log / Delta（変更履歴・意図・経緯）
│   ├── scenarios/
│   │   └── sc-00X.md                     # ATDD：SC（Given/When/Then）
│   └── interfaces/                       # I/F定義（UI / API / DB）
│       ├── ui/
│       │   ├── UI-00X.ui.yaml            # UI定義（配置・制約・活性条件）
│       │   └── UI-00X.transitions.md     # 画面遷移図（Markdown内にMermaid等で記述）
│       ├── api/
│       │   └── openapi.yaml              # API定義（OpenAPIなど）
│       └── db/
│           └── migrations/
│               └── 001_create_tables.sql # DB定義（DDL/マイグレーション）
├── scripts/
│   └── traceability/                     # 後編で扱う（CI検査の仕組み）
└── AGENTS.md

Spec（SDD）の最小テンプレ（“AIが迷わない道しるべ”）

Specは「長文で全部を書く」ものではありません。
AIが迷うポイント（境界・例外・不変条件）と、人間が判断したいポイント（非ゴール・決定事項） に寄せて短くします。

# <機能名>

- Spec ID: SPEC-XXX-001
- 対象ユーザー：<ペルソナ>

## 背景（WHY）
- <なぜ必要か>

## ゴール（アウトカム）
- <何ができる状態になれば成功か>

## 非ゴール（やらないこと）
- <今回やらない範囲を明示>

## 用語
- <用語>：<定義>

## 境界（スコープ）
- <含む>
- <含まない>

## 観測性（Observability）
- <成功/失敗が観測できる形>

## 決定事項（Decision / Delta要点）
- <こう決めた理由>
- <代替案と不採用理由（1行でOK）>

## 未決事項（Open Questions）
- <まだ決めていない点>
- <後続の判断が必要な点>

## 業務ルール（BR）
### BR-XXX-001 <ルール名>
- 判定順序：
- 例外：
- 不変条件（Invariant）：

BR（業務ルール）のコツ：AIが“抜け道”を作れない粒度にする

BRは、次の3点セットで書くと強いです。

• 判定順序：何を先に判定するか（枝刈りの順番）
• 例外：誰が例外か（ロール／状態／条件）
• 不変条件（Invariant）：絶対に破ってはいけない状態（永続化された後も含む）

例（イメージ）：

### BR-ORDER-001 取引停止の顧客には注文を作成できない
- 判定順序：最初に取引停止を確認する（以降の判定を行わない）
- 例外：管理者ロールは“参照のみ”可能だが作成は不可
- 不変条件（Invariant）：取引停止顧客の注文は、新規作成されない

受入シナリオ（ATDD）は「AIのゴール」を固定する

ATDDは、フレームワークより 書式（Given/When/Then）と観測可能性 が重要です。
さらに、このモデルでは 受入シナリオが上流IDを参照 します。

• 参照BR：どの業務ルールを守るべきか
• 参照UI/API/DB定義：どのI/Fに接続するか（変更点の追跡がしやすくなる）

## SC-ORDER-001 取引停止顧客の注文作成は拒否される
- 参照BR: BR-ORDER-001
- 参照UI: UI-ORDER-01
- 参照API: API-ORDER-CREATE

Given 取引停止の顧客「C001」が存在する
When ユーザーが注文を作成する
Then APIは400を返し、エラーコード "ORDER_CUSTOMER_SUSPENDED" を返す
And DBに注文は作成されない

※ここでのポイントは「期待結果が観測可能」になっていることです。
　（APIのステータス／エラーコード／DBに作られない、など）

UI / API / DB 定義は“形”を固定し、CIで弾ける状態にする

UI / API / DB を文章だけで管理すると、AIのドリフトを検知しづらくなります。
そこで、これらは 差分が取りやすい構造化形式（YAML/OpenAPI/DDL等）で置き、変更があればレビューとCIで必ず可視化します。

• UI定義：画面要素、制約、活性条件、主要イベント
• API定義：operation/入力/出力/エラー形式
• DB定義：スキーマ、型、制約、マイグレーション

形式は現場に合わせてよいですが、「IDが付く」「差分がレビューできる」「CIで検査できる」 ことだけは死守します。

レビュー待ち（キュー詰まり）を現実的にさばくルール

レビュー待ちのストレスは「待つこと」ではなく 止まること です。
そこで、品質ゲートを維持しながら、待ち時間は並列化で吸収します。

ルール（明文化しておく）

• 原則：品質ゲートは維持する（レビューとCIは省略しない）
• ルール：レビュー待ち中は次工程へ先行着手してよい（並列化）
  • 例：Specレビュー待ち中に、受入シナリオ案やテスト骨格の作成に着手
• ルール：前工程からフィードバック（修正）が入ったら、先行着手した次工程にも必ず反映する
  • 具体：Specが変わったら、SC／テスト／実装の “参照ID・期待結果・境界条件” を同期する
  • 影響が大きい場合は、先行着手した作業を「捨てて作り直す」判断も含め、差分を明示して再レビューに回す
• ルール：先行着手した成果物は「暫定」であることを明示する（PRタイトルやラベルでOK）
  • 後続の差分吸収（rebase/追加コミット）を前提にし、レビュー側も“暫定”として見る

この運用で、待ち時間をゼロにはできないが、チームのスループットを落としにくい状態に寄せられます。

“Done” を定義する（AI時代は特に）

AIが入ると、途中経過（コミット）の品質がブレやすいので、Doneを明文化しておくと運用が安定します。

チケットが「レビューに出せる」最低条件

• Specに「境界・非ゴール・未決事項」が書かれている
• SC（受入シナリオ）が観測可能な期待結果になっている
• UI/API/DB定義のどこを触るのかが明示されている（ID参照）
• 生成物（実装/テスト）が上流IDを参照している（コメントでも良い）

まとめ

• SDD（Spec）は「道しるべ」。しかし、道しるべだけではAIは迷う
• ATDD/TDD（テスト）は「ゴール」。仮説の余地がないゴールを置くとAIは自走しやすい
• ただし “テストに通れば良い” に寄ると品質が壊れる
  → だから Spec＋レビュー＋CI を統合し、抜け道を塞ぐ

次回予告（3/3）

後編では、ここまでの成果物設計を「運用で頑張る」から卒業させます。

• CIで“ドリフトを検知して弾く”：トレーサビリティの機械化（最小ルール）
• 互換維持 vs 改善/仕様変更：受入テストやレビューの判断基準をどう運用に落とすか（重要論点）