In the previous post, I made the case that specification is the highest-leverage skill in AI-driven development. A precise specification produces better output, requires less iteration, and surfaces ambiguity before it becomes a bug.
But writing detailed specifications from scratch is cognitively demanding. You must simultaneously consider functional requirements, constraints, context, edge cases, and integration points. Holding all of this in your head while also thinking about the actual problem you are trying to solve is exhausting.
Templates solve this problem. A specification template is a reusable structure that prompts you to provide the information AI needs. Instead of remembering what to include, you fill in sections. Instead of inventing structure, you follow a proven format.
This post provides a library of specification templates for common development tasks. Each template is complete enough to use immediately and annotated with guidance on customization. By the end, you will have practical tools that make specification-first development sustainable.
Why Templates Matter
Templates provide three benefits that compound over time.
Consistency. When every developer on a team uses the same template structure, specifications become predictable. Code reviewers know where to find constraint information. New team members can read specifications without learning idiosyncratic formats. The AI receives consistently structured input, which improves output consistency.
Completeness. A well-designed template includes sections for everything that matters. You cannot forget to specify error handling if the template has an error handling section staring at you. Templates encode the lessons of past omissions. Every time a missing specification element caused problems, that element gets added to the template.
Reduced cognitive load. Writing a specification becomes a matter of filling in sections rather than inventing structure. This frees mental energy for the actual thinking: what should this code do, what constraints apply, what could go wrong. The template handles the meta-question of what to specify so you can focus on the object-level questions.
Teams that adopt specification templates report that specifications take less time to write, not more. The template eliminates the blank-page problem and provides momentum that carries through to completion.
Template Structure Overview
Every template in this library follows a common structure with five core sections:
- Purpose: A one or two sentence summary of what the code should accomplish. This orients the AI and serves as a check that you understand your own goal.
- Requirements: The functional specifications. Inputs, outputs, behaviors, transformations. What the code must do.
- Constraints: The boundaries. Technology choices, performance requirements, security requirements, style requirements. What rules the code must follow.
- Context: The environment. Existing patterns, interfaces, dependencies, examples from the codebase. Where the code lives.
- Edge Cases and Errors: The exceptional paths. What happens with invalid input, boundary conditions, failure scenarios. How the code should behave when things go wrong.
Some templates add domain-specific sections. An API template includes request/response formats. A UI component template includes state management. But the five core sections appear in every template.
Template: API Endpoint
Use this template when specifying a REST API endpoint, GraphQL resolver, or similar request handler.
## API Endpoint Specification
### Purpose
[One sentence: what does this endpoint do and why does it exist?]
### Endpoint Details
- Method: [GET/POST/PUT/PATCH/DELETE]
- Path: [/api/v1/resources/{id}]
- Authentication: [Required/Optional/None, specify method]
- Authorization: [What permissions are required?]
### Request
- Path parameters: [List with types and validation rules]
- Query parameters: [List with types, defaults, validation rules]
- Request body: [JSON schema or TypeScript interface]
- Headers: [Any required custom headers]
### Response
- Success (200/201): [JSON schema or TypeScript interface]
- Error responses:
- 400 Bad Request: [When and what body]
- 401 Unauthorized: [When and what body]
- 403 Forbidden: [When and what body]
- 404 Not Found: [When and what body]
- 422 Unprocessable Entity: [When and what body]
- 500 Internal Error: [What body, what gets logged]
### Business Logic
[Step-by-step description of what the endpoint does]
1. Validate input
2. Check authorization
3. [Domain-specific steps]
4. Return response
### Constraints
- Performance: [Expected latency, throughput requirements]
- Rate limiting: [If applicable]
- Idempotency: [For POST/PUT, is it idempotent?]
- Caching: [Cache headers, invalidation rules]
### Context
- Related endpoints: [Links or descriptions]
- Database tables: [What tables are read/written]
- External services: [What services are called]
- Example similar endpoint: [Paste code or link to existing endpoint that follows the right patterns]
### Edge Cases
- [Empty result set]
- [Maximum page size]
- [Concurrent modification]
- [Partial failure scenarios]Customization guidance: For internal APIs, you may simplify authentication and authorization sections. For public APIs, expand the error response section with user-friendly messages. For high-throughput endpoints, add detailed performance constraints.
Template: Data Transformation Function
Use this template when specifying a function that transforms data from one format to another, processes collections, or performs calculations.
## Data Transformation Specification
### Purpose
[What data goes in, what data comes out, why is this transformation needed?]
### Function Signature
- Name: [function_name]
- Parameters:
- [param_name]: [type] - [description, valid values]
- Returns: [type] - [description]
- Raises/Throws: [list of exceptions with conditions]
### Transformation Rules
[Precise description of how input maps to output]
- [Rule 1: when X, output Y]
- [Rule 2: when A, output B]
- [Default behavior when no rules match]
### Examples
Input: [concrete example]
Output: [expected result]
Input: [edge case example]
Output: [expected result]
### Constraints
- Performance: [Time complexity requirements, e.g., must be O(n)]
- Memory: [Space constraints, streaming requirements]
- Immutability: [Should input be modified or preserved?]
- Thread safety: [Concurrent access requirements]
### Context
- Called by: [What code calls this function?]
- Calls: [What other functions does this use?]
- Similar function: [Example from codebase]
### Edge Cases and Errors
- Empty input: [Return empty collection / raise error / return default]
- Null/None values: [How to handle]
- Invalid input: [Validation approach and error messages]
- Overflow/underflow: [For numeric operations]Customization guidance: For simple transformations, the examples section may be sufficient without detailed transformation rules. For complex business logic, expand the transformation rules into a comprehensive specification. For performance-critical code, add benchmarking requirements.
Template: UI Component
Use this template when specifying a React component, Vue component, or similar UI element.
## UI Component Specification
### Purpose
[What does this component display? What user need does it serve?]
### Component Interface
- Name: [ComponentName]
- Props:
- [propName]: [type] - [required/optional] - [description]
- Events/Callbacks:
- [onEvent]: [signature] - [when fired]
- Slots/Children: [If applicable]
### Visual Requirements
- Layout: [Description or link to design]
- Responsive behavior: [Mobile, tablet, desktop variations]
- States:
- Default: [description]
- Loading: [description]
- Empty: [description]
- Error: [description]
- Disabled: [description]
### Interaction Behavior
- [Click behavior]
- [Hover behavior]
- [Focus behavior]
- [Keyboard navigation]
### State Management
- Internal state: [What state does the component manage?]
- External state: [What state comes from props/context/store?]
- State transitions: [What causes state changes?]
### Constraints
- Accessibility: [ARIA requirements, screen reader behavior]
- Performance: [Render optimization, virtualization needs]
- Browser support: [Specific requirements]
- Dependencies: [Allowed libraries, prohibited libraries]
### Context
- Design system: [Link to design system, component library]
- Similar component: [Example from codebase]
- Parent components: [Where is this component used?]
### Edge Cases
- [Very long text content]
- [Missing optional props]
- [Rapid user interaction]
- [Network failure during async operations]Code language: PHP (php)Customization guidance: For design system components, expand the visual requirements with design tokens and spacing specifications. For complex interactive components, add a state machine diagram or description. For form components, add validation and submission handling sections.
Template: Validation Logic
Use this template when specifying validation rules for user input, API payloads, or data integrity checks.
## Validation Specification
### Purpose
[What is being validated and why?]
### Input
- Type: [What type of data is being validated?]
- Source: [Where does this data come from?]
### Validation Rules
| Field | Rule | Error Code | Error Message |
|-------|------|------------|---------------|
| [field] | [rule description] | [CODE] | [User-facing message] |
### Rule Details
[For complex rules, provide detailed specifications]
Rule: [Rule name]
- Condition: [When does this rule apply?]
- Logic: [How is validity determined?]
- Examples:
- Valid: [example]
- Invalid: [example]
### Return Value
- Success: [What is returned when valid?]
- Failure: [Structure of validation errors]
### Constraints
- Fail-fast vs. collect-all: [Stop at first error or return all errors?]
- Sanitization: [Should input be sanitized as well as validated?]
- Async validation: [Any rules requiring external calls?]
### Context
- Existing validators: [Reusable validation functions to use]
- Error handling pattern: [How errors are displayed to users]
### Edge Cases
- [Empty string vs. null vs. undefined]
- [Whitespace handling]
- [Unicode and special characters]
- [Maximum length boundaries]Code language: PHP (php)Customization guidance: For form validation, group rules by field and include real-time vs. submission validation distinction. For API validation, include HTTP status codes for different validation failures. For complex business rules, add cross-field validation specifications.
Template: Database Migration
Use this template when specifying schema changes, data migrations, or database modifications.
## Database Migration Specification
### Purpose
[What change is being made and why?]
### Migration Type
- [ ] Schema change (DDL)
- [ ] Data migration (DML)
- [ ] Both
### Changes
#### Tables
[For each table affected]
Table: [table_name]
- Action: [CREATE/ALTER/DROP]
- Columns:
- [column_name]: [type] [constraints] - [ADD/MODIFY/DROP]
- Indexes:
- [index_name]: [columns] - [ADD/DROP]
- Foreign keys:
- [constraint_name]: [specification] - [ADD/DROP]
#### Data Changes
[If data migration]
- Source: [Where does data come from?]
- Transformation: [How is data modified?]
- Destination: [Where does data go?]
### Rollback Plan
[How to reverse this migration]
- Schema rollback: [DDL to undo]
- Data rollback: [Is it possible? How?]
### Constraints
- Downtime: [Zero-downtime required? Maintenance window?]
- Performance: [Expected duration, table lock implications]
- Data preservation: [What must not be lost?]
### Context
- Related migrations: [Dependencies, ordering]
- Application changes: [Code that must deploy with this migration]
- ORM/Framework: [Specific migration tool being used]
### Verification
- Pre-migration checks: [What to verify before running]
- Post-migration checks: [How to verify success]
- Rollback triggers: [When to roll back]Code language: PHP (php)Customization guidance: For large table migrations, add batching specifications and progress monitoring. For multi-database environments, specify which databases are affected. For regulated environments, add audit trail requirements.
Template: External Service Integration
Use this template when specifying code that integrates with third-party APIs, SDKs, or external systems.
## External Service Integration Specification
### Purpose
[What capability does this integration provide?]
### Service Details
- Service: [Name and version]
- Documentation: [Link to API docs]
- Authentication: [API key, OAuth, etc.]
- Environment: [Different endpoints for dev/staging/prod?]
### Operations
[For each operation being implemented]
Operation: [operation_name]
- HTTP Method: [GET/POST/etc.]
- Endpoint: [URL pattern]
- Request: [Parameters, headers, body]
- Response: [Expected response structure]
- Rate limits: [Requests per second/minute/hour]
### Error Handling
- Network errors: [Retry strategy, timeout handling]
- Rate limiting: [Backoff strategy]
- Authentication errors: [Token refresh, re-authentication]
- Service errors: [How to handle 5xx responses]
- Validation errors: [How to handle 4xx responses]
### Data Mapping
- Inbound: [How service data maps to our domain models]
- Outbound: [How our data maps to service format]
### Constraints
- Timeout: [Maximum wait time]
- Circuit breaker: [Failure threshold, recovery time]
- Caching: [What responses can be cached, TTL]
- Idempotency: [For write operations]
### Context
- Wrapper pattern: [Link to existing integration pattern]
- Credentials management: [How secrets are stored/accessed]
- Monitoring: [What to log, what metrics to emit]
### Testing
- Mock strategy: [How to test without hitting real service]
- Sandbox environment: [If available]
- Test credentials: [How to obtain]Code language: CSS (css)Customization guidance: For payment integrations, add PCI compliance requirements. For data-heavy integrations, add pagination handling. For webhook-based integrations, add payload verification and idempotency handling.
How to Customize Templates for Your Domain
These templates are starting points, not final forms. Your team should customize them based on your technology stack, your patterns, and the failures you have experienced.
Add sections for repeated omissions. Every time a missing specification element causes problems, consider adding a section for it. If your team repeatedly forgets to specify logging requirements, add a logging section. If error messages are inconsistent, add an error message section with format guidelines.
Remove sections that do not apply. If your team never builds public APIs, simplify the API template by removing extensive error response documentation. If you use a single database, remove multi-database considerations from the migration template. Templates should be right-sized for your context.
Include examples from your codebase. The context section of every template has a place for “similar code.” Populate this with actual examples from your system. When developers fill out the template, they should include a link or paste code that demonstrates the patterns to follow.
Version your templates. As your practices evolve, your templates should evolve. Maintain templates in version control alongside your code. Review and update them periodically based on team feedback and observed results.
Evolving Templates Based on Results
Templates are living documents. They should improve based on what you learn from using them.
After completing an ADD cycle, ask: Did the specification produce good results? If not, why? Was important information missing? Add a section. Was a section routinely unhelpful? Remove or revise it.
Track which specification gaps cause the most rework. If a particular type of missing information repeatedly leads to iteration or bugs, that information needs a more prominent place in your templates.
Share template improvements across the team. When one developer discovers a useful addition, propagate it to everyone. Templates are institutional knowledge that should be collectively maintained.
The goal is templates that, when filled out completely, reliably produce specifications that generate good code on the first attempt. This is achievable, but it requires iteration on the templates themselves, not just on the specifications you write with them.
Let’s Continue the Conversation
Which of these templates is most relevant to your work? What sections would you add based on your experience?
Does your team already use specification templates? What has worked well, and what has not?
Share your thoughts in the comments. I will incorporate community feedback into the downloadable template library.