Prompting AI Coding Agents Effectively

A strong coding prompt is a compact product specification. It reduces guessing without prescribing code you do not understand.

The five-part prompt

Use this structure:

1. Outcome: describe user-visible behavior.
2. Context: name relevant project facts and files.
3. Constraints: protect the stack, scope, security, and design rules.
4. Acceptance criteria: list observable results and edge cases.
5. Verification: name checks and request evidence.

Example:

Outcome: Add a category filter to the transaction list.

Context: This is a Next.js App Router project using TypeScript, Tailwind,
Supabase, and the existing transaction repository. Inspect before editing.

Constraints: Reuse existing components. Do not add dependencies or change the
database. Preserve keyboard access and the current mobile layout.

Acceptance criteria:
- “All categories” is the default.
- Choosing a category displays only matching transactions.
- The empty result explains how to clear the filter.
- The filter remains selected after a data refresh.

Verification: Run lint, type checking, relevant tests, and describe the manual
browser checks. Report anything you could not run.

Ask for evidence, not confidence

Avoid “make sure it works.” Ask which command ran, its result, and what remains untested. A build passing proves compilation, not correct authorization or good mobile design.

Useful closing instruction:

After implementation, summarize changed files, commands run, results, manual
checks still required, and any assumptions or risks. Do not claim a check passed
unless you ran it and observed a successful result.

Separate exploration from implementation

For unfamiliar code, begin with:

Inspect only. Trace the current flow, identify the smallest change, and propose
a plan. Do not edit files, install packages, run migrations, or deploy.

After reviewing the plan, authorize a bounded step. This prevents an agent from solving a misunderstood problem across twenty files.

Give context efficiently

Point the agent toward source-of-truth files rather than pasting the whole project. Mention installed frameworks, existing design system, data model, and test commands. Paste full error output when debugging, but redact tokens and personal data.

Screenshots are excellent for visual bugs when accompanied by viewport size, expected behavior, and the relevant URL. A screenshot alone does not reveal DOM structure, network failures, or accessibility problems.

Control scope

Say what must not change. For example:

Do not rename public routes, change the database schema, replace the auth
provider, upgrade dependencies, or redesign unrelated pages.

This is especially important because agents often notice adjacent improvements. Capture those as follow-up ideas instead of mixing them into one change.

Use acceptance scenarios

Write criteria as Given/When/Then:

Given a signed-in user with no transactions,
when the dashboard loads,
then it shows a friendly empty state and an “Add transaction” action.

Include unhappy paths: invalid input, unauthorized access, no results, server error, slow network, and repeated clicks. You do not need every edge case in every prompt; include the ones that could break trust or data.

Ask for explanations at the right altitude

“Explain every line” creates noise. Ask:

Explain this change to a non-technical product owner. Describe the data flow,
security boundary, files changed, and why the verification is sufficient. Then
name the two code details I should understand before approving it.

When one detail remains confusing, zoom in on it.

Recovery prompt

When a change fails, do not immediately ask the agent to keep trying randomly:

Stop editing. Show Git status and summarize the current uncommitted changes.
Identify the last verified working commit. Explain whether we should fix forward
or restore specific uncommitted files. Do not run destructive Git commands.

You decide after seeing the evidence. Never approve broad deletion or reset commands without confirming exact targets and recoverability.

Tool-specific context

Codex: Put durable repository conventions and verification commands in AGENTS.md; keep task-specific acceptance criteria in the prompt.

Claude Code: Put durable project guidance in CLAUDE.md or reference a neutral project guide. Avoid filling permanent context with temporary task detail.

Cursor: Use project rules for durable conventions and attach or reference the smallest relevant files. Review the diff before accepting broad Agent changes.

Prompt anti-patterns

“Build me an Uber clone.” No audience, scope, rules, or acceptance criteria.

“Use the best stack.” “Best” depends on platform, budget, team, data, and delivery constraints.

“Fix everything.” No boundary or proof of completion.

“Rewrite it cleanly.” Risks losing behavior without tests.

Pasting a secret. Secrets are not debugging context.

Create a reusable task template

Save this in your notes:

# Outcome

# Current behavior and evidence

# Relevant context

# Constraints / out of scope

# Acceptance criteria

# Verification commands and manual checks

First inspect and plan without editing. State assumptions. Wait for approval.

Completion checklist

• My prompts describe outcomes, not only code instructions.
• I separate inspection, planning, implementation, and verification.
• I include observable acceptance criteria.
• I protect scope and security with explicit constraints.
• I ask for command results and unresolved risks.

Next: Planning an App Before Generating Code