この記事の目次
Claude Code にテストを任せるときの要点は、テストを「書かせる」ことより、テストを「実行させて結果を読ませる」ことにあります。公式のベストプラクティスは、テストやビルドのように合否を返すチェックを渡せば、Claude Code が作業、実行、結果の確認、修正を自分で繰り返すと説明しています。以下、指示の書き方、CLAUDE.md、/goal と Stop hook の使い分け、CI での実行、動かないときの確認点を公式の記述に沿って整理します。
Claude Code テストで最初に押さえることは何か？
公式のベストプラクティス（Best practices）は、テスト、ビルド、スクリーンショットの比較といった「実行できるチェック」を渡すよう勧め、これが見守る作業と任せて離れられる作業の差になると書いています。Claude Code は作業が終わったように見えた時点で止まります。合否を返すチェックがなければ「終わったように見える」以外の合図がなく、間違いはすべて人が気づくまで残ります。逆にテストのように合否判定が出るものを渡せば、Claude Code は作業し、チェックを実行し、結果を読み、通るまで繰り返します。
もう1つの基本は、成功を宣言させるのではなく証拠を出させることです。公式は、テストの出力や、実行したコマンドとその戻り値を示させるよう勧めています。証拠を読むほうが自分で検証をやり直すより速く、見ていなかったセッションでも確認できるためです。
テストを書かせる指示はどう書けばよいか？
「テスト書いて」だけでは、何を検証すべきかが伝わりません。公式の指示例（Best practices）は、次の3点を具体的にしています。
- 検証対象のファイルとシナリオ、テストの好み。例として、ログアウト状態のユーザーというエッジケースを指定し、モックを避けるよう書き添えた指示が挙げられています
- 期待値となる入出力。メールアドレス検証の関数なら、正しい例と誤った例をテストケースとして列挙し、実装後にテストを実行させます
- バグ修正の順序。症状と疑わしい場所を伝え、まず問題を再現する失敗テストを書かせてから修正させます
テストが足りない既存コードに追加する場合は、公式の「Common workflows」にある4段階の流れがそのまま使えます。
find functions in NotificationsService.swift that are not covered by tests
add tests for the notification service
add test cases for edge conditions in the notification service
run the new tests and fix any failures未テストの関数を特定し、足場となるテストを作り、エッジケースを加え、最後に実行して失敗を直させる順番です。公式によると、Claude Code は既存のテストファイルを見て、スタイル、フレームワーク、アサーションの書き方を合わせます。見落としがちなエラー条件、境界値、想定外の入力を洗い出させることもできます。
指示文全体の組み立て方はプロンプトの書き方の基本で扱っています。
生成されたテストはどう確かめればよいか？
テストが通っていても、そのテストが検証として働いているとは限りません。公式ドキュメントからは、確認の手段として次の3つが読み取れます。
1つ目は、書く役と確かめる役を分けることです。公式（Best practices）は、直前に書いたコードに引っ張られない新しいコンテキストのほうがレビューに向くとし、1つの Claude にテストを書かせ、別の Claude にそれを通すコードを書かせるやり方を挙げています。
2つ目は、差分を新しいサブエージェントに見せることです。同梱の /code-review スキルは、現在の差分のバグを新しいサブエージェントで確認します。計画と照らし合わせたいときは、レビューの指示を自分で書きます。公式の例は、計画書の要件がすべて実装されているか、列挙したエッジケースにテストがあるか、作業範囲外が変わっていないかを確認させるものです。
Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.ただし公式は、指摘を全部追うと起こりえないケースのテストのような過剰な実装が増えるとして、正しさや要件に関わるテスト項目の不足だけを挙げさせるよう勧めています。
3つ目は、テストの出力を本筋の会話に流し込まないことです。テスト実行は出力が多く、コンテキストを大きく使います。公式（Subagents）は、テスト実行をサブエージェントに任せ、失敗したテストとエラーメッセージだけを返させる指示を例に挙げています。
Use a subagent to run the test suite and report only the failing tests with their error messagesプルリクエスト単位のレビュー機能はClaude Code のコードレビューの使い方を、サブエージェントの作り方はサブエージェントの解説を参照してください。
CLAUDE.md にはテストについて何を書けばよいか？
公式のベストプラクティス（Best practices）は、CLAUDE.md に含めるべきものとして「テストの手順と、使うテストランナー」を挙げています。例として示されている CLAUDE.md には、性能のためにテストスイート全体ではなく単一のテストを優先して実行する、という1行があります。
# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance書き方で効くのは具体性です。公式（Memory）は、CLAUDE.md は強制される設定ではなくコンテキストとして扱われるため、確かめられる程度に具体的に書くよう求めています。「変更をテストする」ではなく「コミット前に npm test を実行する」と書く、という対比が示されています。
置き場所と確認方法も公式に書かれています。
- プロジェクトの CLAUDE.md は
./CLAUDE.mdか./.claude/CLAUDE.mdに置き、ビルドとテストのコマンドなどチーム共通の指示を書く /initを実行すると、コードベースを解析してビルドコマンドやテスト手順を含む初版を作る- 読み込まれたかは
/contextで確認する - テストの規約が長くなるなら、
.claude/rules/にtesting.mdのようなトピック別ファイルとして分けられる。pathsを指定したルールは、一致するファイルを Read、Write、Edit したときに読み込まれる
CLAUDE.md は毎回読み込まれるので、広く当てはまることだけを書くよう公式は勧めています。書き方全般はCLAUDE.md の書き方ガイドにまとめています。
テストが通るまで作業を続けさせるにはどうするか？
公式のベストプラクティス（Best practices）は、チェックで停止をどれだけ強く縛るかを4段階で示しています。
| 段階 | 仕組み | 向いている場面 |
|---|---|---|
| 1つのプロンプト内 | 指示の中でテストを実行させ、通るまで直させる | どのタスクでもすぐ使える |
| セッション全体 | /goal に完了条件を設定する |
1つのセッションで大きめの作業を任せる |
| 決定的なゲート | Stop hook がスクリプトでチェックを実行し、通るまでターンを終わらせない | 設定したスコープの全セッションに効かせる |
| 別の目による確認 | 検証用のサブエージェントなどが結果の反証を試みる | 作業した本人に採点させたくない |
公式は、プロンプト版はどのタスクにも今日から使え、人がいなくても正しく終わらせられるのは /goal と Stop hook だと説明しています。
/goal で完了条件を渡す
/goal は完了条件を設定するコマンドです。各ターンの後に別のモデルが条件を満たしたかを判定し、未達なら Claude Code は次のターンを始めます。公式（Goal）の例は次のとおりです。
/goal all tests in test/auth pass and the lint step is clean条件の書き方には注意点があります。判定役のモデルは自分でコマンドを実行したりファイルを読んだりせず、会話に出てきた内容をもとに判断します。そのため「test/auth のテストがすべて通る」のように、Claude Code がテストを実行した結果が会話に残る形の条件にします。公式は、良い条件の要素として、測れる終了状態、npm test が 0 で終わるといった確認方法、「他のテストファイルは変更しない」のような守るべき制約を挙げています。
条件は最大4,000字で、or stop after 20 turns のようにターン数や時間の上限を含めて実行時間を区切れます。/goal は権限モードを変えないため、Manual モードでは、設定で既に許可されていないツール呼び出し（テストコマンドを含む）の前に確認が入ります。途中でやめるときは /goal clear を実行します。使い方の詳細は/goal の解説を参照してください。
Stop hook でテストをゲートにする
Stop hook は、メインのエージェントが応答を終えたときに走るフックです（公式: Hooks reference）。ユーザーが割り込んで止めた場合は走りません。Stop イベントでフックが終了コード 2 を返すと停止が取り消され、会話が続きます。このとき stderr に書いた内容が、作業を続ける理由として Claude Code に渡ります。なお PostToolUse イベントは終了コード 2 でもブロックできず、stderr が Claude Code に示されるだけです。テストを停止のゲートにするなら Stop を使います。
公式のフックガイド（Hooks guide）には、テストが通るまで停止させない agent 型の例があります。
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "agent",
"prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
"timeout": 120
}
]
}
]
}
}agent 型は、ファイルを読んだりコマンドを実行したりできるサブエージェントを起動して判定します。ただし公式は agent 型を実験的な機能としており、本番の運用には command 型を勧めています。既定のタイムアウトは agent 型が60秒、command 型が多くのイベントで600秒です。
Hooks の設定方法そのものはHooks の設定ガイドで扱っています。
Stop hook が止まらない・動かないときはどこを見るか？
テスト用の Stop hook で起きやすい症状と、公式のトラブルシューティング（Hooks guide）にある確認点をまとめます。
Claude Code が止まらず、最後に警告が出て終わる。 Stop hook が続けてブロックしすぎた状態です。公式によると、Claude Code はツール呼び出しを挟まずに8回連続でブロックされると Stop hook を上書きして終了します。カウントは Claude Code がツールを呼ぶたびにリセットされます。フックのスクリプトでは、入力 JSON の stop_hook_active が true なら早めに終了させます。
#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0 # Allow Claude to stop
fi
# ... rest of your hook logic収束に8回より多く必要な正当な理由があるなら、環境変数 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP で上限を引き上げられます。
フックが一度も発火しない。 /hooks を実行し、想定したイベントの下にフックが表示されるかを確認します。matcher を使う場合は大文字と小文字が区別される点にも注意します。
/hooks に何も表示されない。 JSON が正しいか（末尾のカンマやコメントは使えません）、設定ファイルの場所が正しいかを確認します。プロジェクトのフックは .claude/settings.json、全体のフックは ~/.claude/settings.json です。
記録にフックエラーが出る。 スクリプトが想定外の非ゼロで終わっています。サンプルの JSON をパイプで渡して手動で実行し、終了コードを確かめます。
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $? # Check the exit codeスクリプト自体が動かない場合は、chmod +x ./my-hook.sh で実行権限を付けます。
CI やスクリプトからテスト修正を回すにはどうするか？
対話せずに Claude Code を動かすときは -p を使います。公式の headless のページ（Headless）には、テストスイートを実行して失敗を直させる例があります。--allowedTools に挙げたツールは許可を求めずに使われるため、この例では Bash によるコマンド実行と Edit による書き換えが確認なしで進み、作業ディレクトリのファイルが変更される可能性があります。許す範囲を絞るなら、公式の権限モードのページ（Permission modes）にある CI 向けの完全な許可リストの例 claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read" のように、テストコマンドと読み取りだけを許します。
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit"人がいない CI では許可待ちで止まらないよう、権限モードも指定します。公式は、許可が必要になる呼び出しをすべて拒否する dontAsk を、閉じた CI 向けとしています。ただし --allowedTools に挙げた操作は dontAsk でも実行されます。
--bare を付けると、ホストのフックや CLAUDE.md を読み込まずに起動します。サブスクリプションのログインは使わないため ANTHROPIC_API_KEY が要ります。付けない -p は、一度も信頼していないフォルダでもプロジェクトの .claude/settings.json のフックを実行し、信頼の確認ダイアログも出ません。そのため、テスト用の Stop hook を CI で効かせたいかどうかで選びます。
GitHub や GitLab 上の CI 構成はGitHub Actions 連携ガイドとGitLab CI/CD 連携ガイドを、権限モードの違いは権限モードの解説を参照してください。開いているセッションと関係なく夜間にテストを回したい場合は、公式もスケジュール機能を案内しています。設定は定期実行の解説にあります。
公式の仕様で今後変わりやすいのはどこか？
この記事の内容は、2026年10月19日に取得して照合した公式ドキュメントに基づきます。変わりやすいと公式自身が明記している点は2つです。
- agent 型のフックは実験的な機能で、動作や設定が今後のリリースで変わりうると書かれています（Hooks guide）
--bareは、将来のリリースで-pの既定になる予定とされています（Headless）。CI で-pだけを使っているなら、更新時にフックや CLAUDE.md が読み込まれているかを確認してください
自分のプロジェクトで定着させるには
最初の一歩は、テストを依頼する指示の最後に「テストを実行して、失敗したら直して」と添え、確認用の出力結果を見せてもらうことです。それで回るようになったら、CLAUDE.md にテストコマンドを書き、大きな作業では /goal、チーム全体で効かせたい場合は Stop hook へと段階を上げていきます。