Español

Block Your AI's First Edit

Your AI edits files it never actually read.

An agent will happily rewrite a function based on its name and a guess at what it does, without ever loading the callers, the tests, or the real data flowing through it. The edit looks confident and is often wrong, because the model filled the gap with a plausible assumption instead of a fact. You cannot fix this by asking the agent "are you sure?" LLM self-evaluation does not reliably catch its own missing context. What changes the output is the investigation itself.

Why "are you sure?" doesn't work

Asking a model to double-check its own reasoning tends to produce a confident restatement, not a genuine re-examination. The model has no new information, so it defends the guess. The only thing that changes a blind guess into a correct edit is loading the context that was missing in the first place. So don't audit the conclusion; force the investigation before the conclusion exists.

The mechanism: a gate before the first mutation

Refuse to let the agent make its first edit until it has produced concrete, checkable facts about the code it wants to change. Require all three:

1. List the importers. Who calls this? A change to a function with twelve callers is a different change than one with zero.
2. Name the affected public functions. Which parts of the public surface does this touch, and what is their contract?
3. Show the real data shapes. Paste the actual types, records, or sample payloads flowing through, not an assumed shape.

The rule is simple: no facts, no edit.

Before editing <file>, produce:
  1. Importers of the symbol you will change (grep the tree, list each).
  2. Public functions this change affects, with their signatures.
  3. Real data shapes: actual types / a sample payload, not assumed.
Do not propose an edit until all three are filled in from the code.

Blind guess vs forced investigation

Forced investigation surfaces the context that turns a blind guess into a correct edit, and it does it before any file changes, so a wrong assumption costs you a sentence, not a broken build.

Power moves

• Wire the gate into the tool layer. A hook that blocks the write tool until an investigation note exists is stronger than a polite instruction the agent can skip.
• Demand evidence, not assertions. "I checked the callers" is not proof; a pasted grep result is.
• Scope the investigation to the blast radius. Importers and public surface define what can break, that is exactly what the agent must enumerate.
• Reuse the investigation as the review contract. The facts it gathered up front are the checklist a reviewer uses afterward.

Resources

• Anthropic — Claude Code hooks (gate tool use)
• Anthropic — Building effective agents
• OpenAI — Function calling and tool use
• Simon Willison — Notes on coding with LLMs