「テストを通して」と頼むと起きること：Claude Codeにテストを改変させない指示

「通して」と頼むと、なぜテスト側が動くのか

「テストを通して」には、直す対象の指定がありません。失敗しているテストは、実装が間違っている場合も、テストの期待値が古い場合もあります。どちらなのかを依頼文が決めていないと、Claude Codeは状況を読んで判断するしかありません。その判断があなたの意図とずれることは起こり得ます。

なお、これは「必ず起きる」話ではありません。起きたときに気づけるよう、依頼側で範囲を絞り、確認の手順を決めておく、という話です。

依頼文テンプレート

以下は説明用の例です。実際のClaude Codeで効果を測定したものではありません。{ } を自分のプロジェクトに置き換えて使ってください。

{テストコマンド} が失敗しています。実装を修正して通してください。

目的：{対象機能}の挙動を仕様どおりにすること。テストを緑にすることが目的ではありません。

禁止事項：
- {tests/ など}配下のファイルを編集しない
- テストのskip、xfail、.only、コメントアウト、削除をしない
- 期待値、許容誤差、タイムアウトを変更しない
- カバレッジ閾値やテスト設定（{設定ファイル名}）を変更しない
- テスト入力を判別して固定値を返すような実装をしない

進め方：
1. まず失敗の原因を説明してください（コードはまだ変えない）
2. 実装側だけを修正する
3. {テストコマンド} を再実行し、結果をそのまま報告する

テスト側が間違っていると判断した場合は、編集せずに止め、
「どのテストの何が仕様と食い違うか」と修正案を報告してください。

ポイントは、最後の「止めて報告」です。禁止だけを並べると、どうしても直せないときの逃げ道がなくなります。逃げ道を「報告」に用意しておくと、黙って緩める方向に流れにくくなります。

毎回書かないための置き場所：CLAUDE.mdとhook

CLAUDE.mdに書く

同じ禁止事項を毎回貼るなら、リポジトリのCLAUDE.mdに短くまとめられます。公式ドキュメントでは、CLAUDE.mdは強制される設定ではなくコンテキストとして扱われ、指示は具体的で簡潔なほど守られやすいとされています（How Claude remembers your project）。

## テストの扱い
- テストが失敗したら、まず実装を疑う。
- 私が明示しない限り、テストファイル・テスト設定を編集しない。
- テストが誤りだと思ったら、編集せず理由と修正案を報告する。

守らせたいならhookで止める

指定したツール呼び出しを実行前に止めるには、PreToolUse hookを使えます。ここではシェルコマンドを実行するcommand型を使います。exit code 2を返すとそのツール呼び出しをブロックでき、stderrの内容がClaudeにブロック理由として渡されます（Hooks reference）。LLMの判断に任せず決まった動作をさせる仕組みである点は、Hooks guideにも書かれています。

.claude/settings.json（説明用の例・未実行）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/protect-tests.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/protect-tests.sh（説明用の例・未実行。Bashとjqが必要です。macOS・Linuxでは chmod +x で実行権限を付けます）：

#!/bin/bash
FILE=$(jq -er '.tool_input.file_path // empty') || {
  echo "ファイルパスを読み取れないため、編集を止めました。hookの入力とjqを確認してください。" >&2
  exit 2
}
FILE="${FILE//\\//}"
case "$FILE" in
  */tests/*|*.test.ts|*_test.py)
    echo "テストファイルの編集は禁止です。実装を直すか、修正案を報告してください。" >&2
    exit 2 ;;
esac
exit 0

使う前に2点確認してください。

• Edit/Writeの対象パスは tool_input.file_path に絶対パスで渡されます（PreToolUse input）。この例の保護対象は tests/ 配下、*.test.ts、*_test.py だけです。test_*.py やテスト設定ファイルなども、プロジェクトに合わせてパターンへ追加し、対象ファイルへの編集がブロックされることを使用前に確認してください。
• この例が止めるのはEdit/Writeツールだけです。Bashコマンド経由のファイル書き換え（sed -i など）は別の対策が要ります。そのため、次節のdiff確認は省かないでください。

緩められた変更の見分け方

作業後は、テストが通ったという報告より先にdiffを見ます。

git status --short
git diff HEAD --stat
git diff HEAD -U0 | grep -nE '^[+-].*(skip|xfail|xit|\.only|TODO|ignore)'

3行目は説明用の簡易検索で、無関係な行も拾い、期待値の変更などは見逃します。ヒットの有無にかかわらずdiff全体を確認してください。git diff HEAD はステージ済みの変更も含みますが、未追跡ファイルの内容は含みません。git status --short に ?? で出るファイルは別途確認します。

見るべき変化を表にします。

• 期待値の変更、怪しい例：expect(total).toBe(1100) が 1000 に、確認すること：仕様側の数字が変わったのか、実装の出力に合わせただけか
• アサーションの緩和、怪しい例：厳密な一致が toBeTruthy() や部分一致に、確認すること：検証していた内容が減っていないか
• アサーションの削除、怪しい例：例外が出ることを確かめる行が消えた、確認すること：消した理由が説明されているか
• skip・無効化、怪しい例：skip、xfail、.only、コメントアウト、確認すること：失敗が隠れただけではないか（.only はテストランナーによって他のテストの実行を除外する）
• 許容範囲の拡大、怪しい例：許容誤差やタイムアウトの数値を増やした、確認すること：不具合の原因を特定したうえでの変更か
• モックの追加、怪しい例：本来通すべき処理をモックに置き換えた、確認すること：テストが本物のコードを通っているか
• 設定の変更、怪しい例：カバレッジ閾値、テスト対象から除外するパターン、確認すること：依頼で許可していない設定変更がないか
• 実装の不自然な分岐、怪しい例：特定のテスト入力のときだけ固定値を返す、確認すること：一般的な処理になっているか

判断の基準は単純です。依頼で許可していないテスト側の差分は、理由が説明されるまで採用しない。テスト側に差分があったら、Claude Codeに「なぜ必要か、実装を直すだけでは通らない根拠は何か」を説明させます。

テストが本当に古いとき

仕様変更でテストの期待値が古くなることは実際にあります。その場合は、禁止を外して頼むのではなく、依頼を2段階に分けるのが安全です。

1. 「テストを編集せず、このテストの期待値が仕様と食い違うかを調べて報告してください」
2. 報告を読んで、あなたが仕様として正しいと確認できたら、「次のテストの期待値だけを、この値に変更してください」と対象を指定して頼む

テスト変更と実装変更を別のコミットにしておくと、レビューで「実装を直した差分」と「テストを変えた差分」を分けて見られます。