Working
Asking for what you want
How to phrase a request so you get the change you meant, first time.
You type in plain English. There's no syntax to learn — but a few habits make the difference between one turn and four.
Say what "done" looks like
The single biggest improvement to any request is a finish line.
| Instead of | Try |
|---|---|
| "fix the login bug" | "logging in with an expired token should show 'session expired' instead of a 500 — there's a failing test in auth_test.go" |
| "make this faster" | "the project list endpoint takes 800ms; get it under 200ms without changing the response shape" |
| "add tests" | "add tests for the retry path in client.go — the timeout case isn't covered" |
It already knows the codebase. What it can't infer is which of five reasonable outcomes you had in mind.
Point at things with @
Mention a path with @ and the file comes along with your prompt.
> why does @internal/auth/session.go drop the refresh token?
> make @web/src/components/nav.tsx match @web/src/components/footer.tsxImages work the same way. @screenshot.png attaches it and the model looks at
it — useful for "make it look like this" and for pasting a stack trace you
screenshotted. CtrlV attaches an image straight off the clipboard.
Ask about the project, not just the code
Some questions aren't answerable from source. Those go to your project's history.
“what did we decide about retries?”
The decision, when it was made, and what it superseded.
“have we tried this before?”
Past sessions that touched the same ground.
“why is this file structured this way?”
The reasoning if it was captured — and silence if it wasn't, rather than a plausible guess.
Plan first when it's bigger than a file
For anything touching several files, /plan <goal> gives you an approach to
correct before any edits happen. See
Planning work that outlives the session.
Interrupt when it goes the wrong way
Esc pauses mid-turn. Say what you actually wanted and type continue — it
resumes from the current state of the files, keeping the edits that were right.
You don't have to start over.
Correct it once and it stays corrected
When you tell it something it got wrong, that correction is captured as a
lesson and surfaces in later sessions. "Don't use any in this codebase," said
once in March, still applies in June — on a different machine.
If it doesn't work
It edits the wrong file. Two similarly named files, usually. Pin it with
@path/to/the/right/one.
It keeps asking clarifying questions. The request has more than one reasonable reading. Give it the finish line and it'll stop asking.
It says it can't find something you know exists. The index may be behind on
a file you just created. /index shows the state; new and edited files are
picked up continuously, but a fresh clone takes a few minutes.