The Complete Guide to Prompting AI Coding Agents (2026)

Key takeaways:

• A coding agent is an autonomous, tool-using system — it plans, edits files, runs commands, and iterates. A chat model is single-turn and reactive. The same prompt that works in ChatGPT will underperform in an agent.
• Agents fail for structural reasons: ambiguous goals, missing stop conditions, too much or too little context, unverifiable acceptance criteria. Tighten the prompt and you tighten the run.
• Six skills transfer across every 2026 coding agent: spec-writing, scope, context, acceptance criteria, tool constraint, and critical review.
• The tool landscape has segmented — terminal-native (Claude Code, Aider), IDE-native (Cursor, Windsurf, Continue.dev), autonomous (Devin), cloud full-stack (Replit Agent, Bolt.new), and targeted UI (v0). Choose based on workflow, not benchmarks.
• Shared techniques — ReAct, plan-and-execute, multi-agent, tool use, self-refine, Reflexion — show up in every agent's internal loop. Knowing the vocabulary helps you steer.

Prompting an AI coding agent is not prompting a chat model. An agent plans, reads files, runs commands, edits code, and iterates — all from a single input. A conversational nudge that works on ChatGPT leaves an agent without a target, a scope, or a stop condition. That is why so many developers describe their first week with Claude Code or Devin as "it kind of works, sometimes." The agent is fine. The prompts are not.

This guide walks through what changes when you move from chat to agents, the six skills that transfer across every tool, the current tool landscape, and the shared techniques that show up inside every agent's loop. It pre-links to a cluster of deep-dive guides for each tool and technique.

What Is an AI Coding Agent?

An AI coding agent is a system that takes a natural-language goal and executes toward it autonomously over multiple steps, using tools — a file editor, a shell, a test runner, a web browser — to make progress. It plans, acts, observes, and iterates. See the agentic AI glossary entry for a longer definition.

Contrast that with a chat assistant. A chat assistant is single-turn and reactive: you ask, it answers, and the loop ends. It does not decide on its own to run npm test, re-read a file it forgot, or open a new git branch. An agent does all of that without asking permission each time.

The category now spans many shapes:

• Terminal-native agents like Claude Code and Aider run inside a shell and operate on your local repo.
• Editor-native agents like Cursor and Windsurf live inside the IDE and stay tied to your open files.
• Autonomous agents like Devin run longer sessions with less step-by-step supervision.
• Cloud scaffolding agents like Replit Agent and Bolt.new spin up whole applications end-to-end.
• Targeted UI agents like v0 focus on a single domain — in v0's case, generating React components.

All of these share the same loop: plan → act → observe → decide. What changes is where they run, which tools they have, and how much autonomy you give them.

Agents vs. Chat Models — Why Prompting Must Change

The shift from chat to agents forces the prompt to carry more weight. A chat model only has to produce a good next message. An agent has to figure out a sequence of actions, stop at the right time, and not wreck anything along the way. Here is the contrast laid out directly:

The practical consequence: chat-style prompts — "Hey, could you add a retry to this function? Thanks!" — produce agent behavior that looks confused. The agent might touch five files, rename things it should not have, and declare victory without running the tests. Not because it is dumb. Because you did not tell it where the edges were.

# Bad — chat-style prompt in an agent
Add a retry loop to the API client. Make it robust.

# Good — spec-style prompt in an agent
Goal: Add a retry loop to `lib/api/client.ts` for the `request()` function.

Scope:
- Only edit `lib/api/client.ts` and its test file `lib/api/client.test.ts`.
- Do not change the function signature.
- Do not touch any other files.

Behavior:
- Retry on network errors and 5xx responses.
- Max 3 attempts with exponential backoff (100ms, 200ms, 400ms).
- Do not retry on 4xx responses.

Acceptance:
- New tests cover both retry-on-5xx and no-retry-on-4xx.
- `npm test` passes.
- Stop when tests pass.

The second prompt is not more verbose for the sake of it. Every line removes a decision the agent would otherwise guess at. For a deeper look at spec shape, see spec-driven AI coding.

The Six Skills of Prompting Coding Agents

These six skills compose. Each one removes a failure mode. Together they turn agent prompting from "sometimes works" into a reliable pipeline.

Skill 1: Write a spec, not a chat request

The single biggest upgrade in coding-agent prompting is replacing conversational asks with structured specs. A spec has four parts: goal (what to build), scope (what to touch and not touch), context (which files matter), and acceptance (how we know it is done).

# Spec skeleton that works across every coding agent

GOAL:
  [One sentence — what finished looks like from the outside]

SCOPE:
  - [Files or modules the agent is allowed to edit]
  - [Explicit out-of-scope: "do not touch X"]

CONTEXT:
  - [Relevant files to read before editing]
  - [Links to the ticket, design doc, or test spec]

ACCEPTANCE:
  - [Verifiable criterion 1 — usually a test or a command]
  - [Verifiable criterion 2]
  - [Stop when all criteria pass]

Writing specs is itself a skill. It forces you to think through edge cases before the agent encounters them. Most bad runs come from under-specified inputs — not from weak models. For detail, see our spec-driven AI coding post.

Skill 2: Define scope and stop conditions

An agent without a stop condition will keep going. It will "improve" the code, add "defensive" checks, rename variables for "clarity," and touch files that have nothing to do with the task. This is not malice — it is the agent optimizing for "do more useful work," which is close to but not the same as "finish the task."

Two guardrails prevent this:

• Scope — an explicit list of what the agent may and may not edit.
• Stop condition — an explicit signal the agent should look for to declare done.

SCOPE:
  - Edit only `src/auth/session.ts` and its tests.
  - Do not touch the login UI, the database schema, or the middleware.

STOP CONDITION:
  - All tests in `src/auth/**` pass.
  - No files outside `src/auth/**` have been modified.
  - Output a summary of the diff and stop.

Stop conditions also protect against loops. When an agent cannot tell whether it is done, it often oscillates — edit, re-edit, revert, retry. A clear "stop when X" turns a potentially infinite run into a bounded one. The companion post on agent debugging prompts covers what to do when the agent still gets stuck.

Skill 3: Provide the right context files

The temptation is to dump the whole repo and let the agent figure it out. Resist it. More context is not better context. Agents weigh every file they read, and noise drowns the signal — on top of burning tokens and slowing the run.

The rule of thumb: three to five files, carefully chosen.

Which files matter? Usually:

• The file you are editing.
• The test file for what you are editing.
• Any file that defines a type, schema, or interface the change depends on.
• One or two representative examples if the pattern is new.

That is it. Architecture notes, naming conventions, and tech-stack context belong in a persistent project file (CLAUDE.md, .cursorrules, AGENTS.md, whatever your agent reads by convention) — not pasted into every prompt. The tool use prompting patterns post goes deeper into which file reads to allow vs. require.

CONTEXT:
  Read these files before editing:
  - lib/payments/stripe.ts  (the module to edit)
  - lib/payments/stripe.test.ts  (existing test shape)
  - lib/payments/types.ts  (the PaymentIntent type)

  Do not read the rest of the repo unless one of these files imports it.

Skill 4: Write verifiable acceptance criteria

"It works" is not an acceptance criterion. Neither is "the code is clean" or "handle edge cases." An agent cannot verify any of those. If you cannot check a criterion with a command or a test, you are asking the agent to self-report, which is the same as asking it to grade its own homework.

Verifiable criteria look like:

• npm test passes with no failures.
• The new endpoint returns 200 on valid input and 400 on missing fields.
• tsc --noEmit returns 0.
• No files outside the scope list have been modified (git diff --name-only).
• The diff touches fewer than 120 lines.

ACCEPTANCE:
  1. `pnpm test lib/cache` — all tests pass.
  2. `pnpm typecheck` — no errors.
  3. `git diff --name-only` — only files inside `lib/cache/` appear.
  4. The cache hit-rate logging is emitted exactly once per request.
  5. Stop when all of the above hold.

This is the single highest-leverage skill in agent prompting. Tight acceptance criteria transform the agent from "hope it did the right thing" into a closed loop. The autonomous testing with AI post expands on how to compose acceptance tests the agent can run itself.

Skill 5: Constrain tool use deliberately

Coding agents are dramatically more useful when they can run the test suite, the type checker, and the linter — because they can close their own feedback loop. They are dramatically more dangerous when they can do anything. The job is to allow the former and block the latter.

A reasonable default tool policy:

This is how you keep the agent useful without giving it the keys. In Claude Code, Cursor, Aider, Devin, and others, the specifics of how you express this vary — allowlists, permission prompts, rulefiles — but the principle is shared. See tool use prompting patterns for the patterns and MCP and tool use prompting for a related discussion of structured tool access.

TOOLS:
  - Allowed without asking: read, write (in scope), run tests, run typecheck, git add, git commit.
  - Ask first: installing a new package, editing any file outside scope, any git push.
  - Never: force-push, delete branches, touch files outside the repo.

Skill 6: Read agent output critically

The agent's self-report is not verification. When it says "I added the retry logic and all tests pass," you still have to look. Not because the agent is lying — because it can be wrong about what it did. It can edit the wrong file, add a test that silently passes, or import a function that does not exist.

A checklist you can run on every agent output:

• Open the diff. Read it end to end.
• Re-run the tests yourself. Do not trust the agent's "tests pass."
• Look for invented APIs — imports, flags, methods that do not exist.
• Check for scope creep. If files outside scope changed, find out why.
• Check error handling paths. Agents often skip them.
• Check that new code is tested, not just that old tests pass.

The AI code review agents vs. prompts post goes into how to automate parts of this review — and where human eyes still have to live in the loop.

# Prompt for the agent's closing step
When you believe you are done:
1. Print the full diff.
2. Run the test command and paste the full output.
3. List any files you read but did not edit.
4. List any assumptions you made that the spec did not cover.
5. Stop and wait for approval.

Tool Landscape 2026

The coding-agent space has segmented into distinct shapes. Here is how the major tools position themselves. These descriptions stick to generally-known positioning — when specific feature details are fast-moving, the cluster posts go into depth.

Claude Code (Anthropic)

Claude Code is Anthropic's terminal-native coding agent. It runs as a CLI in your local repo, reads files, edits them, runs shell commands, and iterates through a task. It leans toward fine-grained control — you approve or restrict tools, point it at context, and steer the run. It is a strong fit when you want the agent close to your existing terminal workflow rather than inside an IDE. For the prompting patterns specific to it, see the Claude Code prompting guide.

Cursor

Cursor is a fork of VS Code with an integrated coding agent. Its Composer / agent mode lets you describe a change and have the agent edit multiple files with project awareness. It is well-suited for developers who want the agent inside their editor and tied to the files they already have open. The Cursor AI prompting guide covers the patterns that translate well to Cursor's agent flow.

Devin (Cognition)

Devin is Cognition's autonomous coding agent, positioned for longer, more hands-off task execution — handed a ticket, it plans, executes, and reports back. It emphasizes task completion over line-by-line collaboration. The tradeoff: you give it more autonomy, which raises the premium on spec quality and tight acceptance criteria. The Devin AI prompting guide goes into how to brief it effectively.

Replit Agent

Replit Agent runs inside Replit and is positioned for full-stack scaffolding from a natural-language prompt — from blank workspace to running app, including files, config, and deployment. It is strong for going from idea to a running prototype without touching local tooling. The Replit Agent prompting guide covers the shape of prompts that work for application scaffolding.

GitHub Copilot Workspace

GitHub's Copilot Workspace is Microsoft's agent-shaped surface for coding tasks tied to GitHub issues and repositories. It fits naturally where the work is already expressed as issues and PRs. The GitHub Copilot Workspace prompting post covers how to write issues and specs that Workspace can execute against.

v0 (Vercel)

v0 is Vercel's AI tool focused on generating UI — React components and pages — from a prompt. It is narrower in scope than a general coding agent, optimized for the frontend/React/Next.js path. That focus makes it sharp: prompts that describe a UI and its behavior get usable output quickly. The v0 prompting guide covers what to include when you want a component, a full page, or a small feature.

Bolt.new (StackBlitz)

Bolt.new is StackBlitz's in-browser agent for spinning up full applications in a sandbox — file system, package install, live preview — driven by natural-language prompts. Like Replit Agent, it leans toward scaffolding and prototyping rather than surgical edits on an existing codebase. See the Bolt.new prompting guide for the prompting patterns that fit its sandboxed model.

Windsurf (Codeium)

Windsurf is Codeium's IDE with an integrated agent, often compared against Cursor. It sits in the same editor-native slot: you work in files, and the agent has awareness of the project. The Windsurf AI prompting guide gets into the Windsurf-specific workflow.

Aider

Aider is an open-source terminal-native coding agent that works with many model providers. It emphasizes git-aware editing — every change goes through commits you can inspect and revert. That auditable-by-default stance makes it a strong fit for developers who want tight control. The Aider prompting guide covers the patterns that fit its git-first workflow.

Continue.dev

Continue.dev is an open-source IDE assistant that you configure with your own model and tooling choices. It spans chat-style help and agent-style actions inside the editor. The openness and configurability make it appealing to teams that want to keep their model choice flexible. The Continue.dev prompting guide covers the prompting style that works well inside its setup.

How to choose

There is no single right answer. A rough map:

Benchmarks move weekly. Workflow fit does not. Pick the tool whose shape matches how you already work, and the six skills above will carry across.

Shared Techniques Across Agents

Under the hood, coding agents run variants of a small set of prompting techniques. Knowing the vocabulary helps you read docs, debug loops, and steer runs.

ReAct — interleaves reasoning and action in a Thought → Action → Observation loop. It is the most common internal shape of a coding agent's planning step. The ReAct prompting guide expands on it, and the ReAct glossary entry gives the short form.

Plan-and-execute — splits a run into an explicit planning step (outline the subtasks) and an execution step (carry them out). Useful when a task is large enough that a single ReAct loop would lose the thread. The plan-and-execute post covers when to invoke a separate plan step.

Multi-agent orchestration — more than one agent, each with a role (planner, implementer, reviewer). Adds coordination cost, pays off for complex or long-running work. See the multi-agent prompting guide.

Tool use patterns — how agents call external functions (file edit, shell, HTTP, DB) with structured arguments. The tool use prompting patterns post gets into schema design and safety; the tool use glossary entry gives the definition.

Self-refine — the agent generates, critiques its own output, and revises. Helpful as a closing step before an agent declares done, especially on non-trivial code changes. See the self-refine guide.

Reflexion — a memory-based variant where the agent reflects on past failures and carries the reflection forward into the next attempt. Useful in multi-attempt loops, like a run that retries a failing test. See the Reflexion prompting guide.

These are also the techniques described in the companion posts on agentic AI prompting and the broader AI agents prompting guide — both of which come at the same material from slightly different angles.

Workflow Patterns

Techniques compose into workflows. A few are worth naming because they show up across teams and tools.

Spec-driven coding — the workflow anchor of this guide. You write a spec (goal, scope, context, acceptance), the agent executes, you review the diff. It is slower in minutes per task and faster in successful tasks per day. See spec-driven AI coding for the full pattern.

Agent debugging — when an agent gets stuck, the fix is almost never "nudge harder." It is "inspect the last three actions, find the missing piece, restart with a tighter scope." The agent debugging prompts post covers the common failure shapes and the prompts that unstick them.

Autonomous testing — letting the agent write and run tests as part of its loop, so acceptance is self-checked. This is the practical expression of Skill 4. The autonomous testing with AI post walks through how to set it up without ending up with useless rubber-stamp tests.

Code review: agents vs. prompts — you can use a single long prompt to review a PR, or you can use an agent that fetches the diff, pulls the changed files' context, runs the linter, and writes comments. Different tradeoffs. See AI code review: agents vs. prompts and, for the prompt-only side, the existing code review prompt patterns.

Common Anti-Patterns

Most agent failures look like one of these. Each has a concrete fix.

• "Review this PR" with no scope. The agent picks something to say about everything and says nothing useful about anything. Fix: name the concerns to check — security, performance, error handling, test coverage — and let the agent focus.
• No stop condition. The agent keeps "improving" until it has edited half the repo. Fix: specify the stop signal explicitly — a test passing, a file count, a diff-size budget.
• Too many context files. You paste 40 files, the agent drowns, and the important file gets ignored. Fix: 3-5 files, chosen for direct relevance.
• Trusting the agent's self-report. "Tests pass" can be wrong for three reasons: they did not run, they ran on the wrong files, or the agent is looking at stale output. Fix: re-run the tests yourself; diff-review every change.
• Vague acceptance criteria. "Make it robust" is not checkable. Fix: translate every criterion into a command that returns pass or fail.
• Unbounded tool access. Full shell access plus full git access plus production credentials is asking for a bad day. Fix: an allowlist of safe tools, a confirm-list for risky ones, a deny-list for destructive ones.
• Re-prompting when stuck instead of diagnosing. Each nudge burns tokens without converging. Fix: stop the run, look at the last three actions, fix the missing piece (context, test, tool), then restart.
• Letting the agent install dependencies freely. A "helpful" npm install some-obscure-package is an unreviewed supply-chain decision. Fix: route new dependencies through a confirm step.
• Prompting the agent to write "clean code." Clean is not a specification. Fix: name the style rules that matter (linter config, naming conventions, file size limits) and let the linter enforce them.
• Skipping the diff read because the tests passed. Tests catch regressions, not scope creep or invented APIs. Fix: always open the diff.

How to Evaluate an Agent's Output

A short checklist you can copy. Run every item before you accept an agent's work:

• Diff is small enough to read. If it is not, reject and tighten scope.
• Every changed file was in scope. Anything outside scope needs a written reason.
• Tests run locally — not just "the agent says they pass."
• New behavior has a new test. If it does not, the agent is under-tested.
• No invented APIs. Search the codebase for every unfamiliar import.
• No silent error handling — no empty catches, no swallowed promises.
• Type checker passes. Linter passes. Formatter applied.
• The commit message describes the change honestly, not the agent's mood about the change.
• You could explain every change to a teammate without re-reading it.
• Nothing in the diff surprises you. Surprises are bugs you have not found yet.

FAQ

How is prompting an AI coding agent different from prompting ChatGPT?

Chat models answer a single turn; coding agents plan, run tools, and modify files across many steps. That means the input has to look like a spec, not a question. You state the goal, the scope, the files in play, the commands the agent is allowed to run, and what finished looks like. A conversational nudge that works on ChatGPT — "make this better, thanks" — leaves a coding agent without a target to stop at.

What is the best AI coding agent in 2026?

There is no single best — the right choice depends on where you work and how autonomous you want the agent to be. Claude Code is strong when you live in the terminal and want fine-grained control. Cursor and Windsurf are strong for in-editor work with a persistent project context. Devin is positioned for longer, more autonomous task execution. Replit Agent and Bolt.new lean toward scaffolding full applications from a prompt. v0 is narrower — it targets React and Next.js UI generation. Pick based on workflow fit, not benchmark rankings.

Do I need to learn a new prompting style for each tool?

Mostly no. The six skills in this guide — writing specs, defining scope and stop conditions, providing the right context files, writing verifiable acceptance criteria, constraining tool use, and reading output critically — transfer across every agent. What changes between tools is the mechanics: how you pass context, which commands the agent can run, and whether there is a plan step. The prompting discipline stays the same.

Can I use the same prompts across agents?

Mostly yes, with small adjustments. A spec-style prompt with a goal, scope, context, and acceptance criteria will work in Claude Code, Cursor, Aider, and Devin. You may need to rename file references, switch from "run the tests" to the specific test command, or adjust how tool permissions are expressed. The structure — the thing that makes the prompt actually work — carries over.

How long should a good spec be?

As long as it takes to be unambiguous, and no longer. A targeted bug fix can be five lines: one-line goal, one-line failing test reference, a "do not touch these files" list, and the stop condition. A feature spec for a new endpoint might run a page: goal, constraints, input and output schemas, files to read, files to write, acceptance tests, and out-of-scope notes. The test is whether a careful reader could paraphrase what "done" means without guessing.

What about the hallucination risk when agents write code?

Always assume an agent can invent an API, a flag, a package version, or a file path that does not exist. The countermeasures are structural: ask for small commits, require tests to pass before the agent claims completion, diff-review every change before merging, and keep the agent's tool permissions narrow enough that a bad guess does not reach production. Trust the loop — spec, run, test, review — not the agent's self-report.

Should I let the agent run shell commands?

Yes, within a bounded set. Coding agents get dramatically better when they can run the test suite, the type checker, and the linter themselves, because they can close their own feedback loop. The risk is unbounded shell access: deletes, force-pushes, production deploys. A reasonable default is to allow read commands, test and build commands, and git operations on feature branches — and require confirmation for anything that leaves the sandbox.

How do I debug when an agent gets stuck in a loop?

Stop the run and inspect the last three things it did. Loops almost always come from one of three causes: the acceptance criteria were ambiguous so it cannot tell when to stop; it is missing a piece of context (a file, an env var, a test fixture) and keeps guessing; or a tool is failing silently and it cannot see why. Fix the cause, then restart with a tighter scope. Do not keep nudging — you will burn tokens and still not converge.

What goes in a context file vs. the prompt itself?

Put stable, reusable information in context files — architecture notes, naming conventions, the tech stack, the testing strategy. Put task-specific information in the prompt — what to build, which files to touch, what done looks like. A good project CLAUDE.md or equivalent means you do not repeat yourself every prompt; the agent already knows the ground rules.

When should I use a multi-agent setup instead of one agent?

When the work splits cleanly into independent roles with different goals — for example, one agent plans, another implements, a third reviews. Multi-agent helps for complex, long-running work where role separation prevents the single-agent tendency to skip steps. It adds cost and coordination overhead, so use it when the problem really has multiple roles, not just to look sophisticated.