Code agents work best with a brief, not a chat message: a clear goal, the relevant context and files, explicit constraints, a definition of done that the agent can verify itself (ideally a test command) and a request to plan before editing. Persistent knowledge belongs in context files, task-specific details in the brief, and long tasks should be split into steps that each end in a reviewable state.
On this page
Prompting a code agent is closer to delegating work to a capable new colleague than to chatting with an assistant. The agent can read your code, run commands and change many files, but it does not know your intentions, your unwritten conventions or what you will consider done. Most disappointing agent results trace back to a missing piece of that information. This article shows how to write briefs that consistently produce mergeable work in Claude Code, OpenAI Codex, Cursor and similar tools.
Three layers of instructions
It helps to separate instructions into three layers. Persistent context is true for every task in a repository: build commands, architecture, conventions and forbidden patterns. It belongs in a context file such as CLAUDE.md, AGENTS.md or project rules. Task brief describes this specific piece of work. Steering is the short feedback you give while the agent works, such as correcting a wrong assumption or narrowing scope. Teams that mix these layers end up repeating conventions in every prompt, or burying task details in a context file nobody updates. Our guide on writing CLAUDE.md and AGENTS.md files covers the persistent layer; this article focuses on the brief.
Anatomy of a good task brief
A reliable brief has six parts. It does not need to be long; for a small bug, each part can be one sentence.
- Goal. What should be true when the task is done, from the user's or system's perspective, not as a list of code edits.
- Context. Why the change is needed, which files or modules are relevant and any background the agent cannot infer from the code, such as a linked issue or a product decision.
- Constraints. What must not change: public APIs, database schema, dependencies, performance budgets or files outside a certain folder.
- Definition of done. Verifiable criteria, ideally a command such as a test suite that must pass, plus new tests the agent should add.
- Approach hints. Optional: existing patterns to follow, for example how a similar endpoint is built.
- Process instruction. Ask for a plan first, or tell the agent to stop and ask when a requirement is ambiguous instead of guessing.
The definition of done is the part most often missing and the part with the biggest effect. An agent that can run a test and see it fail has a feedback loop; an agent without one relies on its own judgment of success.
Weak versus strong: an example
A weak brief might say: fix the bug where the invoice export is wrong. The agent has to guess what wrong means, which export, and how to verify a fix. A strong brief says: invoices with more than one currency export the total in the default currency instead of the invoice currency; the logic is in the export service and its formatter; do not change the CSV column order because a customer integration depends on it; add a test with a two-currency invoice that fails before the fix; done when the full export test suite passes. The second version takes a minute longer to write and typically saves several rounds of correction.
Specs for larger features
For work spanning several files or sessions, write a short spec before prompting. Many teams let the agent draft the spec from a conversation, then edit it by hand, then use it as the source for multiple briefs. A spec should describe behaviour, data models, interfaces between parts and open questions. Storing it in the repository, for example in a docs folder, lets later sessions and other agents refer to it. This spec-first approach is also the basis for running several agents in parallel, which we describe in multi-agent development workflows.
Managing context during a session
Long sessions degrade. As history grows, the agent may lose track of early instructions or keep following an abandoned approach. Practical habits help: start a new session per task, point explicitly to the files that matter, summarise decisions before switching topics and ask the agent to write intermediate notes to a file that a fresh session can read. When the agent goes in the wrong direction twice, stop, rewrite the brief and restart instead of piling on corrections.
Steering without micromanaging
Good steering is short and specific: name the wrong assumption and the correct fact. Avoid rewriting the whole task in a correction. If you find yourself dictating code line by line, the task is either too small for an agent or the brief lacked essential context.
Prompts as team assets
Briefs for recurring tasks, such as adding an API endpoint, writing a database migration or preparing release notes, are worth turning into templates, custom commands or saved prompts in the repository. This makes quality less dependent on who writes the prompt and spreads good practice. Review these assets like code. If you are rolling out agents across a team, our article on what a good agentic coding workshop covers explains how to build these habits collectively.
Common mistakes
Asking for too much at once is the classic. Others include describing implementation steps instead of outcomes, omitting constraints that seem obvious to you, accepting a plan without reading it and forgetting to tell the agent how to run the tests. A subtle one is politeness padding: long, friendly prose that hides the one critical requirement in the middle. Structure beats length.
Practise it with your own backlog
Brief writing is a skill that improves fastest with feedback on real tickets. In our agentic coding workshops at neooutput, teams rewrite their own backlog items into briefs, run them through Claude Code, Codex or Cursor and compare the results. We use the same method to build and launch digital products every day.
Frequently asked questions
Should prompts for code agents be written in English?
Agents understand many languages, but English prompts and context files align with code, documentation and error messages, which reduces ambiguity. Many teams discuss in their native language and write briefs in English.
How long should a prompt for a coding agent be?
As long as needed to cover goal, context, constraints and definition of done, and no longer. For small fixes that can be a few sentences; larger features deserve a separate spec file.
Is it better to ask the agent for a plan first?
For anything beyond a trivial change, yes. Reviewing a plan takes a minute and catches misunderstandings before they turn into large diffs.