Catalog My learning Blog
AI-Assisted Coding Course: Agentic Development in 30 Days · Phase 2 · Lesson 8 · 5 min read

How to Prompt AI Coding Agents: Specs, Not Wishes

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Bug Report Prompt That Leads to a Diagnosis
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Write task prompts that produce mergeable changes on the first attempt: state the outcome, constraints, scope and verification, point to the code, ask the agent to surface questions and assumptions, and size tasks so the result is reviewable.

Concept Explanation

A wish describes what you want in a sentence and hopes the agent guesses the rest: "add dark mode", "fix the login bug", "make the importer faster". The agent will produce something, and the less you specified, the more decisions it made on your behalf. Some of those decisions will be wrong, and you discover them only in review, or in production.

A spec states the decisions that matter. It does not need to be long; it needs to cover four things. The outcome: what should be true when the task is done, from the user's or system's point of view. The constraints: what must not change, which approach or library to use or avoid, performance or security requirements. The scope: which parts of the codebase are in play and what is explicitly out of scope. The verification: how the agent should prove it worked, usually specific tests, commands or a manual check. Pointing at the relevant files and a similar example (Day 6) completes the picture.

Two techniques catch misunderstandings before code is written. First, ask the agent to state its assumptions and questions before starting; a good agent will notice ambiguities you missed, such as whether "export" should include archived records. Second, for anything non-trivial, ask for a plan first and approve it (Day 9). Both cost seconds and save rework.

Bug reports deserve their own shape. Give the observed behavior, the expected behavior, exact reproduction steps or a failing test, relevant logs or error messages, and what you have already ruled out. Ask the agent to reproduce the bug before fixing it, and to explain the root cause in its summary. "Fix the login bug" invites a guess; "users with plus signs in their email get 401 after the October upgrade; here is the log line; write a failing test first" invites a diagnosis.

Size matters as much as clarity. A task that produces a 2,000-line diff across thirty files cannot be reviewed properly, no matter how good the prompt was. Break large work into steps that each produce a coherent, testable change of a few hundred lines at most: first the data model and migration, then the service logic with tests, then the API, then the UI. Each step gets its own short spec and its own commit.

Finally, write prompts in plain, direct language. Modern models follow instructions closely, so say what you want rather than shouting with capital letters or threatening. Explaining why a constraint exists, such as "never log request bodies because they contain card numbers", helps the agent apply it correctly in situations you did not list.

ElementWishSpec
Outcome"Add dark mode""Theme follows system setting with a toggle in Settings that persists per user"
Constraints(none)"Use existing CSS variables in tokens.css; no new dependencies"
Scope(implied: everything)"apps/web only; email templates out of scope"
Verification(none)"Visual test for both themes; pnpm test and lint pass"
Questions(none)"List assumptions and questions before you start"

Worked Example: A Bug Report Prompt That Leads to a Diagnosis

This prompt gives the agent everything needed to find the real cause instead of patching the symptom, and requires a failing test first.

Code
Bug: users whose email contains "+" (e.g. ana+shop@example.com) get 401 on login
since the release on 2026-10-02. Others can log in.

Observed: POST /api/login returns 401 for these users. Log line:
  auth.login: no user for email "ana shop@example.com"
Expected: login succeeds as before.

Reproduce: the seeded user plus@example.test has the address user+1@example.test.
What I ruled out: passwords are correct (reset worked); the users exist in the DB.

Please:
1. Write a failing test in tests/auth/login.test.ts that reproduces this.
2. Find the root cause (the log suggests "+" becomes a space somewhere).
3. Fix it at the root, not by special-casing "+" in the login handler.
4. Run pnpm test -- tests/auth and pnpm typecheck.
5. In your summary, explain the root cause and which commit introduced it (use git log).

With the log line and the ruled-out causes, the agent quickly finds that a new middleware decodes the form body as URL-encoded, turning "+" into a space, and fixes the parser rather than the symptom.

A wish leaves the decisions to the agent. A spec states the outcome, constraints, scope and verification, points to relevant code, and asks the agent for assumptions or a plan before work begins.
A wish leaves the decisions to the agent. A spec states the outcome, constraints, scope and verification, points to relevant code, and asks the agent for assumptions or a plan before work begins.

Real-World Examples

  • Anthropic's Claude Code best practices advise being specific in instructions, giving the agent a way to verify its work, and asking it to explore and plan before coding, noting that vague prompts lead to more course corrections.
  • GitHub's guidance for assigning issues to Copilot's coding agent recommends writing issues as you would for a teammate, with clear scope, acceptance criteria and pointers to relevant files, because the agent works from the issue text alone.
Key TakeawaysA vague wish leaves the important decisions to the coding agent, while a written spec means you make those decisions yourself first. State the outcome, constraints, scope and verification, point to relevant code and examples, and ask for assumptions or a plan before work starts. Report bugs with observed and expected behavior, reproduction, logs and ruled-out causes, and require a failing test first. Keep each task small enough to review, and explain the reasons behind constraints.

Review Questions & Answers

The outcome to achieve, the constraints to respect, the scope of what may and may not change, and how the result will be verified.

It surfaces ambiguities and misunderstandings before any code is written, when correcting them costs seconds instead of a rework cycle after review.

The test proves the agent reproduced the actual bug, gives objective feedback on whether the fix works, and prevents regressions afterwards.

The agent can apply the underlying principle to situations the prompt did not list, for example avoiding logging sensitive data in a new code path, not only the exact case you described.