Prompting Coding Agents

Intermediate

Write a job description, not a wish

01 The Concept

Coding agents (Claude Code, Copilot agents, Cursor and friends) don't just answer — they act: they read files, edit, run tests, and keep going. A vague instruction doesn't produce one bad answer anymore; it produces ten confident steps in the wrong direction before anyone checks.

A good agent prompt reads like a job description: the goal, the boundaries (what must not be touched), the definition of done, and how to verify. Front-load constraints — an agent discovers 'don't modify the public API' much more cheaply in its instructions than in your code review. For anything non-trivial, ask for a plan first: 'show me the files you'll change and why, then wait.'

02 Weak vs. Strong

EX 01A refactor with boundaries

Refactor internal/payments for readability. Job spec: GOAL: reduce the 3 near-duplicate charge-retry code paths to one. BOUNDARIES: - Do NOT change any exported function signature (other packages depend on them) - Do NOT add new dependencies - Don't touch internal/payments/webhooks.go — mid-migration by another engineer DEFINITION OF DONE: - `go test ./internal/payments/...` passes with no test edits, except adding coverage for the unified retry path - `git diff --stat` under ~300 lines PROCESS: first reply with a short plan — files you'll change, the unified design, risks. Wait for my OK before editing.

→ Why it works

Goal, boundaries, checkable done-criteria, and a plan gate. Each line prevents a specific expensive failure mode: broken callers, surprise deps, a teammate's merge conflict, a 2,000-line diff.

EX 02A bug fix that must not grow

Fix exactly one bug: users with a + in their email ([email protected]) get 'invalid email' at login. Repro: `curl -s localhost:8080/auth/login -d '{"email":"[email protected]", ...}'` → 400. SCOPE: the fix plus a regression test. Nothing else — no drive-by refactors, no formatting other files, no 'while I was here'. If you find the root cause is bigger than the validator (e.g. it's mangled at ingestion), STOP and report instead of fixing beyond scope. DONE: the curl above returns 200; new test covers + emails; full test suite still green.

→ Why it works

Agents love expanding scope. An explicit repro, a hard scope fence, and a stop-and-report escape hatch keep a one-line fix from becoming a rewrite.

03 Key Points

01State goal + boundaries + definition of done — the agent fills in everything you leave open

02Front-load constraints: protected files, forbidden dependencies, API stability, style rules

03Plan-first for non-trivial work: 'list the files you'll touch and the approach; wait for my OK'

04Definition of done should be checkable: 'tests pass, lint clean, the demo script runs' — not 'works well'

05Persistent instruction files (CLAUDE.md / AGENTS.md) hold the permanent rules so every session starts pre-briefed

06Small scoped tasks with verification beat one giant 'build the feature' prompt

04 Model-Specific Notes

Claude Code reads CLAUDE.md automatically — put permanent rules there (build commands, protected paths, conventions) and per-task specs in the prompt. Its plan mode formalizes the plan-first gate.

05 For Your Role

Same pattern works for any multi-step AI task — trip planning, document overhauls: goal, hard limits ('under $2k, no red-eyes'), definition of done, and 'show me the plan first'.

Next: Long-Context Prompts That Don't Get Lost →