Prompting inside coding agents

TL;DR

Coding agents — Claude Code, Cursor, Aider, Windsurf, Continue — are agents whose tools are read_file, edit_file, run_command, search_code. Their prompts carry more weight than any other kind of prompt in daily use today, because the output isn't a chat reply — it's real code that ships. The craft here has four idioms. The prompt is the spec for the change. A project-level context file supplies house rules to every session: Claude Code's CLAUDE.md, Cursor's .cursor/rules/ files or a shared AGENTS.md, or Aider's CONVENTIONS.md. Plan mode, or "propose-then-apply," separates thinking from acting on high-risk changes. Sub-agents run delegated tasks in parallel and protect the main context window. This lesson names the patterns, so a developer new to coding agents gets the leverage on day one instead of stumbling into it over a month.

🎯 For the AI PM (or coding-agent user)

Why it matters — For developers, this is the highest-productivity prompting surface in the industry right now. For PMs, it is where "vibe coding" turns from demo into product (see TPM for AI products).

What it changes in your decisions — You start treating your CLAUDE.md (or equivalent) as a versioned engineering artifact, not a scratch note. You reach for plan mode on any change touching more than one file. You delegate parallel investigations to sub-agents instead of blocking the main session.

Ask yourself — "Am I prompting this coding agent the way I would write a ticket for a competent contractor — spec, constraints, verification — or the way I would text a friend?"

Risk if ignored — Agent-generated code that compiles, runs, and quietly breaks something else. Or a session that wanders because you never named a success condition, and you don't notice until 45 minutes in.

The mental model

Every arrow here is a prompt-engineering surface. Your prompt is the task. The project context file is the always-on system prompt every session inherits. The tool descriptions are what the agent reads to decide what to do next. The proposed diff is what you review — and the quality of your review depends on how tightly you scoped the prompt.

Pattern 1 — the prompt is the spec

Coding-agent prompts read like small tickets, not chat messages. A weak prompt:

Add caching to the search endpoint.

A strong prompt:

Add an in-memory LRU cache to src/search/handler.py's search() function.

• Cache key: the normalized query string.
• Cache size: 1000 entries. Eviction: LRU.
• Cache TTL: 5 minutes.
• Do not cache when the caller passes no_cache=True.
• Add a unit test in tests/search/test_cache.py covering: cache hit, cache miss, eviction at capacity, TTL expiry, and the no_cache=True bypass.
• Do not touch any other file.

Every line in the strong prompt is a constraint the agent will honor. The "do not touch any other file" line does the most work. It stops the agent from "improving" code you did not ask about.

The rule: prompt as if the agent will do exactly what you wrote and nothing you didn't. Because it will.

Pattern 2 — the project context file is the always-on system prompt

Claude Code reads CLAUDE.md. Cursor reads Project Rules in .cursor/rules/ and also reads AGENTS.md. Cursor's older single .cursorrules file is deprecated. Aider reads CONVENTIONS.md. All of them play the same role: a project-scoped file, checked into git, that ships to every session as part of the system prompt. Tool file names change often, so check your tool's current documentation before you copy a layout.

Keep one limit in mind. These files are guidance, not enforcement. The agent usually follows them, but nothing forces it to. When a rule must never break, such as "never run a command that deletes data," enforce it with permissions or hooks, and use the context file to explain why.

What to put in it:

• What the codebase is. One paragraph. What ships, what stack.
• Layout. Where things live, and one-line notes on why.
• Build/test/lint commands. So the agent can verify its own work.
• House rules. "Prefer editing existing files to creating new ones." "Don't add try/except unless the failure mode is real." "No new dependencies without approval."
• Anti-patterns. Things the codebase has learned the hard way not to do.

What NOT to put in it:

• Task-specific instructions (those belong in the prompt for that task).
• Onboarding text for humans (that belongs in README.md).
• Long philosophical notes (the agent skims for facts, not essays).

Every project's CLAUDE.md becomes a prompt-engineering artifact you version and review like code. A bad CLAUDE.md invisibly degrades every session in that project.

Pattern 3 — plan mode and propose-then-apply

For any change touching more than one file, or any change to unfamiliar code, run the agent in plan mode (Claude Code's plan mode; Cursor's read-only Ask mode before its Agent mode; Aider's /architect). The agent proposes the change without applying it. Mode names change between versions, so check what your tool calls it. You review the plan, redirect if needed, then approve.

The idiom:

• Small, obvious changes: apply mode.
• Anything touching multiple files, config, migrations, or public APIs: plan mode.
• Anything you're not sure how to structure yourself: plan mode with the agent helping you think.

Skipping plan mode on a large change is the coding-agent equivalent of skipping code review. Fast at first. Painful the second time.

Pattern 4 — sub-agents for parallel investigation

Both Claude Code and Cursor let you spawn sub-agents (background tasks, task tool) for work you want to run in parallel without polluting the main session's context. Good uses:

• Investigations. "Find every place logger.warning is called with a hardcoded string" — dispatch to a sub-agent; get a summary back.
• Broad refactors. "Rename foo to bar across the entire test directory, reporting any file it couldn't update automatically."
• Independent tasks. Two unrelated bugs in different subsystems can run as two parallel sessions.

The rule: sub-agents are for tasks whose result you want, not tasks whose process you want to steer. If you need to intervene mid-task, do it in the main session.

Pattern 5 — verification is part of the prompt

The best coding-agent prompts end with a verification clause: "After making the change, run pytest tests/search/ and report the output." "Then run npm run typecheck." "Then show me the diff." The agent runs the check itself and either declares success with evidence or reports the failure. This is the coding-agent equivalent of the acceptance criteria in a PRD.

Without a verification clause, the agent judges its own work on vibes.

Pattern 6 — rule out the two habits of capable agents

Strong coding models have two habits that a short prompt can prevent.

• Over-engineering. The agent adds extra files, helper functions, and options you did not ask for. Add a scope rule to the prompt or the context file: "Only make changes that are directly requested. Do not refactor surrounding code, add comments to code you did not change, or build in flexibility for hypothetical future needs."
• Writing to the test. The agent makes the tests pass by hard-coding the expected values, or by writing a special case for the test inputs. Add: "Write a general solution that works for all valid inputs, not only the test cases. If a test looks wrong, or the task cannot be done, tell me instead of working around it."

Both rules are fixes for behaviour seen on recent models. Re-test them when you change model, since a later model may need less of this.

A third habit is a plus, not a problem. Agents often write small scratch files to test an idea. If you do not want leftovers, add: "Delete any temporary files you create before you finish."

Tradeoffs

• Speed vs. safety. Apply mode is fastest. Plan mode is safest. Match to change size.
• Context depth vs. CLAUDE.md bloat. Everything in the context file costs tokens on every session. Keep it tight; move anything task-specific to prompts.
• Sub-agent parallelism vs. coordination cost. Two parallel sub-agents beat two sequential ones on wall-clock time; they lose the shared context that sequential work preserves.
• Autonomy vs. review. More autonomous agents ship faster and hide more bugs in what they produced. High-autonomy sessions need higher-quality prompts and more careful review.

Failure modes

• The one-liner ticket. "Fix the bug" with no repro, no file names, no acceptance criteria. Agent guesses; guess is wrong; you spend twice as long fixing the guess as you would have fixing the bug.
• Missing CLAUDE.md. Every session re-learns the project from scratch. Every session makes the same mistakes.
• A hard rule left as guidance. "Never touch the production config" sits in the context file, and one session ignores it. Enforce must-not rules with permissions or hooks.
• Green tests, wrong code. The agent hard-codes values so the suite passes. The verification clause reports success. Read the diff, not only the test output.
• Skipping plan mode on a large change. Agent commits to a wrong structure by the third file; unwinding costs more than proposing would have.
• No verification clause. Agent reports "done"; you find the tests were never run half an hour later.
• Sub-agent spam. Dispatching sub-agents for tasks small enough to just do, because it feels productive. Each sub-agent has spin-up cost. Match to task size.
• Prototype code shipped as production code. Vibe-coded code demos beautifully and lacks error handling, tenancy, and tests. Ship the prototype through the same eval-driven pipeline as any other code.

Practitioner checklist

• Does my current prompt read like a ticket a competent contractor could pick up, or like a text message?
• Does this project have a CLAUDE.md (or equivalent) with layout, commands, and house rules — kept in git, reviewed like code?
• For any change touching more than one file: am I using plan mode, or am I trusting the agent to structure it in one shot?
• For investigations that would fill my main context: am I dispatching them to sub-agents?
• Does my prompt end with a verification clause — a test, a typecheck, a diff review — so "done" has evidence, not vibes?
• Have I told the agent to keep changes minimal and to write general solutions, not code that only passes the tests?
• Is every "must never" rule enforced by permissions or hooks, not only written in the context file?

Related lessons

• Prompting for tools and agents
• When prompts fail: the diagnostic playbook
• TPM for AI products — the "vibe coding" section covers the PM-side risk of shipping prototype-grade agent-generated code.
• AI agents — the scaffolding underneath these tools.