Chapter 02 · Section I · 12 min read
Framing intent clearly
Claude Code does not read minds. It reads prompts. This section is about the difference between a prompt that describes what you want and one that leaves the agent to guess — and why that difference is where most bad output comes from.
Two engineers can hand Claude Code the exact same codebase, ask what is nominally the same question, and get output of radically different quality. The difference is almost always in the framing. Vague framing produces vague work. Concrete framing produces concrete work. This is the first lesson of prompting, and if you get it, most of the rest is fine-tuning.
Say what you want, not what is wrong
Compare two prompts for the same task:
Weak: “The login flow is broken. Fix it.”
Strong: “In src/auth/login.ts, when the user submits a valid email but the password is wrong, the API returns 500 instead of 401. Change the error path so it returns 401 with { error: 'invalid_credentials' }. Add a test.”
The weak version leaves Claude to figure out what “broken” means, which files to touch, and what “fixed” looks like. The strong version specifies the file, the input condition, the current wrong behaviour, the desired behaviour, and the follow-up. Every one of those pins narrows the space of “did I do this right” from vast to tractable.
Include the outcome, not just the action
“Refactor this function” is a means. “Refactor this function so it can be reused by the batch job, which needs to call it 200 times per invocation without opening a new database connection each time” is an end.
Ends give Claude something to check its work against. Means give it a chore to complete without knowing whether it succeeded.
State the constraints
A lot of the prompts that go wrong go wrong because Claude did not know a constraint you took for granted. Common ones worth spelling out:
- Framework or library version. “This is Astro 5, not Next.js.” “React 18, using Hooks, not the old class API.”
- Style rules. “Follow the existing pattern in
src/api/*.ts— notry/catch, let errors bubble to the global handler.” - What not to touch. “Do not modify the
legacy/directory.” - What the test story is. “Tests live in
__tests__/. Use vitest. Assume the DB is mocked.”
When ambiguity is the point
Sometimes you legitimately do not know what you want. That is fine — just say so:
“I want to add rate limiting to this endpoint. I have not decided between a token-bucket approach in-process and Redis-backed. Walk me through the tradeoffs first, then I will pick and you can implement.”
That is a good prompt. It sets Claude up as a thinking partner rather than a code monkey, and it makes the “wait, discuss first” step explicit.
Check your understanding
Quick check
—