AI駆動開発の品質問題をTDD×9つの品質ゲートで解決する

TDD（テスト駆動開発）とは

TDD（Test-Driven Development）は、テストコードを先に書いて、そのテストが通るように実装を進める開発手法です。RED（失敗テストを書く）→ GREEN（テストを通す最小実装）→ REFACTOR（きれいにする）の3ステップを繰り返します。

当社（JQIT）では、AIソリューション開発のワークフロー標準としてTDDを採用しています。この記事では、そのワークフローの一部を紹介します。

AI駆動開発の品質問題

Claude Code でAI駆動開発すると、「なんかそれっぽく動くもの」は驚くほど速くできます。でも品質が安定しません。テストが先に書かれてないのに実装が始まったり、レビューをすっ飛ばしてリファクタに入ったり、動いてるように見えて実は中身がバグだらけだったり。

出力を毎回チェックする自分の負荷がどんどん増えていって、「AIにやらせたら楽になる」はずが逆に忙しくなりました。

Anthropic公式エンジニアリングブログに「Harness design for long-running apps」という記事があります。AIアプリケーションでは ハーネス（外枠）の設計 が品質を左右するという話です。この「工程ごとにチェックポイントを設けて品質を担保する」という考え方を参考に、TDDワークフロー用のハーネスを設計しました。

ハーネスの枠組みはAnthropicの記事から着想を得ていますが、中身のワークフロー――9つの品質ゲート、5つのサブスキル、各Gateのチェック項目――はすべてオリジナルで組んだものです。

オーケストレーターという考え方

Claude Code には SKILL.md というファイルでエージェントの振る舞いを定義する仕組みがあります。僕はここに オーケストレーター を作りました。指揮者のようなもので、自分では手を動かさず、専門のサブスキルに仕事を振ります。

核になるのは3つのロール定義。SKILL.md にこう書いてあります。

Planner が「何をやるか」を決め、Generator が「実際にやる」、Evaluator が「ちゃんとできてるか」を判定します。この3つが分離していることで、「実装した本人がレビューして OK を出す」みたいな手抜きが構造的に起きなくなります。

ワークフロー全体はこうなっています。

ピンク色のノードがサブスキルへの委譲ポイントです。オーケストレーター自身が処理するのは Section 1, 2, 6, 8 だけで、重い処理は全部サブスキルに投げています。

5つのサブスキル — 各工程で何をチェックするか

このワークフローの価値は「各工程で何を見るか」が具体的に定義されていることです。サブスキル5本それぞれの役割とチェック内容を紹介します。

/tdd-code-review（Gate 3: テスト前コードレビュー）

テストを書く前にコードの品質を確認します。レビュー対象はソースコード・DB設計・セキュリティの3軸。

• ファイル肥大化チェック: wc -l で300行超のファイルを検出 → /decompose で自動分割
• ソースコードレビュー: パスパターンでフロント（/review-vercel-frontend）かバックエンド（/review-python-backend）のレビュースキルを自動選択
• DBレビュー: RLSポリシーの漏れ、インデックスの過不足を確認
• セキュリティレビュー: XSS・SQLi・CSRF・認証漏れを /security-review で検出

/tdd-test-writer（Gate 4-5: RED→GREEN）

TDDの核心。失敗テストを先に書き（RED）、それを通す最小実装を書く（GREEN）。

• Gate 4（RED）のCritical: テストが実際に失敗していること。「おそらく失敗する」は禁止、実行ログ必須
• Gate 5（GREEN）のCritical: 新テストがパスしていること＋既存テストを壊していないこと
• テストテンプレート3種（単体 / API統合 / E2E）を references/test-templates.md に定義し、Generator がそれに沿って書く

/tdd-refactor（Gate 6: リファクタリング）

GREEN後のリファクタフェーズ。「何をやるか」と同じくらい「何をやらないか」を定義しています。

• やること: 重複除去、命名改善、関数分割、/simplify による品質チェック
• やらないこと: 新機能追加、パフォーマンス最適化、テストケース追加（次のREDフェーズの仕事）
• Gate 6のCritical: リファクタ後も全テストがパスしていること

/tdd-ui-review（Gate 7: UI/UXレビュー）

E2Eテストがある場合のみ発動。Playwright MCPでスクショを撮り、3段階の優先度でUIを評価します。

• Priority 1（CRITICAL）: AI臭さゼロ・テンプレ感排除・デザインシステム統一
• Priority 2: レイアウト崩れ・レスポンシブ・コントラスト比
• Priority 3: UX導線・操作ステップ数・エラー時ガイド
• スクショ→評価→修正→再スクショのループを最大3ラウンド

/tdd-doc-sync（Gate 9: ドキュメント同期）

TDDサイクルの最終ゲート。コード変更から同期すべきドキュメントを自動特定します。

• マッピングテーブル: src/app/api/** → api-reference.md、supabase/migrations/** → db-schema.md など
• /doc-condenser でAI臭い文章（「シームレスに統合」等）を自動検出・修正
• リファクタのみ・CSSのみなど、同期不要なケースはGate 9自体をスキップ

品質ゲートシステム：0-3点スコアリング

ただ、サブスキルに投げっぱなしだと品質がバラつきます。そこで入れたのが 品質ゲートシステム です。

ルールはシンプルです。

• 採点: 各項目 0-3点（Missing / Partial / Good / Excellent）
• 80点以上 = PASS → 次工程へ
• 60-79点 = CONDITIONAL → 指摘箇所のみ修正して再評価（最大2回）
• 59点以下 = FAIL → Planner に差し戻して工程やり直し
• Critical項目が0点 → スコアに関係なく FAIL

各項目が 0〜3点で、合計スコアの 80% 以上なら合格です。ポイントは Critical 項目 の存在で、これが 0点だとスコアが何点でも即 FAIL になります。たとえば Gate 4（RED フェーズ）なら「テストが実際に失敗している」が Critical。テストが通ってしまっているのに RED フェーズ通過、なんてことは許されません。

各ゲート通過時に Evaluator が出力するレポートはこんな形式です。

Quality Gate Report: Gate X - [ゲート名]

#	評価項目	点数	コメント
1	[項目名]	X/3	[具体的な評価理由]
2	...	...	...

スコア: XX / YY（ZZ%）
判定: PASS / CONDITIONAL / FAIL
Critical違反: なし / [違反項目]

指摘事項（CONDITIONAL/FAIL時）

• [修正が必要な具体的指摘]

次のアクション

• PASS → Gate X+1 へ進む
• CONDITIONAL → [修正対象] を修正後、再評価
• FAIL → [差し戻し先] から再実行

CONDITIONAL の場合、修正→再評価のループは最大2回まで。2回やってダメならFAILに格上げされて、Planner まで差し戻されます。「何回やっても通らない」という無限ループは起きません。

テスト種別の自動判定

オーケストレーターのもう1つの仕事が、変更されたファイルのパスから自動でテスト種別を判定することです。

git diff --name-only で変更ファイルを取得して、パスパターンでマッチングします。E2E 判定のときは POM（Page Object Model）が tests/page-objects/ にあるかも確認します。

判定手順は4ステップです。

1. 変更ファイルのパスをパターンマッチ
2. E2E判定時: POM が tests/page-objects/ に存在するか確認
3. 既存テストがあれば更新、なければ新規作成
4. ユーザーに判定結果を報告し、確認を取る

最後にユーザー確認を入れているのがミソです。自動判定を信用しすぎて間違ったテスト種別で走り出すのを防ぎます。

テストの3層はこう配置されています。

tests/
├── unit/          # 単体テスト（Vitest）
├── api/           # API統合テスト（Vitest）
├── e2e/           # E2Eテスト（Playwright）
├── page-objects/  # POM（E2E用セレクタ管理）
├── manifests/     # 画面マニフェスト
└── helpers/       # テストヘルパー

スキル構成の全体像

最終的なファイル構成と行数はこうなりました。

~/.claude/skills/tdd/
├── SKILL.md              (322行)  ← オーケストレーター本体
└── references/
    ├── quality-gates.md   (314行)  ← 品質ゲート定義
    ├── test-templates.md            ← テストテンプレート
    ├── scenario-design.md           ← シナリオ設計
    ├── test-data.md                 ← テストデータ
    ├── visual-review-checklist.md   ← 目視確認リスト
    └── flaky-test-patterns.md       ← フレーキーテスト対策

~/.claude/skills/tdd-code-review/SKILL.md    (117行)
~/.claude/skills/tdd-test-writer/SKILL.md    (163行)
~/.claude/skills/tdd-refactor/SKILL.md       (82行)
~/.claude/skills/tdd-ui-review/SKILL.md      (154行)
~/.claude/skills/tdd-doc-sync/SKILL.md       (113行)

合わせて 1,549行。多いと感じるかもしれませんが、これで Gate 1〜9 の品質ゲートが全部回ります。人間が毎回チェックリストを見ながらレビューする手間を考えたら、1,549行のMarkdownで自動化できるなら安い投資だと思います。

自分で作るなら

この記事を読んで「自分のプロジェクトでも試したい」と思ったら、SKILL.md にまずこれだけ書いて /tdd で走らせてみてほしい。

Agent Roles

Quality Gates

• 各項目 0-3点、合計の80%以上で PASS
• Critical項目が0点 → 即 FAIL

いきなり 9 Gate 全部作る必要はありません。最初は Gate 4-5（RED→GREEN）だけでも十分動きます。テスト種別判定のパスパターンは自分のプロジェクト構成に合わせて書き換えてください。品質ゲートの評価項目は3〜4項目から始めて、運用しながら増やしていくのが現実的です。

次回予告

1,549行の Markdown で 9 Gate。やってることはシンプルで、「誰が何をやるか決めて、やったら点数つけて、合格なら次へ」を繰り返しているだけです。少なくとも「テスト書いてないのに実装が始まる」は Gate 4 の Critical 項目で構造的にブロックされるようになりましたし、差し戻しは起きますが、気づかずスルーされることはなくなりました。

次回（Part 3）は、このシリーズの核心である RED→GREEN フェーズ に踏み込みます。「失敗テストなしにコードを一行たりとも書かない」という Iron Law を SKILL.md にどう実装したか、Gate 4-5 の評価項目、そしてテストテンプレート 3種（単体 / API統合 / E2E）を全部載せる予定です。

ハーネスエンジニアリング実践シリーズ（全8部）
Part 1: スキルの階層構造で開発を自動化する ← 今ここ
Part 2: Gate 3 — テスト前にコードレビューを自動で回す
Part 3: Gate 4-5 — RED→GREENを自動で回す
Part 4: Gate 6 — リファクタリングの自動化と品質チェック
Part 5: Gate 7 — スクショでUI/UXを自動レビューする
Part 6: Gate 9 — ドキュメントをコードに自動追従させる
Part 7: 実践編 — ハーネスでAPIダッシュボードを作ってみた
Part 8: 全体像 — スキル1,549行で9つの品質ゲートを回す