One Claude Code Tip a Day: Name the Failure Signal First

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

A Claude Code session usually fails quietly before it fails loudly. The model starts editing, the diff looks reasonable, and only at the end do you realize nobody agreed on what would prove the bug was fixed. Was the target a failing unit test, a console error, a visual regression, a 500 in production logs, or a user flow that should stop timing out? If that signal is vague, Claude can produce a plausible patch that changes code without changing reality.

Today’s habit is simple: before Claude Code edits anything, make it name the failure signal. A failure signal is the piece of evidence that currently says “broken” and should say “fixed” after the patch. It can be a failing test, a stack trace, a browser screenshot, a log line, a curl response, or a git diff constraint. The point is not bureaucracy. The point is to prevent the model from optimizing for a tidy explanation instead of a verified outcome.

The real task: a bug report with too many possible causes

Imagine a product dashboard where the “Export report” button sometimes produces an empty CSV. A teammate says, “Claude can probably fix this quickly.” Maybe it can. But if you start with “fix the export bug,” Claude may jump into the React button, add a loading state, and declare victory. The empty CSV might actually be caused by stale filters, an API route that drops a date range, or a background job that returns before rows are ready.

Start the session with a read-only prompt that forces the evidence to the front:

Prompt: “Do not edit yet. Read the likely export flow and identify the failure signal we should reproduce before patching. Name the exact test, log line, request, UI behavior, or file output that currently proves the bug. If the signal is missing, propose the smallest way to create one.”

Then give Claude enough context to avoid guessing. If you know the files, anchor them: “Use @app/reports/ExportButton.tsx, @app/api/reports/export.ts, and @tests/reports. First explain the path from click to CSV bytes.” If the bug came from production, paste the relevant log excerpt and ask Claude to separate symptoms from proof.

What a good first answer looks like

A useful answer does not begin with a patch. It says something like: “The failure signal should be a request to /api/reports/export with filters applied that returns a CSV containing only headers. We can reproduce it with the existing report-export test by adding a filtered fixture, or manually with curl after seeding two rows. The current UI spinner is not the signal; the CSV contents are.”

That answer is valuable because it narrows the session. Claude has now identified the artifact that must change. You can ask for commands that match the repo instead of generic advice: !pnpm test reports-export, !curl -s localhost:3000/api/reports/export?... | wc -l, or !git diff -- app/api/reports tests/reports. If the command fails because the repo uses npm, Docker, or a seeded database, that mismatch becomes part of the evidence rather than a detail hidden until the end.

Use the signal to control the patch

Once the failure signal is named, ask Claude to make the smallest patch that moves it. A good follow-up is: “Patch only the code path connected to this signal. Do not clean up neighboring files. After editing, rerun the same reproduction command and explain whether the signal changed.”

This matters in real sessions because Claude Code is good at finding adjacent improvements. It may notice old naming, duplicated helpers, or missing types. Those may be worth fixing later, but they can also bury the bug under noise. The failure signal gives you a boundary: if a change does not help the signal move from red to green, it probably belongs in a separate commit.

Second-pass correction: challenge the signal itself

The first proposed signal can be wrong. Maybe the empty CSV is only visible in the browser because a download library strips the body. Maybe the backend test passes because it bypasses auth. Maybe the log line is a consequence of the timeout, not the cause. Before accepting the patch, ask Claude to critique its own evidence:

Prompt: “Challenge the failure signal. What would make this proof misleading? Is there a lower-level or higher-level check that would catch the real user-visible bug better? If our current signal is insufficient, adjust the verification plan before making more edits.”

This second pass is where many shallow sessions become useful. Claude may decide to keep the focused API test but add one browser-level manual check. Or it may discover that the API response is correct and the actual failure is a frontend race after changing filters. You have not wasted work; you have prevented the wrong fix from becoming polished.

Failure modes to watch for

The first failure mode is a signal that is too broad: “the app works” or “tests pass.” Push back until Claude names the specific test, route, component state, log line, or user action. The second is a signal that is too internal: a helper function returns a value, but the user still receives an empty file. Pair internal checks with one user-visible confirmation. The third is changing the signal mid-session without saying so. If Claude starts with a failing test and ends by showing only a clean typecheck, ask it to rerun the original test.

Also watch for evidence theater. A long explanation, a pretty checklist, or a confident “this should fix it” is not verification. Make Claude paste the command result, summarize the before/after, and review the git diff for unrelated changes. The signal should survive the whole loop: reproduce, patch, rerun, inspect diff, and then decide.

Rule of thumb

Before Claude Code edits, ask: “What exact evidence is broken, and what exact evidence will prove it is fixed?” If the session cannot name that signal, it is too early to patch. The best Claude Code workflows do not start with code generation; they start by choosing the proof that will keep the code honest.