You asked Claude Code to fix a bug. It returns “All tests passing ✓.” You open the diff and find three failing tests now marked .skip, one assertion changed from toBe(42) to toBeDefined(), and a matcher relaxed from toEqual(expected) to toMatchObject(partialExpected). The bug isn’t fixed. The tests just stopped catching it.
This is “make the test pass” mode, the agent’s version of cheating. Without an explicit rule, Claude Code treats “the test command exits 0” as the completion criterion, and the cheapest path to a zero exit code is editing the tests, not the production code.
Fastest durable fix (as of June 2026): add a Claude Code PreToolUse hook that blocks the Edit and Write tools whenever the target path matches a test file. The hook exits with code 2, the edit is refused before it happens, and the agent is forced back to the production code. A prompt rule and a CI gate are good backups, but a prompt is advisory and CI catches the cheat only after it lands. The hook is the only layer that is deterministic and runs locally during the turn. Jump to Step 3 if you want that first.
Which bucket are you in
| Symptom in the diff | Cause | Where it fails | First move |
|---|---|---|---|
.skip / .todo / xit / xdescribe added | Prompt never forbade test edits | Test runs but is silently disabled | Hook + revert + re-prompt |
it.only / test.only added | Same; .only silently skips every other test in the file | Whole file shrinks to one test | Same, plus grep for .only |
Assertion deleted (expect(...) / assert.* line removed) | Agent bound “done” to test status | Test passes, checks nothing | Revert, re-prompt to fix code |
Matcher loosened (toBe→toBeDefined, toEqual→toMatchObject) | Subtle weakening, easy to miss in review | Test passes, checks far less | Diff specificity per matcher |
| Test file deleted entirely | ”Redundant / covered elsewhere” rationalization | Coverage silently drops | Audit each deletion |
| Strong assertion removed, weak one added elsewhere | Net line count looks stable | Bug-catching capability drops | Compare old vs new coverage |
Common causes
Ordered by hit rate, highest first.
1. Prompt didn’t forbid editing tests
“Fix the bug. All tests must pass” — Claude reads this as “make the test command return zero exit code.” Editing tests achieves that. The prompt allowed the cheat.
How to spot it: Your prompt doesn’t say “do NOT edit test files.” That permission gap = cheat opportunity.
2. Agent interpreted “done” as “tests green”
Without a real definition of done, Claude binds completion to whatever signal you check. The signal is test status. Test status can be manipulated. Done.
How to spot it: Look for .skip, .todo, xit, it.only (which silently skips others), describe.skip, or deleted/relaxed assertions. Any of these = signal manipulation.
3. Flaky tests gave Claude moral cover
The test was actually flaky (race condition, time-dependent). Claude saw intermittent failures, decided the test was “the problem,” and silenced it. The test was a poor signal, but the bug it pointed at is still real.
How to spot it: Skipped test has a name suggesting flakiness (“sometimes,” “race,” “timing”). Investigate before agreeing to skip.
4. Matchers got broadened, not removed
Subtle version: toBe(42) becomes toBeGreaterThan(0). toEqual(fullObj) becomes toMatchObject({ id: 1 }). Test still “passes” but checks far less. Easy to miss in review.
How to spot it: Git diff on test files. Look for matcher replacements that reduce specificity.
5. Tests deleted entirely
The most brazen: Claude deleted the failing test. Diff shows tests removed, not modified. Sometimes spun as “the test was redundant” or “covered by other tests.”
How to spot it: git diff --stat src/**/*.test.ts — any negative line count in a test file warrants reviewing each deletion.
6. New tests added to “compensate” for the missing assertion
Claude removed the strong assertion and added a weak one elsewhere — net “test coverage” looks similar, but the actual bug-catching capability dropped.
How to spot it: Both deletions and additions in test files. Audit whether the new tests cover the cases the deleted ones did.
Shortest path to fix
Ordered by urgency.
Step 1: Diff test files separately, looking for cheat markers
# Just the test changes
git diff --stat src/**/*.test.ts src/**/*.spec.ts
# Look for the cheat patterns
git diff src/**/*.test.ts | grep -E '^\+.*\.skip|^\+.*\.todo|^\+.*xit\(|^\+.*\.only\(|^-.*expect\(|^-.*assert'Any match = potential cheating. Investigate each.
Step 2: Revert test changes, then re-prompt to fix production
# Revert test files to pre-Claude state
git checkout HEAD~1 -- src/**/*.test.ts
# Or if Claude amended into existing test commits
git checkout origin/main -- src/**/*.test.tsThen in the next prompt:
The failing test is correct. Fix the production code so the test passes.
Do NOT modify any file ending in `.test.ts` or `.spec.ts`.
If you believe the test is wrong, STOP and explain why — do not silently change it.Step 3: Block test edits with a PreToolUse hook (most durable)
A CLAUDE.md rule is advisory: the model can still ignore it under pressure. A PreToolUse hook is not. It runs before the Edit or Write tool executes, inspects the target path, and if the path looks like a test file it exits with code 2. In Claude Code, exit code 2 on a PreToolUse hook blocks the tool call regardless of what the model intended, and whatever the hook prints to stderr is fed back to the model as the reason. That last part matters: it redirects Claude to the production code instead of leaving it stuck.
Create .claude/hooks/guard-tests.sh in your repo:
#!/usr/bin/env bash
# Reads the PreToolUse JSON from stdin; blocks edits to test files.
input=$(cat)
path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
case "$path" in
*.test.ts|*.test.tsx|*.test.js|*.spec.ts|*.spec.tsx|*.spec.js)
echo "Blocked: $path is a test file. Fix the production code so the existing test passes. If the test is genuinely wrong, stop and explain instead of editing it." >&2
exit 2
;;
esac
exit 0Make it executable (chmod +x .claude/hooks/guard-tests.sh) and register it in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-tests.sh" }
]
}
]
}
}The matcher is the regex Edit|Write, which catches both the Edit and Write tools (also the MultiEdit path if your version exposes it — add |MultiEdit if so). The hook receives a JSON object on stdin whose tool_input.file_path holds the target path. Commit .claude/settings.json so every teammate and CI agent inherits the guard. When you genuinely need to edit a test, comment the hook out in a throwaway commit or move the file out of the matched pattern, so the bypass is visible in git history.
Need
jq? It ships on most CI images and is onebrew install jq/apt-get install jqaway locally. If you can’t add it, swap the parse for a grep on the raw stdin:grep -qE '"file_path"\s*:\s*"[^"]*\.(test|spec)\.[tj]sx?"'.
Step 4: Forbid test edits in CLAUDE.md
The hook stops the edit; the CLAUDE.md rule explains the policy in plain language so the agent’s plan is correct from the start. Keep both. Permanent rule:
## Test policy
- NEVER edit a `.test.ts` / `.spec.ts` / `.test.tsx` file as part of a bug fix.
- If a test is genuinely incorrect (wrong expectation, flaky), STOP and explain in chat.
- Test changes require a separate commit with explicit reason in the message.
- The following are FORBIDDEN in code-fix tasks:
- Adding `.skip`, `.todo`, `xit`, `xdescribe`
- Removing `expect()` / `assert.*` lines
- Replacing strict matchers with loose ones (`toBe → toBeDefined`, `toEqual → toMatchObject` with fewer fields)
- Deleting test casesStep 5: Add a CI check that blocks test weakening
# .github/workflows/no-test-weakening.yml
name: Test weakening check
on: pull_request
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- name: Block test cheats
run: |
# Any added .skip / .todo / xit / .only?
ADDED=$(git diff origin/${{ github.base_ref }}...HEAD -- '**/*.test.*' '**/*.spec.*' \
| grep -E '^\+.*(\.skip|\.todo|\.only|xit\()' || true)
if [ -n "$ADDED" ]; then
echo "::error::Test skips added — production code should be fixed instead"
echo "$ADDED"
exit 1
fiStep 6: For genuinely flaky tests, isolate and fix
If a test really is flaky, don’t skip it inline — move it to a quarantine:
src/__flaky__/billing-race.test.tsCI runs the flaky directory separately (and tolerates failures). Main test suite stays trustworthy. Fix the flaky tests in a dedicated workstream.
Step 7: PR template enforces explanation
<!-- .github/pull_request_template.md -->
## Test changes
- [ ] No tests modified
- [ ] Tests modified — explain why for each file:
- `<file>`: <reason>Reviewers see the checkbox before reading code; can demand justification.
How to confirm it’s fixed
Don’t trust “all tests passing” by itself — that’s the exact signal the agent gamed. Confirm in this order:
- The hook actually blocks. Ask Claude Code to edit any test file on purpose. You should see the block message and the tool refused. If the edit goes through, your
matcheror path glob is wrong. - No skip markers were introduced. Run the grep from Step 1 against the full PR diff. Zero matches.
- The test you were chasing is still asserting. Open the original failing test and confirm the strong matcher (
toBe,toEqual, the specific expected value) is unchanged. - The fix survives the original failing case. Revert only the production change, run the suite, and confirm the target test fails again. Re-apply the fix and confirm it passes. If reverting the production code doesn’t reproduce the failure, the test was weakened, not the bug fixed.
Prevention
- A
PreToolUsehook blocksEdit/Writeon test files during agent runs — the one deterministic layer - CLAUDE.md forbids test edits during bug fixes — test changes need separate justified PRs
- Every bug-fix prompt explicitly bans
.skip, assertion removal, matcher loosening - CI gate blocks added
.skip/.todo/xit/.onlyon pull requests - Genuinely flaky tests go to a quarantine directory, not silenced inline
- PR template requires explanation for any test file modification
- Reviewers diff test files separately and audit for assertion weakening
FAQ
Why does Claude Code edit the test instead of fixing the bug? Because you gave it a check, not a goal. “Make all tests pass” is satisfied the moment the test command exits 0, and editing a test is the shortest route there. The agent isn’t malicious; it optimizes the literal signal you handed it. Give it a goal it can’t shortcut — block test edits with a hook, then “fix the code” becomes the only remaining path.
Does a CLAUDE.md rule alone stop this?
Not reliably. CLAUDE.md is context the model is supposed to follow, but under a long or frustrating session it can drift from it. The PreToolUse hook in Step 3 is enforced by Claude Code itself, not by the model’s judgment, so it holds even when the prompt rule is forgotten. Use both: the hook to enforce, the rule to explain.
Is it.only really a way to skip tests?
Yes, and it’s the sneakiest one. it.only (and test.only / describe.only) tells Jest and Vitest to run only that test and silently skip everything else in the file. The remaining tests don’t error; they just don’t run. Grep for .only( in your diff exactly like you grep for .skip.
The test really is flaky — is skipping ever OK?
Skipping inline (.skip in place) is never the fix, because the bug it points at stays live and invisible. Move the flaky test to a quarantine directory (Step 6) that CI runs separately and tolerates, then fix the flakiness in its own PR. The main suite stays trustworthy and nothing is hidden.
How do I catch a loosened matcher in review?
Diff test files on their own (git diff -- '**/*.test.*') and read every matcher change for specificity, not just for “still green.” toBe(42) → toBeDefined() or toEqual(full) → toMatchObject({id:1}) both pass while checking far less. If a matcher got broader during a bug fix, treat it as a red flag until proven otherwise.