How to write prompts for Claude Code that work first time

To write prompts for Claude Code that work first time, give it four things: what should be true afterwards, the files to read (@src/billing/invoice.ts), what must not change, and a check it can run, such as "the new test passes". For a change across several files, ask for a plan and approve it before any edit.

Two of the before-and-after prompts below are ones we send while building Shuriken, real file names included.

Why the first prompt matters so much#

Claude Code is an agent, not a chat box. It reads files, runs commands and edits code until it decides it's done, so a vague prompt doesn't get a vague answer. It gets confident work on the wrong thing.

Anthropic's best-practices page gives two reasons. The first is that "Claude can infer intent, but it can't read your mind." The second is the context window: every file read and every command output stays in the conversation, and "performance degrades as it fills". /context shows what is filling it. A clear prompt helps on both counts, with fewer wrong turns and fewer wasted reads.

The four parts of a Claude Code prompt#

The done-condition is the row most prompts leave out. Anthropic's docs: "Give Claude a check it can run: tests, a build, a screenshot to compare. It's the difference between a session you watch and one you walk away from." In our own content prompts it is a command, npx vitest run --config vitest.node.config.ts test-node/site-content.test.ts, which fails on a title over 60 characters, a related page that doesn't exist or a # heading in the body. Our TDD with Claude Code post goes one step further: write the failing test first, and the done-condition is already in the repo.

Point at files instead of describing them#

"The billing code" makes Claude search. @src/billing/invoice.ts doesn't. Typing @ in Claude Code opens a path menu. A file reference puts the file's contents into the conversation, and a folder reference such as @src/billing/ shows its listing, not its contents (common workflows).

The same docs give four more ways to hand over context:

• Paste a screenshot of the error or the design you want.
• Pipe data in: cat error.log | claude -p "explain this error".
• Name a pattern to copy. Anthropic's own example: "look at how existing widgets are implemented on the home page … HotDogWidget.php is a good example. follow the pattern".
• Point at history. "look through ExecutionFactory's git history and summarize how its api came to be" beats "why is this API weird?".

Context that is true for every task belongs in CLAUDE.md instead: build commands, your test runner, branch rules. Run /init once to start one, /memory to edit it, and keep it short.

When to ask for a plan first#

Plan mode is for a change across several files, or code you don't know yet.

1. Press Shift+Tab until the status bar shows plan mode, type /plan, or start with claude --permission-mode plan.
2. Claude reads and proposes, and edits nothing until you approve.
3. Ctrl+G opens the plan in your editor, so you can change it before Claude starts.

Skip the plan for small work. Anthropic's rule of thumb: "If you could describe the diff in one sentence, skip the plan."

Before and after: prompts from our own work#

Both come from building Shuriken. The first is the prompt for this guide; the second is a bug from 5.0.0.

A content task.

Before:

Write a blog post about Claude Code prompts.

After:

Write the guide "how to write prompts for Claude Code" as
packages/cloud/site/content/guides/prompts-for-claude-code.md, following
content/SCHEMA.md. Every claim must be true against our code or cited from
Anthropic's docs. Don't edit files another agent changed in the last 15
minutes. Done when the content test and build:site pass; report the files
you wrote and the test output.

The second one names the file, the rulebook (SCHEMA.md, 139 lines of rules every page on this site follows), the limits and the check, which is npm run build:site in packages/cloud. The first gets a generic post in a random place.

A bug.

Before:

The app keeps saying "Computer not reached". Fix it.

After:

On a huge chat, loading its history overflows the stack and freezes the
background service, and the app shows "Computer not reached". Write a failing
test that loads a chat with a huge history first. Then fix the loader so a
history that size loads. Run only that test file, not the whole suite.

That one is close to a real bug we fixed for 5.1. On 20 October 2026, Shuriken 5.0.0 on our own machine kept showing "Computer not reached", and the cause was one huge chat whose history load overflowed the stack. The after prompt gives the symptom, the likely cause, the test to write first and the one command to run. Anthropic's docs make the same move: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it".

Small asks and large asks#

For the large kind, Anthropic's docs suggest a short prompt that asks Claude to interview you, ending in a spec file:

I want to build [brief description]. Interview me in detail using the
AskUserQuestion tool. ... Keep interviewing until we've covered everything,
then write a complete spec to SPEC.md.

Then start a fresh session to build from that spec. Numbered steps help as well; the quickstart shows a three-step database-to-webpage example.

A big ask in one prompt also reads more files, and every file read goes into the context. Why Claude Code burns tokens shows where it goes.

When the first try misses#

Anthropic's docs give three ways back:

1. Press Esc to stop Claude mid-action. Context is kept, so you can redirect.
2. Press Esc twice, or run /rewind, to go back to an earlier point in the conversation, the code, or both.
3. If you've corrected it more than twice on the same thing, run /clear and write a better first prompt. "A clean session with a better prompt almost always outperforms a long session with accumulated corrections."

How Shuriken helps: queue and Steer#

In Shuriken the message box stays open while the agent works. Send "now add the same to the CSV export" mid-turn and it joins the chat's queue, then goes when the turn ends. A row can carry attachments and repeat once, a set number of times or until stopped. You can edit, reorder or remove it, and ⌘Z brings a removed row back.

Since 5.1, every queued message also has a Steer button. It sends that message into the running turn, so the agent takes the missing fact on board without stopping: "Use the existing date helper in utils/, don't write a new one." Claude Code, Codex, OpenCode and Pi accept a message mid-turn; with other agents the row waits for the turn to end. Steer Claude Code while it's running walks through the row itself.

Each new chat also runs on its own branch in its own worktree, so you can try two prompts for the same task side by side and keep the better result (running Claude Code agents in parallel).

If you'd like to try both on your own work, download Shuriken.