One Claude Code Tip a Day: Pin the File Before Editing

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

The real failure: the agent fixes a nearby file

A common Claude Code failure is not bad syntax. It is good code in the wrong place. You describe a frontend bug — “the checkout discount appears in the API response but not on the order summary” — and Claude searches broadly, finds a component with a familiar name, and patches it. The diff looks reasonable. The test may even pass. Then you open the app and the discount is still missing because the production route renders a different component, or mobile uses a separate summary drawer, or the price row is composed from a shared formatting file. Today’s habit is simple: use `@file` to pin Claude Code to the actual file before you let it reason or edit.

Use `@file` as an anchor, not a shortcut

`@file` is most useful when you already have one source of truth: a failing test, a component, a route, a log parser, a migration, or a config file. Instead of saying “fix the checkout summary,” start with the file that evidence points to:

`Read @apps/web/src/components/OrderSummary.tsx and @apps/web/src/lib/price-format.ts. Do not edit yet. Explain how discounts flow into the displayed total, and name the exact condition that could hide a discount even when the API response contains one.`

This prompt changes the session. Claude Code is not free to invent the architecture from search results. It must inspect the files you named and explain the mechanism before editing.

A realistic debugging loop

Imagine the browser console shows no error, network logs show `discountCents: 1500`, but the UI renders the original total. First, ask Claude to read the relevant file and state a hypothesis:

`Using @apps/web/src/components/OrderSummary.tsx, trace the rendering path for discountCents. Do not change code. Tell me which branch controls the discount row, which props come from the parent, and what evidence would prove this component is the one on the page.`

Claude might notice that the row only renders when `discountLabel` is present, not when `discountCents` is nonzero. That is a useful hypothesis, but do not patch yet. Make it prove the file is active:

`Now inspect @apps/web/src/routes/checkout.tsx. Does this route render OrderSummary directly or through another wrapper? If another component maps API data into props, name that file before editing.`

The second pass often catches the real bug: the route passes `discountCents` but never maps `promotion.name` into `discountLabel`.

The edit contract

Once the file path is proven, turn `@file` into an editing contract. Keep the task narrow and reversible:

`Edit only @apps/web/src/routes/checkout.tsx and, if required, @apps/web/src/components/OrderSummary.tsx. Make the smallest change so a nonzero discount with no label still renders a discount row using the fallback label "Discount". Do not refactor unrelated pricing code. After editing, run the relevant test and show git diff.`

This is better than “fix it” because it defines the permitted surface area. If Claude touches a currency utility, updates snapshots across the app, or renames props in three packages, you have a clear reason to stop the session and ask why.

Inspect the result like a reviewer

After Claude edits, inspect evidence, not confidence. Ask for three things: the diff, the command output, and the user-visible verification path.

`Show the git diff for @apps/web/src/routes/checkout.tsx and @apps/web/src/components/OrderSummary.tsx. Then summarize which test proves the mapping works. If no test exists, propose the smallest test before claiming the bug is fixed.`

For frontend bugs, add a browser check when possible. A unit test can prove the label mapping, but it cannot prove the row is visible in the rendered checkout drawer. A good Claude Code loop may end with:

`Run the checkout story or Playwright test that renders a discounted order. If it fails, paste the failure and do not make a second edit until you explain whether the failure is test setup, CSS visibility, or wrong data.`

This keeps the session grounded in observable behavior.

Failure modes

The first failure mode is anchoring the wrong file. `@file` makes Claude focused, not magically correct. If you pin a dead component, Claude may produce a beautiful patch that never runs. Always pair file anchoring with a question like “what proves this file is on the failing path?”

The second failure mode is over-anchoring. If you mention ten files, you recreate broad search with extra ceremony. Start with one or two files tied to evidence, then let Claude ask for the next file only when the path requires it.

The third failure mode is using `@file` only after the edit. By then the agent has already built a mental model from guesses. Pin the file during analysis, before implementation.

Second-pass correction

When the first patch is wrong, do not restart with a vague complaint. Use the failed evidence to re-anchor:

`The Playwright checkout test still fails: the discount row is absent. Re-read @apps/web/src/routes/checkout.tsx and @apps/web/src/components/MobileOrderDrawer.tsx. Do not edit. Explain why the previous patch did not affect the failing viewport, then propose the smallest second patch.`

This is where `@file` shines. You are not asking Claude to “try again.” You are teaching it to connect the failed verification to a more precise file boundary.

Rule of thumb

Use `@file` whenever the cost of editing the wrong place is higher than the cost of one extra inspection prompt. Anchor the session on the file, make Claude explain the mechanism, prove the file is on the failing path, then edit narrowly and review the diff. The best Claude Code sessions feel less like autocomplete and more like a disciplined debugging partner with a finger on the exact line of code that matters.