このシリーズについて
ハーネスエンジニアリング実践シリーズでは、Claude Code の Skills 機能を使って TDD ワークフローを自動化する方法を紹介しています。前回（Part 3）で RED→GREEN フェーズの品質ゲートを紹介しました。今回は時系列的にはその手前、テストを書く前のコードレビュー自動化の話です。
テスト書く前にやることがある
TDD でまず「テスト書こう」と思うのは自然なんですが、少し待ってください。
AI 駆動で開発していると、1 つのファイルに何でもかんでも詰め込んでいきがちです。「ここに追加して」「この機能も足して」と指示を繰り返すうちに、あっという間に数千行のファイルができあがる。どこにどの機能があるのか分からない、触ると別の場所が壊れる――そういう状態でテストを書いても意味がありません。テスト自体が低品質コードに密結合して、あとからリファクタした瞬間に全部壊れます。
自分の /tdd スキルでは、RED フェーズ（テスト作成）に入る前に Gate 3: コードレビュー という関門を設けています。ここでファイルの肥大化チェック、ソースコードレビュー、セキュリティレビュー、DB レビューを自動で回して、テスト対象コードの品質を先に担保します。
今回はこの Gate 3 を担う /tdd-code-review スキル（SKILL.md 117 行）の中身を全部見せます。
Gate 3 の評価項目（8 項目 x 3 点 = 満点 24 点）
Evaluator が採点する全項目がこれです。
| # | 評価項目 | 配点 | 評価基準 |
|---|---|---|---|
| 1 |
[CRITICAL] ファイル行数チェック |
3 | 300行超のファイルがない、または /decompose で分割済み |
| 2 | 責務分離 | 3 | 1ファイルに複数の責務が混在していないか |
| 3 | ビジネスロジックの配置 | 3 | コンポーネント内にロジックが直書きされていないか |
| 4 |
[CRITICAL] Critical指摘ゼロ |
3 | レビュースキルの Critical 指摘が全て解消されているか |
| 5 | レビュースキルの適切な選択 | 3 | 変更パスに応じた正しいスキルが呼ばれているか |
| 6 |
[CRITICAL] /security-review 指摘ゼロ |
3 | XSS / SQLi / CSRF 等の脆弱性がないか |
| 7 | RLSポリシー確認（DB変更時） | 3 | tenant_id による行レベルセキュリティが適切か |
| 8 | インデックス確認（DB変更時） | 3 | FK列・検索条件列にインデックスがあるか |
合格ライン: 80%。DB 変更がなければ項目 7・8 は対象外で満点 18 点になります。
ポイントは [CRITICAL] がついた 3 項目。これらが 0 点だと、他が全部満点でもスコアに関係なく 即 FAIL です。ファイルが肥大してる、Critical 指摘が残ってる、セキュリティホールがある――どれか 1 つでもあったらテストフェーズに進めません。
自動判定の仕組み: パスでレビュースキルを呼び分ける
Gate 3 の核になるのが、変更ファイルのパスに応じたレビュースキルの自動選択です。SKILL.md にはこう書いてあります。
## 2. ソースコードレビュー
変更ファイルのパスに応じて、該当するレビュースキルを実行する。
| 変更パス | レビュースキル | 観点 |
|----------|--------------|------|
| `src/app/(authenticated)/**/*.tsx` | `/review-vercel-frontend` | UI/UX品質、React/Next.jsパフォーマンス、Webガイドライン準拠 |
| `src/components/**/*.tsx` | `/review-vercel-frontend` | 同上 |
| `src/app/api/**/*.ts` | `/review-python-backend` | API設計、セキュリティ、入力バリデーション、エラーハンドリング |
| `src/lib/**/*.ts` | `/review-python-backend` | コード品質、セキュリティパターン |
つまり .tsx ファイルを触ったら /review-vercel-frontend が走り、.ts（API / lib）を触ったら /review-python-backend が走ります。開発者が「どっちのレビュースキルを使うか」を考える必要がありません。パスだけで決まります。
ちなみにこれらのレビュースキルは、公開されているベストプラクティス系スキルを組み合わせて自分で作ったものです。たとえば /review-vercel-frontend は ui-ux-pro-max（UI/UX 設計）、vercel-react-best-practices（React/Next.js パフォーマンス）、web-design-guidelines（Web インターフェースガイドライン）の 3 つの観点を 1 つのスキルに統合しています。/review-python-backend も同様に、python-backend と fastapi-async-patterns を束ねたものです。公開スキルのルールやベストプラクティスをそのまま使うのではなく、自分のプロジェクトに合わせて 1 つのレビュースキルとしてカスタマイズしているわけです。
DB 関連の変更（supabase/migrations/**）があれば、さらに supabase-postgres-best-practices の観点で RLS ポリシーとインデックスをチェックします。
## 3. DBレビュー
| 変更パス | チェック観点 |
|----------|------------|
| `supabase/migrations/**` | スキーマ設計、インデックス、RLSポリシー、パフォーマンス |
| `src/lib/types.ts` | 型定義とDBスキーマの整合性 |
| `src/lib/database.types.ts` | Supabase生成型の最新性 |
全部パスベースなので、人間の判断が不要です。ここが「自動で回す」の本質ですね。
ファイル肥大化チェック: 300 行超は /decompose に委譲
Gate 3 で最初にやるのが、ファイルサイズのチェックです。
## 1. ファイル肥大化・モジュール分割チェック
**自動判定基準:**
- 変更対象ファイルが **300行超** → `/decompose` でモジュール分割を検討
- 1ファイルに **複数の責務**（API呼び出し + UI + バリデーション等）が混在 → 分割を推奨
- コンポーネント内に **ビジネスロジック** が直接書かれている → `src/lib/` への切り出しを推奨
**手順:**
1. `wc -l` で変更対象ファイルの行数を確認
2. 300行超のファイルがあれば `/decompose` を呼び出して分割を実施
3. 分割後にテストを書く（分割前のテストは書かない）
wc -l で行数を数えます。300 行超えてたら /decompose スキルに委譲してモジュール分割します。分割前のコードに対してテストは書きません。これが鉄則です。
/decompose は肥大化したファイルをモジュール単位・機能単位・コンポーネント単位に分割する専用スキルです。AI 駆動開発で膨れ上がった「全部入りファイル」を、責務ごとに 300 行以下のファイルへばらしてくれます。分割の粒度は機械的な行数ではなく、責務の境界で決まります。
なぜ 300 行か？ 経験的に、300 行を超えたファイルは大体 2 つ以上の責務を持っています。テストを書こうとすると「このファイルの何をテストするのか」が曖昧になって、結局テストが甘くなります。先に分割しておけば、モジュール単位で集中したテストが書けます。
セキュリティレビュー: /security-review を全ファイルに
構造チェックとソースコードレビューに加えて、全変更ファイルに /security-review を走らせます。
## 4. セキュリティレビュー（`/security-review`）
**検出対象:**
- インジェクション（XSS、SQLi、コマンドインジェクション）
- 認証・認可の不備（認証バイパス、権限昇格）
- データ露出（PII漏洩、シークレットのハードコード、ログへの機密情報出力）
- CSRF / CORS 設定の不備
- RLS ポリシーの欠落・不適切な設定
**手順:**
1. `/security-review` を実行
2. 指摘があれば修正してから Gate 3 評価に進む
3. Critical 指摘が残っている場合、Gate 3 は自動 FAIL
これはセキュリティチェック用のスキルです。指摘が残ったまま Gate 3 に進もうとしても、[CRITICAL] /security-review 指摘ゼロ が 0 点になって自動で弾かれます。
スキップ条件: なんでもかんでもレビューしない
Gate 3 には明確なスキップ条件も定義してあります。
## 5. スキップ条件
以下の場合はこのスキルをスキップする:
- テストコードのみの変更（`tests/**`）
- ドキュメントのみの変更（`docs/**`）
- 設定ファイルのみの変更（`*.config.*`）
- ユーザーが明示的にスキップを指示した場合
テストファイルだけ直した、ドキュメントだけ更新した――そういうときにわざわざコードレビューゲートを通す意味はありません。無駄な工程を省くのも自動化の一部です。
品質レポートの実例: PASS / CONDITIONAL / FAIL
Gate 3 を通過すると、Evaluator が以下のフォーマットでレポートを出します。3 パターンの具体例を載せておきます。
PASS の例（スコア 89%）
## Quality Gate Report: Gate 3 - コードレビュー
| # | 評価項目 | 点数 | コメント |
|---|---------|------|---------|
| 1 | [CRITICAL] ファイル行数チェック | 3/3 | 全ファイル300行以下 |
| 2 | 責務分離 | 3/3 | API層・UI層・ロジック層が適切に分離 |
| 3 | ビジネスロジックの配置 | 2/3 | 1箇所 utils に寄せたほうがよい計算ロジックあり |
| 4 | [CRITICAL] Critical指摘ゼロ | 3/3 | レビュー指摘なし |
| 5 | レビュースキルの適切な選択 | 3/3 | .tsx → /review-vercel-frontend を正しく選択 |
| 6 | [CRITICAL] /security-review 指摘ゼロ | 2/3 | 軽微な指摘1件（Critical以外）、修正推奨 |
**スコア**: 16 / 18（89%）
**判定**: PASS
**Critical違反**: なし
### 次のアクション
- PASS → Gate 4（RED フェーズ）へ進む
CONDITIONAL の例（スコア 67%）
## Quality Gate Report: Gate 3 - コードレビュー
| # | 評価項目 | 点数 | コメント |
|---|---------|------|---------|
| 1 | [CRITICAL] ファイル行数チェック | 3/3 | 全ファイル300行以下 |
| 2 | 責務分離 | 1/3 | UserDashboard.tsx に API呼び出しとUIが混在 |
| 3 | ビジネスロジックの配置 | 1/3 | コンポーネント内に集計ロジックが直書き |
| 4 | [CRITICAL] Critical指摘ゼロ | 3/3 | Critical指摘なし |
| 5 | レビュースキルの適切な選択 | 2/3 | 正しいスキルだがレビュー観点が一部不足 |
| 6 | [CRITICAL] /security-review 指摘ゼロ | 2/3 | 軽微1件 |
**スコア**: 12 / 18（67%）
**判定**: CONDITIONAL
**Critical違反**: なし
### 指摘事項
- [ ] UserDashboard.tsx: API呼び出しを custom hook に切り出す
- [ ] 集計ロジックを src/lib/analytics.ts に移動する
### 次のアクション
- CONDITIONAL → 指摘2箇所を修正後、再評価（最大2回）
FAIL の例（Critical 違反）
## Quality Gate Report: Gate 3 - コードレビュー
| # | 評価項目 | 点数 | コメント |
|---|---------|------|---------|
| 1 | [CRITICAL] ファイル行数チェック | 0/3 | OrderForm.tsx が 487行。/decompose 未実施 |
| 2 | 責務分離 | 0/3 | 1ファイルにフォーム/バリデーション/API/状態管理が全部入り |
| 3 | ビジネスロジックの配置 | 1/3 | 価格計算ロジックがコンポーネント内 |
| 4 | [CRITICAL] Critical指摘ゼロ | 3/3 | Critical指摘なし |
| 5 | レビュースキルの適切な選択 | 3/3 | /review-vercel-frontend を正しく選択 |
| 6 | [CRITICAL] /security-review 指摘ゼロ | 3/3 | 指摘なし |
**スコア**: 10 / 18（56%）
**判定**: FAIL
**Critical違反**: 項目1（ファイル行数チェック）が 0点
### 指摘事項
- [ ] OrderForm.tsx を /decompose で分割する（487行 → 目標300行以下）
- [ ] 分割後に責務を整理してから再レビュー
### 次のアクション
- FAIL → Planner に差し戻し。/decompose 実施後、Gate 3 を最初からやり直し
CONDITIONAL なら指摘箇所だけ直して再評価（最大 2 回）。FAIL なら Planner まで差し戻して、構造から立て直します。2 回修正しても CONDITIONAL のままなら FAIL に格上げされるので、だらだら直し続けることもありません。
自分で作るなら
自分のプロジェクトに導入するなら、こんな順番がいいと思います。
1. まず「行数チェック」だけ入れる
いきなり 8 項目やろうとすると大変です。wc -l で行数を見て、超えたら警告出す――これだけでもテスト前の品質は上がります。閾値はプロジェクトに合わせて 200 行でも 400 行でも構いません。
2. パスベースのスキル振り分けを定義する
自分のプロジェクトのディレクトリ構成に合わせて「このパスならこのレビュー観点」を表にします。Rails なら app/controllers/ → API レビュー、app/views/ → フロントレビュー、みたいな感じです。
3. Critical 項目を 1 つだけ決める
全部 Critical にすると何も通らなくなります。「これだけは絶対ゼロにしたい」という 1 項目（たとえばセキュリティ指摘ゼロ）から始めるのがおすすめです。
4. スキップ条件を忘れずに
テストだけの変更、ドキュメントだけの変更にまでレビューゲートを通すと、開発速度が落ちます。スキップ条件を書いておくのを忘れがちですが、これがないと地味にストレスになります。
次回予告
テスト対象のコードがきれいなら、テストもきれいに書けます。Gate 3 はそのための関門です。
次回（Part 4: Gate 6 --- リファクタリングの自動化と品質チェック）では、GREEN でテストが通った後のリファクタフェーズを扱います。「やらないこと」の明示、/decompose による分割、スコープ逸脱検知など。
ハーネスエンジニアリング実践シリーズ（全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つの品質ゲートを回す