# How to write prompts for AI coding agents

URL: https://agentvera.dev/en/blog/prompts-for-ai-coding-agents/ · Published: 2026-10-27

How to write prompts for AI coding agents: bad vs good examples, giving files and constraints, asking for a plan, splitting tasks, verification and reusable prompts.

**In short:**

- A good prompt for a coding agent names the goal, the files to start from, the constraints and how to check the result. Vague prompts get vague code.
- For anything bigger than a small fix, ask for a plan first, split the work into steps you can review, and tell the agent which command proves it is done.
- Rules you repeat go in CLAUDE.md, AGENTS.md or GEMINI.md; workflows you repeat become skills or custom commands, so each prompt can stay short.

**A good prompt for an AI coding agent says four things: what you want, where to start, what must not change, and how to tell that it worked.** Most bad results come from leaving out one of those, not from the wrong wording. The agent can read your code, run commands and edit files, so the job of the prompt is to point that work in the right direction and give it a finish line.

This guide shows bad and good prompts side by side, then covers context, plans, splitting work, verification and where to keep prompts you reuse. The examples use Claude Code and Codex CLI, but the habits apply to Gemini CLI and any other [coding agent](/en/glossary/coding-agent/ "What is a coding agent").

## Why prompting an agent is different from prompting a chatbot

A chatbot only has your message. A coding agent has your whole repository, a shell and a loop: it reads files, makes a change, runs something, looks at the result and tries again. That changes what a prompt needs to do:

- **You don’t need to paste code.** Point to files and let the agent read them.
- **You do need to set limits.** An agent that can edit anything may edit things you didn’t mean.
- **You need a stopping rule.** Without one, the agent decides by itself when the work is good enough, and its bar may not be yours.

Every extra file the agent reads also fills its [context window](/en/glossary/context-window/ "What is a context window"). A focused prompt keeps the agent focused and the session cheaper.

## Bad prompt vs good prompt

Here is a typical first attempt:

```text
fix the login bug
```

The agent has to guess which bug, where it lives and what “fixed” means. It may change the wrong file, rewrite a function that was fine, or “fix” the symptom by catching the error.

Here is the same request written for an agent:

```text
Users with an email that has uppercase letters can't log in: the API returns
401 even with the right password. Signup stores emails as typed; login looks
them up as typed too, so "Ana@x.com" and "ana@x.com" don't match.

Start in src/auth/login.ts and src/auth/signup.ts.
Normalize emails to lowercase on both signup and login. Don't change the
database schema in this task, and don't touch the session code.

Done when: a new test in tests/auth.test.ts logs in with "Ana@X.com" after
signing up with "ana@x.com", and `pnpm test` passes. Show me the diff.
```

It’s longer, but every line saves the agent a guess. Here is what each part does:

| Part | Example | Why it helps |
| --- | --- | --- |
| Symptom | “returns 401 even with the right password” | The agent knows what to reproduce |
| Cause, if you know it | “stores emails as typed” | Skips a long search |
| Starting files | `src/auth/login.ts` | Less reading, fewer wrong guesses |
| Constraints | “don’t change the database schema” | Keeps the change small and safe |
| Done criteria | a named test plus `pnpm test` | A finish line the agent can check |

You don’t always know the cause. That’s fine: say so, and ask the agent to find it before fixing it. “Find out why X happens and explain it before changing anything” is a strong prompt by itself.

## Give context, not essays

The most useful context is concrete and checkable. In rough order of value:

1. **File paths and symbols.** `src/billing/invoice.ts`, `calculateTax()`. In Claude Code and Codex you can type `@` to pick a file and attach it.
2. **Error output.** Paste the exact stack trace or failing test output, not a summary of it.
3. **Constraints.** Libraries you use or don’t, folders to leave alone, APIs that must stay backward compatible.
4. **Examples in the codebase.** “Follow the pattern in `src/routes/users.ts`” beats a paragraph describing the pattern.
5. **The why.** One sentence on the user-facing goal helps the agent make reasonable choices you didn’t spell out.

What to leave out: long history of the project, your opinions on unrelated code, and instructions that apply to every task. Those last ones belong in a project file, covered below.

Screenshots help for UI work. Claude Code and Codex both accept images; Codex also takes `codex --image path/to/file.png` on the command line.

## Ask for a plan first

For anything bigger than a small fix, separate thinking from doing. Ask the agent to read the code and propose a plan, review it, then let it implement.

- **Claude Code:** press Shift+Tab until the status bar shows plan mode, type `/plan` before a single prompt, or start with `claude --permission-mode plan`. In plan mode Claude reads and proposes but doesn’t edit. [Claude Code plan mode](/en/blog/claude-code-plan-mode/ "Claude Code plan mode") covers the details.
- **Codex CLI:** `/plan` asks Codex to plan before implementing. You can also start a read-only session with `/permissions` set to Read Only.
- **Any agent:** say it in words: “Don’t edit anything yet. Read the relevant files and give me a numbered plan with the files you’ll change.”

A planning prompt that works well:

```text
We need to add CSV export to the reports page.
Don't write code yet. Read src/reports/ and the existing PDF export in
src/export/pdf.ts, then give me:
1. the files you will add or change,
2. how the CSV is built and streamed,
3. what you'll test,
4. anything you're unsure about.
```

Reading the plan takes a minute and catches the expensive mistakes: the wrong folder, a new dependency you don’t want, a migration you didn’t expect. If the plan is wrong, correct it in plain words (“use the existing `toRows()` helper instead of a new parser”) and ask for a revised plan.

## Split big tasks into steps

Agents do best on tasks you could review in one sitting. A prompt like “build the billing system” produces a large diff that’s hard to check and hard to undo. Break it up:

```text
Step 1 of 4: add the Invoice model and migration only.
No API routes or UI yet. Run the migration on the dev database and the
model tests, then stop and show me the diff.
```

Then step 2 is the API, step 3 the UI, step 4 the emails. After each step you review, commit, and start the next one. Two habits make this work:

- **Commit between steps.** A clean commit is a checkpoint. If step 3 goes wrong, you reset to the end of step 2 instead of untangling a mixed diff. [Undoing Claude Code changes](/en/blog/undo-claude-code-changes/ "Undo Claude Code changes") lists the options.
- **Fresh context for unrelated work.** Use `/clear` in Claude Code or `/new` in Codex when you switch topics. Old context costs tokens and pulls the agent back toward the previous task.

Independent steps can also run in parallel, each agent in its own [git worktree](/en/blog/git-worktree-parallel-agents/ "Git worktrees for parallel agents") so they don’t overwrite each other’s files.

## Tell the agent how to verify

“Make it work” lets the agent decide what working means. A verification instruction moves that decision back to you. Good ones are commands with a clear result:

```text
Done when:
- `pnpm test tests/export.test.ts` passes, including a new test for an
  empty report,
- `pnpm typecheck` has no errors,
- GET /reports/42/export.csv returns a header row and one row per entry.
Paste the command output at the end.
```

A few patterns that raise the bar:

- **Test first.** “Write a test that reproduces the bug, run it and show me it fails. Then fix the code until it passes.” This proves the test actually covers the bug. More in [writing unit tests with AI](/en/blog/write-unit-tests-with-ai/ "Write unit tests with AI").
- **Ask for evidence, not claims.** “Paste the output” is harder to fake than “confirm it works”.
- **Name what must not break.** “The existing tests in `tests/auth/` must still pass.”
- **Forbid the shortcuts.** “Don’t skip or delete tests, and don’t add `any` casts to silence type errors.” Agents under pressure to make a check pass sometimes take these routes.

Then read the diff. A second model reviewing the change catches a lot; see [AI code review](/en/blog/ai-code-review/ "AI code review").

## Prompts that go wrong, and fixes

| Prompt | What usually happens | Better |
| --- | --- | --- |
| “Clean up this file” | Large rewrite, renamed functions, broken imports elsewhere | “Extract the parsing in `parse.ts` into its own function; keep the public API unchanged” |
| “Add tests” | Shallow tests that assert the code does what it does | “Add tests for empty input, a 10 MB file and a malformed header; each must fail if I remove the check on line 40” |
| “Make it faster” | Random micro-optimizations | “The `/search` endpoint takes 2 s for 10k rows. Profile it, tell me where the time goes, then propose a fix” |
| “Use best practices” | Whatever the model thinks is best this time | Name the practice: “use the repository pattern from `src/db/users.ts`” |
| A list of ten unrelated fixes | Half done, context full by item six | One task per prompt, or ten tasks in a queue |

## Make prompts reusable

If you type the same instruction in every session, move it out of your prompts.

### Project rules: CLAUDE.md, AGENTS.md, GEMINI.md

Each agent reads a project instruction file at the start of a session: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex (and several other agents), `GEMINI.md` for Gemini CLI. Put commands and conventions there, short and specific:

```markdown
## Commands
- Test: pnpm test (run before saying a task is done)
- Typecheck: pnpm typecheck

## Rules
- Don't edit files in src/generated.
- Don't add dependencies without asking.
- New API routes need a test in tests/routes/.
```

Now “run the tests before you say you’re done” is part of every prompt without you typing it. `/init` in Claude Code, Codex and Gemini CLI generates a first draft. [CLAUDE.md and AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") explains how to keep one set of rules for several agents.

### Repeated workflows: skills and custom commands

For a task you repeat now and then, such as a release, a migration or a review checklist, write it once as a skill or custom command and call it by name.

**Claude Code** uses skills: a folder with a `SKILL.md` file, in `.claude/skills/<name>/` for the project or `~/.claude/skills/<name>/` for you. The folder name becomes a command, and `$ARGUMENTS` receives whatever you type after it:

```markdown
---
name: fix-issue
description: Use when the user asks to fix a GitHub issue by number.
---
Fix GitHub issue $ARGUMENTS.
1. Read the issue with `gh issue view $ARGUMENTS`.
2. Write a failing test that reproduces it.
3. Fix the code until the test passes, then run `pnpm test`.
4. Summarize the change in two sentences.
```

Now `/fix-issue 123` runs the whole prompt. Older Markdown files in `.claude/commands/` still work the same way, but Anthropic’s docs recommend skills for new work because a skill folder can also hold scripts and reference files. Claude also loads a skill on its own when your request matches its description. More in [Claude Code skills](/en/blog/claude-code-skills/ "Claude Code skills").

**Codex** reads skills from `.agents/skills` in a project and `~/.codex/skills` for you, in the same `SKILL.md` format.

**Gemini CLI** uses TOML custom commands in `.gemini/commands/` (project) or `~/.gemini/commands/` (user). `{{args}}` is replaced by what you type after the command, and subfolders become namespaces, so `git/commit.toml` is `/git:commit`:

```toml
description = "Fix a GitHub issue by number"
prompt = """
Fix GitHub issue {{args}}. Write a failing test first,
then fix the code and run the test suite.
"""
```

A good rule of thumb: rules that always apply go in the project file, workflows you use sometimes go in skills, and the prompt itself only carries what is specific to today’s task.

## A prompt template you can copy

```text
Goal: <one sentence, user-facing>
Context: <symptom, error output, what you already know>
Start in: <files or folders>
Constraints: <what must not change, libraries to use or avoid>
Plan first: <yes/no — if yes, don't edit until I approve>
Done when: <commands that must pass, behaviour to show>
Report: <diff, command output, open questions>
```

Not every line is needed every time. For a typo fix, “Goal” is enough. For a new feature, fill them all.

## Prompting agents in AgentVera

AgentVera is a desktop app for macOS, Windows and Linux that runs Claude Code, Codex, Gemini CLI and other CLI agents side by side in real terminals. The prompts are the same; a few features take over the repetitive parts:

- **[Verify](/en/features/verify/ "AgentVera Verify"):** the done criteria you write in your message are pulled out as acceptance criteria. When the agent finishes its turn, a separate verifier reads the diff, runs the allowed test commands and marks each criterion passed or failed with evidence. It can’t edit files. Verify is on the Pro and Team plans.
- **[Code review](/en/features/code-review/ "Code review"):** when a turn ends, a second Claude model reviews what the agent wrote, and the findings can go straight back to the agent.
- **[Send to agent](/en/features/send-to-agent/ "Send to agent"):** send a terminal error, a diff, a log or a line of code to an agent with ⌘⇧L instead of copying and pasting it into your prompt.
- **[Skill gallery](/en/features/skill-gallery/ "Skill gallery"):** create, edit and turn on or off Claude Code and Codex skills in one list, and install shared skills after a security scan.
- **[Workspace](/en/features/workspace/ "Workspace"):** a grid of agents per project, so you can give each split-up step its own agent and worktree.

[Download AgentVera](/en/download/ "Download AgentVera") and try your next prompt with these alongside.

## Wrapping up

Write prompts like a ticket for a capable colleague who just joined: the goal, where to look, what to leave alone, and how you’ll judge the result. Ask for a plan when the task is big, split it into steps you can review, and always give a command that proves it’s done. Move what you repeat into `CLAUDE.md`, `AGENTS.md` or a skill. The same habits matter even more when the agent touches a database; [writing SQL and migrations with AI](/en/blog/write-sql-with-ai/ "Write SQL with AI") applies them to schemas and migrations.

## Frequently asked questions

**How long should a prompt for a coding agent be?** As long as it takes to state the goal, the starting files, the constraints and the done criteria, and no longer. For a small fix that is two or three lines. For a feature it is usually a short paragraph plus a list. Background that applies to every task belongs in CLAUDE.md or AGENTS.md, not in each prompt.

**Should I ask the agent for a plan before it writes code?** Yes, for anything that touches more than a couple of files or that you can’t describe precisely. In Claude Code use plan mode (Shift+Tab or /plan), in Codex use /plan. Read the plan, correct it, then let the agent implement. For a one-line fix a plan is overhead.

**Do prompt tricks like “you are a senior engineer” help coding agents?** Much less than concrete information does. A role line costs little, but the agent gains far more from the file to start in, the command that runs the tests and the behaviour you expect. Spend your words on facts about the task.

**Where should I keep prompts I use again and again?** Project rules go in CLAUDE.md (Claude Code), AGENTS.md (Codex and other agents) or GEMINI.md (Gemini CLI). Repeated workflows become skills: .claude/skills/<name>/SKILL.md in Claude Code, .agents/skills in Codex. Gemini CLI uses TOML custom commands in .gemini/commands.

**How do I stop a coding agent from saying a task is done when it is not?** Give it a check it must run, such as a test command, a build or a curl request, and ask it to paste the output. Ask for a new test that fails before the change and passes after it. Then review the diff yourself or have a second agent review it.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/