Ask before you edit

The most useful thing Claude Code does in an unfamiliar project is not write code. It's answer "what is this?" — and it can do that without changing a byte. Read-only work is free in the sense that matters: nothing needs reviewing, nothing needs undoing.

Ask for a map first. The top-level files, the likely entry point, where configuration lives, and the command that runs the tests. Then check the map against the filesystem yourself. This is not a ritual — it's how you calibrate. A project map that gets the test command wrong tells you something useful about how much to trust the next answer.

When you have a specific question, point at a specific file. "What does src/auth/session.ts do when the token has expired?" beats "how does auth work", because the narrow question has a verifiable answer: you can open the file and see.

I ran: npm run build
I expected: a clean build, like yesterday
I got:

  TS2345: Argument of type 'string | undefined' is not
  assignable to parameter of type 'string'.
    at src/config.ts:42

Diagnose this before proposing a fix. Tell me what you're
confident about and what you're guessing.

Three parts do the work there: the command, the expectation, and the actual output. Most unhelpful debugging sessions are unhelpful because only the third was supplied — without the expectation, Claude has to guess what "working" meant, and without the command it has to guess how you got there.

Asking for a diagnosis before a fix is the other half. A fix arrives as a change you now have to evaluate; a diagnosis arrives as a claim you can check. When the diagnosis is wrong you have learned something cheaply, which is not true of a wrong fix you accepted.

Loading your workspace…