Verification-Driven Development

Claude Code runs an agentic loop with three blended phases: gather context, take action, then verify results. The catch is the last phase: Claude can only verify against something checkable. If you give it no check, it falls back to its own judgment of whether the work looks done — and 'looks done' is a vibe, not a fact.

This is the most important sentence in the lesson: without a verifier, you become the verification loop. Claude writes the code, declares victory, and hands you something that compiles in its head. You run it, find the bug, paste the error back, and Claude fixes it. Round and round. You are doing the job a failing test could do automatically.

The fix is to flip the relationship. Instead of you checking Claude's work, give Claude something it can check its own work against — a command that exits non-zero, a build that fails, a screenshot that looks wrong. Then Claude's verify phase has teeth: it runs the check, sees red, and iterates until green, all in one turn, before it ever returns to you.

The habit is simple: every non-trivial task should name the signal Claude uses to know it succeeded. You don't need new tooling — you need to say the check out loud in the prompt. Four kinds of verifier cover almost everything:

The difference in outcome is stark. Compare these two prompts:

# Weak — no verifier, Claude guesses when done
Add input validation to the signup form.

# Strong — verifier named, Claude iterates to green
Add input validation to the signup form.
The tests in tests/signup.test.ts encode the rules.
Run `npm test -- signup` and keep going until it passes.

With the strong prompt, Claude doesn't stop at 'looks done' — it runs the suite, reads the failures, and fixes them in a loop without your involvement. A passing test suite is something it cannot rationalize away.

A verifier in the prompt closes the loop within a turn. But some conditions span many turns — "the whole suite is green," "the build is clean across all packages." That's what /goal is for: you state a condition, and Claude keeps working across turns until it's met, instead of returning to you after each step.

/goal all tests in `npm test` pass and `npm run build` succeeds

Claude now treats that condition as the bar for done. It edits, runs the suite, sees failures, fixes them, re-runs — turn after turn — and only truly settles when the condition holds. When you're finished, remove the goal:

/goal clear

The condition should be checkable, not aspirational. /goal the code is high quality gives Claude nothing to test against — you're back to 'looks done.' /goal pytest exits 0 and ruff reports no errors gives it a target it can verify on every turn.

Tests prove logic; they don't prove the app runs. A change can pass every unit test and still crash on launch, render a blank screen, or wire up the wrong handler. That gap is what /run and /verify close (Claude Code v2.1.145+).

• /run launches and drives your project's app so you (and Claude) see the change working in the running app, not just in tests.
• /verify goes further: it builds the app, runs it, and observes the result to confirm a change does what it should — explicitly not relying on tests or type checks.

Both need a small per-project setup so Claude knows how to build and launch your app. You generate that once with /run-skill-generator, which writes a per-project skill teaching /run and /verify how to start and drive the app from a clean environment.

# After making a UI change:
/verify   # builds, launches, drives the app, reports whether the change actually works

This turns a screenshot or a running app into a first-class verifier — the same loop-closing idea as a test command, but for behavior that only shows up at runtime.

Once the work is green, a second independent pass over the diff catches what a passing suite won't — subtle bugs, needless complexity, and security holes. These bundled skills all operate on git diff, so they read only what changed.

Higher effort levels trade speed for coverage: low/medium surface fewer, high-confidence findings; high→max go broader and may include uncertain ones; ultra runs a multi-agent review in the cloud.

/code-review high --fix        # broad review, then apply the fixes to your tree
/code-review medium --comment  # post findings as inline comments on the PR
/simplify                      # cleanup-only pass; use /code-review for bugs
/security-review               # scan the diff for vulnerabilities before you ship

Think of these as verifiers for quality, complementing the verifiers for correctness you wired into the prompt. On versions before v2.1.154, /simplify is equivalent to /code-review --fix.

Everything so far depends on you asking for the check, or on Claude choosing to run it. For unattended runs — background agents, CI, claude -p scripts — you want verification that fires no matter what. That's a Stop hook.

Hooks are shell commands wired to lifecycle points (PreToolUse, PostToolUse, Stop, SessionStart, and more) in .claude/settings.json. Unlike CLAUDE.md instructions, which are advisory, hooks are deterministic and guaranteed — they run on the harness, not at Claude's discretion. A Stop hook runs when Claude is about to end its turn. If your check fails, the non-zero exit blocks the stop and Claude keeps working.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npm test && npm run build" }
        ]
      }
    ]
  }
}

Now Claude cannot end the turn while tests fail or the build breaks — the loop is closed by the harness, not by trust. This is the bedrock under autonomous workflows: pair a Stop hook with /goal (or a headless claude -p run) and the agent grinds to a verified state without supervision.