The Navigator · 13 min mission
Prompting Claude Code: From Vague One-Liner to Directed Brief
Write prompts that close the loop on the first pass — outcome, context, and a check Claude can run.
On this page
This guide gives the exact prompt patterns, commands, and keystrokes for directing Claude Code: scoping an ask, attaching an acceptance check, running the explore→plan→code→commit loop, feeding context with @-references, steering mid-run, and setting reasoning depth. Claude Code runs an agentic loop — gather context → take action → verify results — repeating until the task looks done; a directed prompt supplies the context, the constraints, and a check it can run to know it is finished.
| Lever | Vague | Directed |
|---|---|---|
| Scope the task — name the file, scenario, and testing preference | add tests for foo.py | write a test for foo.py covering the edge case where the user is logged out. avoid mocks. |
| Point to sources — direct Claude to what can answer | why does ExecutionFactory have such a weird api? | look through ExecutionFactory's git history and summarize how its api came to be |
| Reference existing patterns — point at a file to imitate | add a calendar widget | look at how existing widgets are implemented… HotDogWidget.php is a good example. follow the pattern… build from scratch without libraries other than the ones already used in the codebase. |
| Describe the symptom — symptom + likely location + definition of done | fix the login bug | 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 |
Upgrade a vague prompt
Prompt upgrader
A vague ask makes the model guess. Pick a prompt below — or type your own — and watch it become a directed one: outcome, evidence, constraints, acceptance criteria. Each added part is highlighted, with a one-line reason it earns its place.
Before — vague
fix the login bug
The model has to guess the file, the scope, and what “done” means — so it often guesses wrong.
After — directed
- OutcomeMake sign-in succeed for valid credentials again on the /login page.
- EvidenceThe regression is in src/auth/login.ts; a failing repro is in tests/auth/login.test.ts.
- ConstraintsTouch only the auth module. Do not change the public API or the session-token shape.
- Acceptance criterianpm test passes, including the previously failing login case, with no new lint warnings.
Outcome
Names the finished result, so the model optimizes for done — not for sounding busy.
Evidence
Points at the real files, data, or context to ground the work and stop it inventing facts.
Constraints
Draws the guardrails up front, so the model stays inside scope instead of gold-plating.
Acceptance criteria
Defines "passing" as a checkable test, so you both know when the task is actually finished.
Give Claude a runnable check
Claude stops when the work looks done. Without a check it can run, "looks done" is the only signal — and you become the verification loop. Hand over a check (tests, a build, a screenshot) and require evidence rather than an assertion: the test output, the exact command and what it returned, or the screenshot — not the sentence "this works now."
| Pattern | Without a check | With a check |
|---|---|---|
| Provide verification criteria | implement a function that validates email addresses | write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing |
| Verify UI changes visually | make the dashboard look better | [paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them |
| Address root causes, not symptoms | the build is failing | the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error |
| Mechanism | How | Scope | Requirement |
|---|---|---|---|
| In one prompt | Ask Claude to run the check and iterate in the same message | Single watched task | None |
/goal condition | A separate evaluator re-checks the goal after every turn | Whole session, unattended | Claude Code v2.1.139+ |
| Stop hook | Code (not judgment) decides whether the turn may end | Deterministic gate | Hook config; CC ends the turn after 8 consecutive blocks |
| Verification subagent | A second agent reviews the result in its own context | Independent second opinion | None |
Explore → plan → code → commit
For anything bigger than a one-line diff, build understanding before editing. The first two phases run in plan mode (Claude reads files and explores read-only, makes no edits) so you can inspect and edit the plan before code changes.
The four phases, with the prompt that drives each
Explore — plan mode
read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.No edits; Claude only orients.Plan — plan mode
I want to add Google OAuth. What files need to change? What's the session flow? Create a plan.PressCtrl+Gto open the plan in your editor and fix wrong assumptions before they become code.Implement — default mode
Hand the approved plan back with its check baked in:
implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.Commit — default mode
commit with a descriptive message and open a PR
| Method | Action |
|---|---|
| Keystroke | Press `Shift+Tab` to cycle permission modes: default → acceptEdits → plan |
| Single prompt | Prefix the prompt with `/plan` |
| Launch flag | Start the session with `claude --permission-mode plan` |
Feed context deliberately
A prompt is also the files, images, and data you put in front of Claude — pulling the right thing in is often higher-leverage than rewording the sentence. The official mechanisms:
| Mechanism | Syntax | Behavior |
|---|---|---|
| Reference a file | @src/utils/auth.js | Claude reads the file contents before responding; also pulls in CLAUDE.md from that dir and its parents |
| Reference a directory | @src/components | Gives a listing, not the contents |
| Paste an image | Drag-drop, or `ctrl+v` in the CLI | Not `cmd+v` — on most terminals that pastes a file path, not the pixels |
| Pipe data in | cat error.log | claude | Sends shell output as the prompt |
| Reference an MCP resource | @github:repos/owner/repo/issues | Pulls the named @server:resource into context |
| Allowlist a doc domain | /permissions | Lets Claude fetch URLs from domains you hit often |
Iterate and manage context
Correct Claude as soon as you notice drift — don't wait until it has built on a wrong assumption, and don't start over. The window is finite, so clearing or compacting it between tasks is part of prompting: the controls below stop, redirect, or reset the session.
| Control | What it does |
|---|---|
Esc | Stops Claude mid-action with context preserved, so you can redirect |
Esc Esc / /rewind | Opens the rewind menu — restore conversation, code, or both to an earlier point |
| Type + Enter while a tool runs | Queues a correction Claude reads after the current action finishes |
/clear | Resets the context window entirely between unrelated tasks |
/compact <instructions> | Targeted compaction, e.g. /compact Focus on the API changes |
/context | Shows what is using context space when a session feels sluggish |
/btw | Answers a side question in a dismissible overlay that never enters history |
| Subagents | Use subagents to investigate how our authentication system handles token refresh… — reads in its own window, reports a summary |
The commands that drive iteration and context
Command explorer
Every built-in slash command worth knowing, grouped by what it touches. Search by name or purpose, filter by group, and pick one for the full when-to-use and the gotchas the menu never tells you.
32 commands
Show version, model, account, and connectivity.
When: Confirm which model and auth method are active — including the classic case where a stray ANTHROPIC_API_KEY is shadowing your subscription. Works mid-response.
Availability varies by plan, platform, and version — type / in your own session to see exactly what is live for you.
Set reasoning depth with effort, not "think hard"
Only ultrathink is a recognized keyword: include it anywhere in a prompt to request deeper reasoning on that turn (Claude Code adds an in-context instruction; the API effort level is unchanged). The phrases "think," "think hard," and "think more" are passed through as ordinary prompt text and are not recognized triggers — the old "think → think hard → think harder" ladder no longer applies.
The real depth control is /effort — a slider, a level name, or /effort auto (resets to the model default).
| Setting | Value |
|---|---|
| Level names | low, medium, high, xhigh, max (model-dependent), plus Claude-Code-only ultracode |
| Auto | /effort auto resets to the model default |
| Default effort | high on Fable 5, Opus 4.8, Opus 4.6, and Sonnet 4.6 (xhigh on Opus 4.7) |
ultracode | Sends xhigh and orchestrates dynamic workflows; session-only |
| Principle | Weaker | Stronger |
|---|---|---|
| Be clear and direct | *Show your prompt to a colleague with minimal context — if they'd be confused, Claude will be too.* | — |
| Add context / motivation | NEVER use ellipses | Your response will be read aloud by a text-to-speech engine, so never use ellipses. |
| Say what to do, not what not to do | Do not use markdown | Your response should be composed of smoothly flowing prose paragraphs. |
| Ask for action, not suggestions | Can you suggest some changes… | Change this function to improve its performance. |
| Don't over-prompt current models | CRITICAL: You MUST be thorough… (can overtrigger) | Normal phrasing; drop anti-laziness boilerplate |
Knowledge check
You ask Claude to "improve error handling in the upload service." It produces a plausible-looking change. What single addition to the prompt would most reduce the chance you have to babysit and re-steer it?
Headless prompts must be self-contained
Run non-interactively with claude -p "prompt". There is no human to answer a clarifying question, so the brief must carry everything — be explicit about what success looks like and what to do with the results. Example of a complete autonomous prompt: "Review open PRs labeled needs-review, leave inline comments on any issues, and post a summary in the #eng-reviews Slack channel." For batch work, refine the prompt on the first 2–3 items interactively, then loop claude -p across the full set with --allowedTools scoping.
| Flag | Values / example |
|---|---|
-p | Runs the prompt non-interactively |
--output-format | text | json | stream-json |
--allowedTools | "Bash,Read,Edit" — scopes what the run may do |
--permission-mode | Sets the permission mode for the run (e.g. plan) |
--verbose | Emits detailed turn-by-turn logging |
Reach the end and this star joins your charted sky.