AI Coding Prompt Template That Follows Specs
AI coding assistants fail when the prompt treats scope as optional. The right prompt design turns your spec into hard boundaries and verifiable outputs.
Quick answer
Anchor AI generation to spec constraints: in-scope files, immutable contracts, acceptance criteria, required tests, and forbidden changes. Require structured output with changed files, evidence, and risk notes.
Prompt blocks you should always include
- Task identity: spec ID and target behavior.
- Scope boundary: allowed files and forbidden paths.
- Contract boundary: API/DB fields that must not change.
- Verification: tests to add or update, plus pass criteria.
- Response format: diff summary, risks, and unresolved questions.
Production-ready prompt template
# AI Implementation Prompt
You are implementing SPEC-123.
## Objective
Implement only the behavior defined in SPEC-123 acceptance criteria.
## In Scope
- /services/order/*
- /controllers/order/*
- /tests/order/*
## Out of Scope
- response schema changes
- DB column rename/remove
- auth middleware changes
## Immutable Contracts
- POST /v1/orders response fields: orderId, status, createdAt
- error envelope shape: { code, message, traceId }
## Acceptance Criteria
1) ...
2) ...
3) ...
## Required Verification
- add/update integration tests for success, validation error, conflict
- run test command: npm test -- order
## Required Output Format
- Changed files with 1-line reason each
- Test evidence (commands + result)
- Risks and follow-up tasks
Common prompt mistakes
- Asking for "best solution" without defining constraints.
- Not declaring forbidden files or contract boundaries.
- Accepting output without test evidence.
- Skipping rollback notes for schema-affecting changes.
These mistakes produce confident-sounding but unsafe code suggestions — especially in multi-module repositories.
Review checklist for AI-generated diffs
- Does every change map to a specific acceptance criterion?
- Were immutable contracts preserved?
- Are added tests sufficient for error and permission paths?
- Is there any hidden scope expansion in the diff?
Run this before merging, even when the AI output looks correct at first glance.
Prompt variants by task type
The production-ready template above works for new feature implementation. Different task types require adjusted constraints. A refactor prompt, a bug fix prompt, and a new feature prompt share the same structure but differ in which boundaries matter most.
# Refactor prompt variant You are refactoring SPEC-REF-44 (extract payment validation service). ## Objective Move validation logic from OrderController to a standalone PaymentValidator class without changing any observable behavior. ## Behavioral Constraint All existing tests must pass without modification. No new behavior is being introduced. External callers must see identical inputs, outputs, and error codes. ## In Scope - /controllers/order.js (extraction only) - /services/ (new PaymentValidator class) - /tests/ (update imports only, no assertion changes) ## Forbidden - Any change to API response shape - Any logic change inside the validation rules - New dependencies not already in package.json --- # Bug fix prompt variant You are fixing BUG-291: duplicate invoice created on payment retry. ## Root Cause (Known) InvoiceService.create() is called before idempotency check. Move idempotency check before the create() call. ## In Scope - /services/invoice.js (check order, one-line reorder) - /tests/invoice/ (add regression test for duplicate retry case) ## Forbidden - No changes to invoice schema or response fields - No changes to payment retry logic outside InvoiceService - Do not alter existing tests; only add the regression case
The refactor prompt's critical constraint is behavioral equivalence — all observable behavior must be unchanged. The bug fix prompt's critical constraint is minimal scope — only the lines required to fix the root cause. Both constraints prevent AI tools from expanding scope to "improve" adjacent code while ostensibly fixing the stated problem.
What AI gets wrong without spec constraints
AI coding tools fail in predictable ways when prompts do not establish boundaries. Understanding the failure modes makes the value of the constraint structure concrete — these are not hypothetical risks, they are the observed behaviors of production AI coding tools when given underspecified prompts.
Given "implement user notification preferences," an unconstrained AI will often add a notification history table, a preference audit log, and a bulk-reset endpoint — none of which were in scope. Each addition is individually reasonable; collectively they triple the implementation footprint. An AI asked to "clean up the API response" will frequently rename fields, remove redundant fields, and normalize formats — all of which break consumers that were not told about the change.
Without explicit acceptance criteria, AI tools write tests that verify the implementation's actual behavior. If the implementation has a bug, the tests verify the bug. The tests pass; the spec was never satisfied. AI-generated code for an "update email" endpoint will handle the happy path and the validation error. It will rarely handle the concurrent update race, the idempotent retry, and the session invalidation behavior — unless those scenarios are listed explicitly in the prompt.
The prompt template applies the same principle to AI tools that applies to human implementation: the more precisely the spec defines the expected behavior, the fewer decisions are made silently during coding.
Reviewing AI output against your spec
AI-generated code requires a structured review pass that goes beyond reading the diff. The review must verify that the implementation satisfies the spec — not just that the code looks reasonable. These two checks are not equivalent. Code can look correct and violate the spec simultaneously.
- Map each acceptance criterion to a specific test. If a criterion has no test, it was not implemented — regardless of whether the feature appears to work manually.
- Check that the immutable contracts section of the prompt was honored. Grep the diff for changes to response field names, error shapes, and auth middleware. AI tools frequently make these changes incidentally when optimizing adjacent code.
- Review the "Out of Scope" section against the changed files list. If any file outside the in-scope list was modified, investigate before merging. The change may be necessary — but it should be explicit, not accidental.
- Run the tests with the AI-generated code before reading the code. If tests fail, read the failing assertions to understand what the AI got wrong. Reviewing the code first creates a bias toward accepting the implementation's behavior as correct.
The review checklist in the template ("Does every change map to a specific acceptance criterion?") is the primary gate. If any change cannot be traced to a criterion, it is either scope expansion — which requires review — or dead code — which should be removed.
Use these templates
Related articles
Editorial note
This guide covers AI Coding Prompt Template That Follows Specs for spec-first engineering teams. Examples are illustrative scenarios, not production code.
- Author details: Daniel Marsh
- Editorial policy: How we review and update articles
- Corrections: Contact the editor