0xdope

AI駆動開発を回す実践ガイド: SDD×TDDとフィードバック・ループ

Sunday, February 1, 2026 · B. Ackkerman · AI · 8 min read

仕様を先に固め、テストで縛り、短いループで改善する実運用フローを具体化する。

AIを開発に組み込むと、実装速度は上がる。だが、速度だけでは品質は上がらない。 品質を上げるには、手順と制約を設計し、短いフィードバック・ループで回し続ける必要がある。 この記事では、SDDとTDDを組み合わせた運用を、実例ベースで整理する。

基本の手順

実運用での基本フローは次のとおりだ。

  1. アイディア検討
  2. 仕様策定
    Input: システム概要、UIイメージ
    Output: docs/spec.md
  3. 計画策定
    Input: docs/spec.md
    Output: PLANS.md
  4. コーディング
    Input: PLANS.md
    Output: 実コード、UIキャプチャなど
  5. テスト実行
  6. 計画進捗を更新
  7. 4-6を繰り返し、品質に問題がないことを確認して終了
---
config:
  look: handDrawn
  theme: dark
---
flowchart TD
    A[アイディア検討] --> B[仕様策定 docs/spec.md]
    B --> C[計画策定 PLANS.md]
    C --> D[コーディング]
    D --> E[テスト実行]
    E --> F[進捗更新]
    F --> G{品質OKか}
    G -- No --> D
    G -- Yes --> H[完了]

重要な原則

1. フィードバック・ループを設計する

エージェント設計の本質は複雑化ではなく、ループ設計にある。 Anthropicの解説でも、LLM + ツール呼び出し + フィードバックのシンプルな構造が強調されている。
https://www.anthropic.com/engineering/building-effective-agents

さらに、推論・計画・ツール実行・観測のループを適切に回せるかどうかが、性能差を生むことも示されている。
https://arxiv.org/abs/2404.11584

2. ドキュメントはコードと近いところに設置する

ドキュメントと実装が離れるほど、同期ズレが起きる。 Coding Agentに参照させる情報は、リポジトリ内でコードに近い位置に置くほうが精度が落ちにくい。

運用としては次が効く。

  • ルートに AGENTS.md を置き、横断的ルールを固定する
  • 仕様は docs/spec.md で一元管理する
  • 手順と進捗は PLANS.md に記録する
  • 実装の判断理由はコード近傍のコメント・型・テストで残す

3. 要件→テスト→コード

順序は逆にしない。要件を先に固め、テストで制約を張ってからコードを書く。

仕様駆動開発(Spec Driven Development: SDD)

SDDは「コードの前に仕様を書く」を徹底するアプローチだ。 GitHubのSpec Kitはこの思想を体系化している。
https://github.com/github/spec-kit

ただし、現場の速度要件を考えると、仕様を多ファイルに分割しすぎると管理コストが上がる。 そのため実務では、docs/spec.md の単一ファイルで仕様を閉じるほうが回しやすいケースが多い。

SDDで押さえるべき4ステップ:

  • Requirements: WHY/WHATを書く（HOWは書かない）
  • Design: 構造・責務・制約を定義する
  • Tasks: 実装可能な粒度へ分解する
  • Implementation: AI実装 + 人レビューで収束させる

テスト駆動開発(Test Driven Development: TDD)

TDDはAI開発と相性が良い。最初に振る舞いを定義し、実装の暴走を防げるからだ。 参考: https://t-wada.hatenablog.jp/entry/definition-of-tdd

基本サイクル:

  • List
  • Red
  • Green
  • Refactor

特にList（テストリスト）が重要だ。ここで「何を変えるか」を明示すると、以降の実装がブレにくい。

SDDとTDDを組み合わせた開発アプローチのイメージ

SDDで仕様境界を決め、TDDで実装境界を制御する。 この2段構えにすると、AI実装の速度と品質を両立しやすい。

---
config:
  look: handDrawn
  theme: dark
---
flowchart LR
    R[Requirements<br/>docs/spec.md] --> D[Design]
    D --> T[Tasks<br/>PLANS.md]
    T --> L[Test List]
    L --> Red[Red]
    Red --> Green[Green]
    Green --> Ref[Refactor]
    Ref --> Rev{仕様に一致?}
    Rev -- No --> D
    Rev -- Yes --> Done[マージ候補]

実運用

使用するファイル

  • AGENTS.md
    プロジェクト共通の行動規範、品質基準、推奨ツールを定義する
  • Skills/
    反復作業をスキル化し、プロンプトの再入力コストを下げる
  • docs/spec.md
    仕様の単一情報源（Single Source of Truth）
  • PLANS.md
    方針、To-Do、進捗、意思決定ログを管理する
  • scripts/capture-screenshots.py
    UI検証の自動化に使う

AGETNS.md という誤記を見かけることがあるが、正しくは AGENTS.md だ。

典型的な副産物（中間生成物）

  • docs/spec.md
  • PLANS.md
  • scripts/capture-screenshots.py
  • UIキャプチャ、スナップショット差分

実例

例1: 旅程アプリ(Webアプリ)

目的は、交通・宿泊イベントを一本のタイムラインで管理し、共有リンクで閲覧できるようにすることだった。 docs/spec.md でGoal/Non-Goal、ドメインモデル、API境界を先に確定し、そこから PLANS.md に落として実装を進めた。

例2: ミリ秒精度時計(macOSネイティブアプリ, Swift)

HH:mm:ss.SSS をメニューバーに常時表示する最小要件を先に固定し、非ゴールを明確化して機能膨張を防いだ。 Swift + AppKit + SwiftPM の構成で、Dock非表示や更新周期の制約まで仕様に落としている。

例3: AI議事録生成ツール(Webkitアプリ, Rust + TypeScript(Tauri) + LLM)

音声入力から文字起こし、要約、Markdown保存までをローカル完結で設計した。 MVPはPythonで検証し、後にRust/Tauriへ移植する前提で、モデル形式や依存排除方針まで仕様で先に固めている。

自動化

自動化は「速くするため」だけではなく、「レビュー対象を固定するため」に導入する。

  • Makefile + PythonスクリプトでUIスナップショットを自動生成する
  • AGENTS.md に検証手順を明記し、エージェント実行時の手順漏れを防ぐ
  • 複雑タスクでは PLANS.md を必須化し、/review -> fix -> /review の収束ループを回す
---
config:
  look: handDrawn
  theme: dark
---
sequenceDiagram
    participant Dev as Developer/Agent
    participant Plan as PLANS.md
    participant Test as Test & Snapshot
    participant Review as Review

    Dev->>Plan: タスクを分解して更新
    Dev->>Test: 実装後にテスト実行
    Test-->>Dev: 失敗/成功の結果
    Dev->>Review: 変更を提出
    Review-->>Dev: 修正要求
    Dev->>Plan: 進捗と判断ログを反映
    Dev->>Test: 再実行して収束

おわりに

AI駆動開発の成否は、モデル選定より運用設計で決まる。 仕様を先に固定し、テストで実装を縛り、短いループで観測と修正を回す。 この基本を崩さなければ、開発速度を上げても品質は落ちない。

This is an excerpt from B. Ackkerman's AI駆動開発を回す実践ガイド: SDD×TDDとフィードバック・ループ article. I highly recommend you give it a read!

Related Articles