How to Write Prompts That Actually Ship Features
Spec-first prompting for coding agents: how to phrase requests so you get working features instead of plausible-looking code that falls apart on the second click.
Key takeaways
- State the goal, the constraints, and what 'done' means — in that order
- Include real error messages and real examples, not paraphrases
- Ask for a plan first on anything non-trivial
- Tell the agent what NOT to touch
Anatomy of a good coding prompt
A prompt that ships has three parts: the goal (what you want to exist), the context (what already exists and what constraints apply), and the acceptance test (how you'll both know it works). Most bad outcomes trace back to a missing third part — if you can't say what 'working' looks like, the agent can't either.
Goal: Add a waitlist signup form to the homepage.
Context: Next.js app, Tailwind, no database yet — store emails in a `signups` table via the existing Supabase client in lib/db.ts.
Done when: I can submit an email, see a success message, and see the row in Supabase. Invalid emails show an inline error.Paste, don't paraphrase
When something breaks, copy the entire error message — stack trace and all — into the chat. Agents are extremely good at reading tracebacks and extremely bad at guessing from 'it says something about undefined.' The same goes for design intent: paste a screenshot or a link to a site whose layout you want, rather than describing it from memory.
Plan first for anything with moving parts
For features that touch more than one file — auth, payments, data models — ask the agent to lay out its plan before writing code: which files change, what new dependencies appear, what could break. You'll catch wrong assumptions when they're free to fix. Most coding agents have a dedicated plan mode for exactly this.
Set boundaries
Agents are eager. Left unguided, they'll 'improve' code you didn't ask about, rename things, and reformat files, making changes hard to review. Add guardrails to your prompts: 'Only modify the checkout page. Don't touch the auth code. Don't add new dependencies without asking.' Most tools also support a project instructions file (like AGENTS.md or CLAUDE.md) where you can set these rules once.
When output goes sideways, reset — don't argue
If you're three corrections deep and the agent keeps digging, stop. Long troubleshooting threads fill the context with failed attempts, and the agent starts pattern-matching on its own mistakes. Revert to your last commit, start a fresh conversation, and re-state the goal with what you learned: 'Last attempt failed because X. This time, do Y instead.'