この記事の目次
Claude Codeに任せられるテストの範囲
Claude Codeには、単体テストの生成、既存コードへのテスト追加、リグレッション確認用のテスト作成、E2Eテスト（画面操作を通しで検証するテスト）の土台づくりまで任せられる。ただしテストフレームワークの選定や運用方針そのものは、プロジェクト側が決めるべき領域である。
具体的にできる範囲を整理すると、次のようになる。
- 既存の関数やクラスに対して、正常系・異常系を含む単体テストを書かせる
- リファクタリング前後で振る舞いが変わっていないかを確認するリグレッションテストを追加させる
- テストが薄い既存ファイルに対して、不足しているケースを洗い出させたうえで補わせる
- E2Eテストのシナリオ骨格（ログインしてから特定の操作を行うまでの流れなど）を組ませる
Jest、Vitest、pytestといったフレームワーク自体は、指示すれば書ける。ただしどのフレームワークを使うか、どこまでカバレッジを求めるかといった方針は、生成AIではなくチームや個人開発者が決める判断であり、Claude Codeに委ねる領域ではない。基本的な操作に不安がある場合はClaude Codeの基本的な使い方を、指示の組み立て方に迷う場合はプロンプトの書き方の基本を先に確認しておくと、以降の内容が理解しやすくなる。
生成されたテストは何を確認してから使うべきか？
生成されたテストをそのまま使う前に確認すべきなのは、そのテストが「通ることを目的化していないか」という一点に集約される。実装の詳細をなぞっただけのテストは、コードが壊れても検知できない。
確認の軸として、次の5項目をチェックリスト代わりに使うとよい。
- アサーション（テストが検証する期待値の記述）が、実装の内部処理ではなく仕様そのものを検証しているか
- 境界値・異常系（空文字、上限値、想定外の入力など）が含まれているか
- モックが本物の依存関係を隠しすぎておらず、検証したい振る舞いが実際に動く経路を通っているか
- 「テストを通すこと」が目的化して、実装のバグに合わせてテスト側を書き換えていないか
- 既存のテスト命名規則やディレクトリ構造に沿っているか
なお、Claude CodeのPRレビュー機能とここで扱っている確認は別物である。PRレビュー機能は差分全体の妥当性を見る仕組みであり、その使い方はPRレビュー機能の使い方で詳しく解説している。本記事で扱っているのは、生成されたテストコード自体が検証として機能しているかという、より狭い範囲の確認である。
なぜ「テスト書いて」だけでは不十分なのか？
「テスト書いて」という曖昧な指示だけでは、何を検証すべきかが伝わらず、生成AIは「とりあえず通るテスト」を優先しやすい構造になる。検証したい仕様や、壊れたときに失敗してほしい条件を言語化しないと、実装の後追いになりがちである。
これは実測値の話ではなく、指示と出力の関係として一般的に整理できる構造である。抽象的な指示は解釈の幅が広いぶん、生成AIにとって「間違っていない」出力を作りやすい。テストの場合、その「間違っていない」出力とは、既存の実装をそのまま通すアサーションになりやすいということだ。
テスト固有に明示しておくとよい項目は、次の4つに絞られる。
- 境界値：どの値を上限・下限として扱うか
- 異常系：どんな入力やエラーを想定するか
- モック対象：どの依存関係を実際に呼ばずに置き換えるか
- 期待する失敗のさせ方：どんな条件で、どんな種類のエラーを返すべきか
指示文の組み立て方そのものはプロンプトの書き方の基本に譲るが、テストを依頼する際はこの4項目を先に自分の言葉で書き出してから指示に落とし込むと、生成されるアサーションの質が変わる。
CI・Hooksによるテスト自動実行の最小構成
生成したテストの価値は、書いた瞬間ではなく継続的に実行され続けることで発揮される。そのためにはプッシュ時にCIでテストを走らせる仕組みと、ローカルでの保存やコミットのタイミングでテストを起動する仕組みの、どちらか、あるいは両方を用意するのが最小構成になる。
CIとHooksは役割が異なるため、比較軸をそろえて整理しておく。
| 比較軸 | CI（例：GitHub Actions） | Hooks |
|---|---|---|
| 起動タイミング | リモートへのプッシュやプルリクエスト作成時 | ローカルでの保存・コミットなど、操作に連動 |
| 実行場所 | CIサーバー（self-hosted またはクラウド） | 開発者のローカル環境 |
| フィードバックの速さ | 数十秒〜数分後（環境構築やキュー待ちを含む） | ほぼ即時 |
| 向いている用途 | マージ前の最終確認、チーム全体での品質チェック | 書きながらの予防的チェック |
Hooksは「保存時・コミット時にテストを起動するトリガー」として捉えると使いどころが分かりやすい。設定の詳細な書き方はHooksの設定ガイドを、GitHub Actionsを使ったCI構築の詳細はGitHub Actions連携ガイドを、Gitの基本操作はGit操作ガイドを参照してほしい。まずはプッシュ時にテストを1本走らせるだけの最小構成から始め、通ることを確認してから対象を広げていくとよい。
CLAUDE.mdにテストのルールをどう書けば守られるのか？
CLAUDE.md（Claude Codeがプロジェクトごとに読み込む指示ファイル）にテストのルールを書く際は、使用フレームワーク、命名規則、モック方針、カバレッジ目標の基準という4点に絞ると、テスト生成の品質が安定しやすい。
- 使用フレームワーク：Jest、Vitest、pytestなど、どれを使うかを明記する
- 命名規則：
describeとitの書き方、ファイル名の末尾（.test.tsなど）を明記する - モック方針：どの層（外部API、DB、ファイルシステムなど）を原則モックするかを決めておく
- カバレッジ目標の基準：数値を上げすぎず、「新規追加コードには最低限の正常系・異常系を含める」程度の現実的な基準にとどめる
CLAUDE.mdの書き方全般や、記述内容をどう運用に落とし込むかについてはCLAUDE.mdの書き方ガイドとClaude Codeの運用ルールにまとめている。ここで挙げた4点は、その中でもテスト固有に書いておくべき中身に限定した内容である。
AIが生成した成果物を安全に運用へ乗せる設計
ここで紹介するのは、テストコード生成そのものの実例ではない。当サイトのブログ記事生成エンジンが、Claude Codeの生成物を安全にパイプラインへ通すために採用している設計であり、テストの自動実行にも類推できる考え方として紹介する。
このエンジンでは、記事生成の処理をS0b-research、S1-outline、S2-outline-review、S3-write、S4-write-review、S5-revise、S6-l1、S7-gateの8段階に分割している。生成物を一気通貫で通すのではなく、段階ごとに検証点を設ける発想である。最終段階の品質ゲートは、intent、primary、news、unique、diversity、voiceという6軸で判定し、この軸の集合が一致しない結果は受け付けない仕組みになっている。「何を満たせば合格とするか」を先に軸として明文化しておくことが、判定を属人化させないポイントである。
再試行の設計にも一貫した上限がある。決定論的なlint違反に対する改稿は最大2回、生成テキストがスキーマに合わないケースの再試行は最初の呼び出し後に1回だけと決まっており、無限にリトライさせない。さらに失敗の種類によって対応を分けており、OAuthエラーは再試行せず即座に失敗として扱う一方で、クラッシュや不正なJSON、タイムアウトは再試行の対象にしている。処理が止まらない場合の強制終了も数値で決めており、既定のタイムアウトは300,000ミリ秒（5分）で、タイムアウト時にはまずSIGTERM（穏当な終了要求）を送り、1,000ミリ秒経っても終わらなければSIGKILL（強制終了）を送る。繰り返し失敗する対象については、直近の隔離から72時間は再試行対象から外し、通算3回隔離されると恒久的に除外する仕組みも組み込んでいる。
これらの設計原則は、テストの自動実行にもそのまま応用できる。
| 設計原則 | このエンジンでの実装 | テスト自動化への応用 |
|---|---|---|
| 段階分割して検証点を作る | 8段階の処理識別子ごとに結果を確認する | 単体テスト→結合テスト→E2Eと、まとめて実行せず段階ごとに結果を見る |
| 合格基準を軸で明文化する | 最終ゲートは6軸の判定結果がそろわないと受け付けない | 「通ること」ではなく、カバーすべき観点を先に列挙してから合否を決める |
| リトライに上限を切る | 改稿は最大2回、スキーマ不正の出力は1回だけ再試行 | フレーキーテスト（不安定に失敗するテスト）の再実行回数に上限を設ける |
| 失敗の種類で対応を分ける | OAuthエラーは即失敗、クラッシュ・不正JSON・タイムアウトは再試行 | 環境起因の失敗とロジック起因の失敗を区別し、再試行すべきかを分岐する |
| 強制終了の基準を数値で持つ | 既定タイムアウト300,000ミリ秒、SIGTERM後1,000ミリ秒でSIGKILL | 止まらないテストプロセスをいつ強制終了するかをあらかじめ決めておく |
| 繰り返し失敗するものを隔離する | 隔離対象は72時間再試行せず、通算3回で恒久除外 | 恒常的に失敗するテストを「既知の不安定」として隔離し、CI全体の信頼性を守る |
個人開発とチーム開発で気をつける点は違うのか？
個人開発では、生成されたテストを自分で確認して素早く回せば足りることが多いが、チーム開発では「誰が生成テストをレビューし、CIのマージゲートに誰の承認を必要とするか」という合意を先に決めておく必要がある。
個人開発の場合、判断者と実行者が同じであるため、前述のチェックリストを自分の中で回すだけでよい。テストが弱くても、気づいた時点で自分で直せる。
一方でチーム開発の場合、Claude Codeが生成したテストを誰も精査しないまま通ってしまうと、レビュー対象がコード本体からテストコードへとずれてしまう危険がある。生成テストのレビュー担当を明確にし、CIのマージゲートでどのチェックが必須で、どのチェックが警告どまりなのかを事前に合意しておくと、この問題を避けやすい。運用ルール全体の考え方はClaude Codeの運用ルールに整理している。
まとめ
Claude Codeには単体テストの生成やリグレッション確認を任せられるが、フレームワークの選定や合格基準の設計は人間側の判断として残る。生成されたテストは、実装の詳細ではなく仕様を検証しているか、境界値や異常系が含まれているかといった観点で確認し、CIやHooksへの組み込みは、まずプッシュ時にテストを1本走らせる最小構成から始めるとよい。
こうした型を知ることと、自分のプロジェクトで実際に定着させることの間には距離がある。プロンプトの指示をどう調整するか、CIのゲートをどこまで厳しくするかは、書籍や記事を読むだけでは身につきにくく、実際に手を動かしながら試行錯誤する時間が必要になる。その試行錯誤を独りで抱え続けるより、継続的に手を動かしながら学べる場を使う選択肢もある。月額1,980円から参加できる学習コミュニティ「AI駆動ラボ」では、Claude Codeを実務で使いこなすための学習を、自分の手で試しながら進めていける。