title: "Prompting for Agents" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [02-project-memory]

Prompting for Agents

The Core Question: How Do I Give Instructions That Work?

Every developer who starts working with coding agents hits the same wall. You type something into the prompt, the agent does... something, and you think: "That's not what I meant." The gap between what you intended and what the agent produced is the prompting gap, and closing it is the single most important skill in agentic development.

The good news: prompting is not mystical. It is a practical skill with learnable patterns. You do not need to memorize magic phrases or speak in a special syntax. You need to understand how agents interpret instructions and adjust your communication style accordingly.

This module teaches you how to give instructions that consistently produce the results you want.

Why Agent Prompting Is Different from Chat Prompting

When you prompt a chatbot, the worst outcome is a bad answer. You read it, shrug, and try again. When you prompt a coding agent, the stakes are fundamentally different: the agent takes actions. It edits files, runs commands, creates directories, installs packages. A misunderstood instruction does not produce a bad paragraph — it produces changed code that you now need to understand and potentially undo.

This difference has three practical consequences:

  1. Clarity matters more. Ambiguity in a chat prompt wastes a few seconds. Ambiguity in an agent prompt can send the agent down a long wrong path, editing multiple files before you realize something went sideways.

  2. Scope matters more. Asking a chatbot to "explain everything about React" just gives you a long answer. Asking an agent to "refactor everything in the project" can trigger sweeping changes that are hard to review.

  3. Context matters more. A chatbot can ask clarifying questions cheaply. An agent that lacks context might make reasonable-sounding but wrong assumptions and act on them immediately.

The upside: agents are also more forgiving than you might expect. They can read your codebase, look up function signatures, and figure out many details on their own. The skill is knowing what to specify and what to let the agent discover.

The Task Decomposition Principle

Complex work breaks down into steps. This is true for humans and it is true for agents. The difference is that agents handle decomposition better when you do the high-level breakdown and let them handle the low-level details.

Consider the task "add user authentication to this app." That is not one task — it is at least five:

  1. Choose and install an auth library
  2. Create a user model and database migration
  3. Build login and registration endpoints
  4. Add middleware to protect existing routes
  5. Write tests for the auth flow

Each of those is a well-scoped agent task. The full request is not. When you give an agent a task that is too large, it has to make many sequential decisions, and the probability of drifting from your intent compounds with each decision.

Decomposition is not about micromanaging. You are not dictating every line of code. You are drawing boundaries around coherent chunks of work so the agent can focus, produce reviewable output, and get your feedback before moving to the next chunk.

The Intent vs. Instruction Spectrum

There is a spectrum between telling an agent what you want (intent) and telling it exactly how to do it (instruction). The sweet spot is closer to intent than most developers initially expect.

Too much intent (vague):

"Make the API better."

The agent has no idea what "better" means to you. Faster? More endpoints? Better error handling? Different response format?

Too much instruction (prescriptive):

"Open src/api/users.ts, go to line 47, change the if statement to use a ternary operator, then on line 52 rename the variable from 'res' to 'response', then..."

You are doing the agent's job for it, badly. The agent is better at navigating code than you are at dictating line-by-line changes from memory.

The sweet spot (intent with context):

"The user API endpoint in src/api/users.ts returns generic 500 errors. Refactor the error handling to return specific HTTP status codes and helpful error messages."

This tells the agent what is wrong, where to look, and what the outcome should look like — without dictating the implementation. The agent can read the file, understand the current error handling, and choose the right approach.

The principle: specify the what and the why. Let the agent figure out the how.

Context Management

Agents operate within a context window — a finite amount of text they can consider at once. Managing this context is a practical skill.

What to include in your prompt:

  • The specific goal of the task
  • Which files or areas of the codebase are relevant
  • Any constraints ("don't change the public API," "use the existing database schema")
  • Examples of similar patterns in the codebase ("follow the pattern in src/api/orders.ts")

What to omit:

  • General background the agent can find by reading files (it can look at your package.json itself)
  • Implementation details you are not sure about (let the agent decide)
  • Long explanations of how the codebase works (point to files instead)

What the agent can find on its own:

  • File contents, project structure, dependency lists
  • Function signatures, type definitions, existing tests
  • Configuration files, build scripts, existing patterns

A common mistake is pasting large blocks of code into your prompt. Instead, reference the file: "Look at the validateUser function in src/auth/validation.ts." The agent will read it with full fidelity. Your pasted code might be stale, truncated, or missing context.

The "Good Enough" First Prompt

Do not spend ten minutes crafting the perfect prompt. Spend thirty seconds writing a reasonable one, send it, and see what happens.

Agents are interactive. Your first prompt starts a conversation, not a contract. If the result is 80% right, a quick correction gets you to 100% faster than trying to anticipate every edge case in your initial prompt.

This is counterintuitive for developers who are used to writing detailed specifications. With agents, iteration is cheaper than specification. A good-enough prompt followed by two rounds of feedback almost always outperforms a meticulously engineered prompt with no feedback.

The practical workflow:

  1. Write a clear but brief prompt
  2. Review the result
  3. Give specific feedback on what to change
  4. Repeat until satisfied

This loop is fast — usually faster than the time you would spend trying to write the "perfect" prompt upfront.

Prompt Anti-Patterns

Three patterns consistently produce poor results:

Being Too Vague

"Make it better." "Fix the bugs." "Clean this up."

The agent does not share your mental model. "Better" to you might mean "faster," "more readable," "more secure," or something else entirely. Always specify what dimension of improvement you care about.

Being Too Prescriptive

"On line 34, change the variable name from x to count. Then on line 35..."

This defeats the purpose of using an agent. If you know exactly what changes to make at the character level, you are faster making them yourself. Agents excel when you describe the problem and let them find the solution.

Context Overload

[Three pages of background, architecture decisions, team conventions, historical context, and tangentially related requirements]

Long prompts bury the actual task in noise. The agent may lose focus on what you actually want. Keep it tight: goal, location, constraints. If you need to convey detailed project conventions, put them in a CLAUDE.md or codex.md file where they persist across sessions (see Module 02).

The Feedback Loop

The most underused prompting technique is feedback. After the agent produces its first result, you have a conversation:

"This is close, but the error messages should include the field name that failed validation."

"Good, but you added a new dependency. Use the built-in Node.js crypto module instead."

"The logic is right but the function is too long. Extract the validation into a separate helper."

Each round of feedback is a prompt in itself, and it benefits from the same principles: be specific, state what you want, and reference concrete details. The agent retains full context of the conversation, so your feedback compounds. By round three, the agent has a much richer understanding of your intent than any single prompt could convey.

When to Start a New Session

Sessions have memory within them but not across them (unless you use project memory files). Over a long session, the context window fills up and the agent may lose track of earlier details.

Start a new session when:

  • You are switching to an unrelated task
  • The conversation has gone on for many turns and the agent seems to be losing coherence
  • You want a fresh perspective on a problem (the agent's earlier wrong assumptions might be anchoring it)
  • The context window is getting full and the tool suggests compacting

Continue the current session when:

  • You are iterating on the same task
  • The agent has built up useful context about your code that would be expensive to re-establish
  • You are in the middle of a multi-step workflow

A practical heuristic: if you would context-switch as a human, context-switch as an agent user too.

Scoping: The Sweet Spot for Task Size

Tasks that are too small create overhead. If you ask the agent to rename a single variable, you spent more time writing the prompt and reviewing the result than just making the change yourself.

Tasks that are too large create drift. If you ask the agent to "build the entire backend," it will make hundreds of decisions without your input, and the result will likely diverge from what you wanted.

The sweet spot is a task that:

  • Has a clear, testable outcome ("the tests pass," "the endpoint returns the right data," "the component renders correctly")
  • Touches a bounded area of code (one file, one module, one feature)
  • Can be reviewed in a few minutes
  • Takes the agent one to five minutes to complete

This typically maps to things like: fix a specific bug, add one endpoint, refactor one function, write tests for one module, update one component. These are the daily building blocks of development work, and they are exactly what agents handle best.

Key Takeaways

  1. Agent prompts have higher stakes than chat prompts because agents take actions, not just generate text. Clarity and scope matter.

  2. Decompose complex work into agent-sized subtasks. Let the agent handle implementation details within each subtask.

  3. Specify intent, not instructions. Tell the agent what you want and why. Let it figure out how.

  4. Manage context deliberately. Include the goal, location, and constraints. Omit what the agent can find on its own.

  5. Iterate, do not over-engineer. A good-enough first prompt plus two rounds of feedback beats a perfect prompt with no feedback.

  6. Avoid the extremes of too vague, too prescriptive, or too much context.

  7. Use feedback actively. Each correction sharpens the agent's understanding of your intent within the session.

  8. Right-size your tasks. Not so small that prompting is overhead, not so large that the agent drifts.

The developers who get the most out of coding agents are not the ones who write the cleverest prompts. They are the ones who communicate clearly, scope work well, and iterate fast.