Claude Code or your AI agent said done, but the tests fail

Agent: Done! The feature is implemented and all tests pass.

$ npm test
Tests:       2 failed, 41 passed, 43 total

Why it happens

An agent's "done" is a summary, not a result. Common gaps: it ran only the tests near its change, it never ran the production build or the typechecker, it made a failing test pass by loosening it (an added .skip or .only, a deleted assertion, an updated snapshot), it left a stub, or it edited files outside the task.

Fix it by hand

1. Run everything yourself. The full test suite, the production build, the typechecker and the linter, for example npm test, npm run build, npx tsc --noEmit and npm run lint.
2. Read the diff for quiet failures. git diff --stat shows which files changed. Check test files for .only, .skip, removed assertions or rewritten snapshots, and look for any casts, @ts-ignore and TODO stubs.
3. Give the agent the real output. Paste the failing lines back and ask it to fix the code without changing the tests.
4. Write the rule down. In CLAUDE.md or AGENTS.md: "Before saying done, run npm test and npm run build, and paste the last lines of each output."
5. Enforce it in Claude Code with a Stop hook. A Stop hook runs when Claude finishes responding. If it exits with code 2, Claude gets your stderr message and keeps working. In .claude/settings.json:

   {
     "hooks": {
       "Stop": [
         { "hooks": [ { "type": "command",
           "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-tests.sh" } ] }
       ]
     }
   }

   #!/bin/sh
   # .claude/hooks/require-tests.sh
   if ! npm test --silent >/tmp/stop-hook-tests.log 2>&1; then
     echo "Tests are failing. Fix them before you finish:" >&2
     tail -n 30 /tmp/stop-hook-tests.log >&2
     exit 2
   fi
   exit 0

   Claude Code passes stop_hook_active to the hook and stops after 8 blocks in a row, so a test that can never pass won't loop forever.

Stop it happening again

• Keep the Stop hook (or your agent's equivalent) in the project so every session uses it.
• Ask for the real output, not a summary, whenever an agent says something works.
• Turn each mistake you correct into a written rule the agent checks next time.