You've installed Claude Code and let it read the todo-api repo. Now the real work: the delete endpoint sometimes returns a 500. You type "fix the delete bug" and wait. Ten minutes later Claude says it's done, with a change in a file you didn't expect, and you can't tell whether the bug is gone. The problem isn't Claude. It did exactly what it understood from one very short sentence. This lesson is about handing over work so the first attempt is the one you wanted.
What Claude sees and what it doesn't
Every task starts with Claude reading the code, and current models are very good at it. Folder layout, naming conventions, the test framework, how existing components are built: Claude usually works these out faster than you could explain them. So you don't need to describe your architecture or list your folders.
What Claude can't see is information that was never in the repo:
- A decision the team made in last week's meeting.
- A deploy process that lives in one person's head.
- The environment variable your integration tests need.
There is also information that is in the repo but takes a few minutes of digging, and every new session Claude digs for it again.
Before writing anything down for Claude, ask two questions: could it find this by reading the code, and would it actually go and look? If both answers are yes, leave it out. For todo-api, "the src/ folder holds the source" is noise. "Deploys wait for Minh's approval in #release" is worth writing down.
A specific request
A specific request helps for the same reason: it gives Claude information it doesn't have yet. A good request usually holds three things:
- Where to look: a file, a folder or a function.
- The symptom or the goal: what is wrong, or what you want.
- What done looks like: how you'll know it's right.
Compare:
fix the delete bugwith:
DELETE /todos/:id sometimes returns 500 when the item was
already deleted. look at src/routes/todos.js, write a failing
test that reproduces it, then fix it so the API returns 404The second takes a few seconds longer to type and often saves you a whole round of corrections.
If there are two reasonable ways to do something and you prefer one, say so up front, for example "return 404, not 204". Claude can't read that preference from the code.
Some old habits can go. Capitals and IMPORTANT don't make Claude listen harder; current models follow a plainly worded line, and too much emphasis makes them over-apply the rule. Phrases like "think step by step" or "be thorough" are ordinary prompt text, not keywords: how hard Claude thinks is set by the effort level. One phrase that still helps is "be ambitious". Claude tends to build the smallest thing that satisfies a request because it can't see how far you hoped it would go. When you want the fuller version, with edge cases and the natural follow-ons, say what scope you have in mind.
Hand Claude what it needs
When you already have the thing Claude needs, give it directly instead of describing it:
- A file: type
@and a path to include the file's contents in your message. - An image: paste a screenshot of the design or the error into the prompt.
- Command output: pipe it straight from your terminal.
cat error.log | claude -p "what's going on here"-p takes the piped text, prints the answer and exits, which suits a quick question about a log.
When you don't know what you want yet
Some work isn't thought through yet, such as rate limiting for the public API. You don't have to work it all out before you ask. Ask Claude to interview you:
I want to add rate limiting to the public API but haven't
thought it through yet. Interview me until you could write
the spec, then write it to SPEC.md.Claude asks about the parts you haven't decided, often as choices: limits per user or per key, what happens to requests over the limit, what's out of scope. It keeps going until the answers add up to a spec.
Once SPEC.md exists, start a fresh session to build from it. The new session begins with a clean context and a written definition of done. It is also the file you will hand to a reviewer later.
"Done when…" has to be something Claude can run
Claude stops when the work looks done. With nothing to run that says whether it is done, "looks done" is all it has. You end up being the test suite, and every mistake waits until you happen to notice it.
Give Claude something that comes back pass or fail: a test file, a build's exit code, a linter, a script that compares output with a fixture. With that, Claude closes the loop itself: change, run the check, read the output if it fails, fix, run again. If your repo already has a test command, it is the single most useful line you can write down for Claude.
How strict you make it is up to you:
- In the prompt: "run the auth tests after, and keep going until they pass". No setup, works for any task.
- With
/goal: sets a condition that a separate model checks after every turn. Useful for long runs. - With someone who didn't write the code:
/code-reviewhas a fresh subagent, which never saw the conversation, review the diff. It isn't swayed by the reasoning that produced the code. - With a hook: forces a check to run; that comes in level 6.
Whichever you use, when Claude says it's done, ask for evidence: the command it ran and its output. "All tests pass" on its own tells you very little, and reading the output is faster than rerunning the tests yourself.
If you ask for a review against a spec, spell out the scope, including "skip style". A reviewer asked to find problems will always find something. Fix every small finding and you end up with extra layers of abstraction and tests for cases that never happen.
Steering the session
No configuration replaces watching the first minute and stepping in when Claude heads somewhere you didn't intend. There are only a few controls, so learn them by heart:
Esc: stops Claude mid-action and keeps everything done so far, so you can redirect without losing work./rewind, orEsctwice on an empty prompt: opens the rewind menu, which rolls the code, the conversation or both back to an earlier prompt. That makes it safe to try the bolder approach first and roll back if it doesn't work./clear: starts over. If you've corrected the same thing twice and it's still wrong, a third correction only adds to a conversation that already holds two failed attempts for Claude to reread./clearplus one new prompt that includes what you've learned works better almost every time.
One caution: /rewind checkpoints cover the files Claude edited with its own file tools. A file that only a Bash command touched isn't restored. Rewind works alongside git, not instead of it.
The next lesson, the last of level 1, covers permission modes and how to read a diff before you approve it.