How to prompt coding agents: Claude Code, Codex and Cursor (2026)
Practical prompting for AI coding agents: how to write the first brief, give the agent a check to run, use CLAUDE.md, AGENTS.md and Cursor rules, and recover when a session goes sideways.
Key Takeaways
- Tell the agent what it can’t see. The code shows how things work, not why, who the users are, or which rule must never break. Those belong in the prompt or in an instruction file.
- Give it a check that comes back pass or fail. A test, a typecheck, a build or a screenshot to compare. With a check, the agent can fix its own mistakes before you see them.
- Use the instruction file your tool reads. Claude Code reads CLAUDE.md (and can read AGENTS.md), Codex reads AGENTS.md, and Cursor reads .cursor/rules and AGENTS.md. Keep them short.
- Plan first on anything bigger than a fix. Ask for a plan, correct it, then let it build. Correcting a plan costs a sentence; correcting finished code costs a session.
- Ask for evidence, not reassurance. “All tests pass” tells you little. The command it ran and the output tell you a lot.
Quick-Start Prioritization Framework
| Situation | What to put in the prompt | Example phrase |
|---|---|---|
| Starting a new feature | Who it’s for, what’s stored, the rule that must hold | “Only the booking’s owner can see it” |
| Fixing a bug | Exact steps, expected vs actual, the error text | “Steps: sign in as B, open /orders. Expected: empty. Actual: A’s orders” |
| Anything over ~100 lines of change | Ask for a plan before code | “Plan first, don’t edit yet” |
| Done-ness | A check the agent can run | “Run the tests and keep going until they pass; show me the output” |
| Repeated correction | Move it into the instruction file | Add one line to CLAUDE.md or AGENTS.md |
| Session going in circles | Stop, summarise, start fresh | “Write what we learned to NOTES.md” |
A coding agent isn’t a chatbot that writes snippets. Claude Code, Codex and Cursor’s agent read your files, run commands, edit many files at once and check their own work. That changes what a good prompt looks like. The skill isn’t clever wording; it’s telling the agent what it can’t see from the code, giving it a way to know when it’s done, and keeping each request small enough that you can judge the result. This guide covers the first prompt, the instruction files each tool reads, verification, and the habits that keep a long session from drifting, with example prompts you can copy.
How coding agents differ from chat
When you paste a question into a chat window, the model only knows what you pasted. An agent can open any file in the project, search it, run your test suite and read the output. That means you don’t need to paste code into the prompt, and you shouldn’t try to describe the codebase in detail. The agent can read it faster than you can summarise it.
What it can’t read is everything that isn’t in the files: the decision you made with a customer last week, the deploy process that lives in your head, the reason a strange-looking function exists. Anthropic’s Claude Code best-practices page frames almost every prompting problem this way: the agent built the wrong thing because it was missing information it couldn’t get from the repo, or it said it was done because it had no way to check its own work.
Writing the first prompt for a feature
A strong first prompt reads like a short brief to a contractor. It names the user, the data, the rules and the finish line.
The four things to include
- Who uses it and what they’re trying to do.
- What gets stored, with the fields that matter.
- The rule that must always hold, usually about who can see or change what.
- How you’ll know it’s done: a test, a page that should load, an output to match.
An example you can adapt
“Add a class booking feature. Members sign in and book a class from the schedule page. Store bookings with member, class, and created time. A member can see and cancel only their own bookings; admins can see all. A class can’t be overbooked past its capacity. Add tests for: booking succeeds, booking a full class fails, member B can’t see member A’s booking. Run the tests and show me the output.”
That’s six sentences, and it closes off the three mistakes agents make most often on this kind of task: no capacity check, no ownership check, and no proof it works.
Point at things instead of describing them
Reference files directly. In Claude Code and Cursor you can type @ followed by a path to pull a file into context. Paste screenshots of a design or an error. Pipe logs in: Claude Code’s docs show cat error.log | claude -p 'what’s going on here' as a pattern.
Plan before you build
For anything bigger than a small fix, ask for a plan and read it before any code is written.
Why it works
A plan is a few paragraphs you can actually read. If the agent plans to store prices as floating-point numbers, or to add a second login system next to the existing one, you catch it in one sentence. After the code exists, the same correction means undoing and redoing many files.
How to ask
Most agents have a plan mode or will honour “plan only, don’t edit files yet.” A useful version: “Read the code that handles orders. Propose a plan for adding refunds: which files change, any database changes, and what could go wrong. Don’t edit anything yet.” Then reply with corrections, and say “go” when it’s right.
Write the spec down for big work
For a multi-day feature, have the agent write the agreed plan to a file such as SPEC.md. Anthropic’s guide suggests starting a fresh session to build from it, so the build begins with a clean context and a written definition of done you can review against later.
Give the agent a check to run
This is the single highest-value habit. If the agent has something that comes back pass or fail, it can make a change, run the check, read the failure and fix it, often several times, before you look.
What counts as a check
- A test file, or a specific test: “run the auth tests.”
- A typecheck or build: anything with an exit code.
- A linter.
- A script that compares output against an expected file.
- A browser screenshot compared with a mockup, if your agent can drive a browser.
Ask for evidence
End prompts with “show me the command you ran and its output.” Agents sometimes report success optimistically. Reading three lines of test output takes seconds and tells you whether the claim is real.
Make it stick
In Claude Code you can go further than asking. Its docs describe a /goal command that keeps the agent working until a condition you state is met, and Stop hooks in .claude/settings.json that run a script whenever the agent tries to finish and send it back to work if the script fails. A typecheck in a Stop hook is a common setup.
Instruction files: CLAUDE.md, AGENTS.md and Cursor rules
Every major agent reads a file of standing instructions at the start of each session. Anything you’ve had to say twice belongs there.
Which file each tool reads
If you switch between tools, an AGENTS.md is the most portable choice, since all three document reading it.
| Tool | File | Notes from the tool’s docs |
|---|---|---|
| Claude Code | CLAUDE.md in the project root | Read at the start of every session; can read an existing AGENTS.md instead; /init generates a starting version |
| Codex | AGENTS.md | Read before doing any work; files from the repo root down to your folder are combined, 32 KiB cap by default |
| Cursor | .cursor/rules/*.mdc or AGENTS.md | Project rules must use .mdc; AGENTS.md supported in the root and subfolders |
What to put in it
- The exact commands to check work: test, typecheck, lint, how to run one test file.
- Places where the code is misleading: an old pattern new code must not copy.
- Decisions that aren’t in the code: which payment provider, how deploys work.
- Hard rules: “never edit files in src/generated,” “every table needs an ownership check.”
Keep it short
Long instruction files dilute themselves. Anthropic’s memory guide recommends staying under 200 lines. Don’t describe what the agent can work out from reading the code; describe what it can’t.
Prompting for bugs
Bug prompts fail when they describe a feeling instead of a reproduction.
Steps, expected, actual
“Checkout is broken” gives the agent nothing. “Steps: add two items, apply code SAVE10, click Pay. Expected: total $18. Actual: $20, and the console shows TypeError: cannot read properties of undefined (reading ‘percent’).” gives it everything.
Ask for the cause before the fix
If a first fix doesn’t work, don’t just paste the error again. Ask: “Explain why this is happening, with the file and line, before changing anything.” If the explanation is wrong, you’ve saved a round of guess-and-patch.
Ask for a failing test first
“Write a test that reproduces this bug and show me it failing. Then fix the code until it passes.” You get the fix and a guard that stops the bug coming back.
Managing long sessions
Agents work within a context window. Long sessions get compacted or cluttered, and quality drops.
One task per session
Start a fresh session for each unrelated task. In Claude Code, /clear resets the conversation. Carry over what matters by writing it down: “Summarise what we decided and what’s left into NOTES.md.”
Course-correct early
If the agent heads the wrong way, interrupt immediately. Every extra minute adds files you’ll need to review or revert.
Commit at every green state
When a check passes and the feature works, commit. If the next prompt goes badly, you can return to this point in one command. Our Git basics guide covers the handful of commands you need.
Common mistakes
These waste more agent time than any choice of model.
- One giant prompt for a whole app. Break it into features you can test one by one.
- No finish line. Without a check, the agent decides it’s done, and its standard may not be yours.
- Describing the codebase instead of letting the agent read it.
- Repeating corrections in chat instead of adding them to CLAUDE.md or AGENTS.md.
- Accepting “fixed” without seeing output or trying it yourself.
- Letting one session run all day across unrelated tasks.
- Granting broad permissions on a machine with production credentials in plain files.
If you’d rather not wire up the backend yourself
If you’d rather not set up a database, sign-in and hosting for what your agent builds, Floot can be connected to Claude Code, Codex and Cursor through its MCP server so the agent creates those pieces and publishes the app in the same session.
Frequently Asked Questions
What’s the best prompt for Claude Code?
There isn’t a magic phrase. The prompts that work name the user, the data, the rule that must hold and a check to run, then ask for evidence. Put anything you repeat into CLAUDE.md.
Should I use CLAUDE.md or AGENTS.md?
If you only use Claude Code, CLAUDE.md is fine. If you also use Codex or Cursor, AGENTS.md is the shared option: Codex and Cursor read it, and Claude Code’s docs say it can read an existing AGENTS.md too.
How long should a prompt be?
Long enough to state the who, what, rule and finish line, which is often four to eight sentences. Length beyond that usually means the request should be split.
Why does my agent keep breaking things that used to work?
Usually because nothing checks the old behaviour. Ask for tests on features you care about and make running them part of every prompt or instruction file.
Do prompts differ between Claude Code, Codex and Cursor?
The principles are the same. The differences are the instruction file each reads, how you reference files, and features like plan mode and hooks. Check each tool’s docs for those.
What do I do when the agent goes in circles?
Stop it, ask it to explain the cause before changing anything, and if that fails, write a short summary to a file and start a fresh session from it.
Sources
- Anthropic, Best practices for Claude Code, 2026 https://code.claude.com/docs/en/best-practices
- Anthropic, Claude Code overview, 2026 https://code.claude.com/docs/en/overview
- OpenAI, AGENTS.md (ChatGPT Learn), 2026 https://learn.chatgpt.com/docs/agent-configuration/agents-md
- Cursor, Rules, 2026 https://cursor.com/docs/context/rules