One-page AI feature spec template
A copyable one-page spec template for AI features, with prompts for each section and a filled-in example to follow.
4 min read Updated
On this page
How to use this template
Copy the template below into your docs tool or repository and fill in each section. Keep it to one page: link to detailed designs, eval sets and technical plans rather than including them. Writing a one-page AI feature spec explains each section and includes a complete worked example for a support-reply feature.
The template
specs/feature-name.md
# Spec: <feature name>
Owner: <name> · Status: draft / approved / building / launched · Last updated: <date>
## User and job
<Who has the problem. Job statement: When <situation>, I want to <progress>, so I can <outcome>.>
Evidence: <ticket counts, interview quotes, analytics, with sources>
## Success metric
Primary: <one behavior metric, with current baseline>
Guardrails: <two or three metrics that must not get worse>
Keep / change / remove thresholds after <period>: <values>
## Proposed solution
<What the AI does and what the user does, in a few sentences. Whole job or part of it?>
## Quality bar
<What a good output looks like, concretely.>
Launch threshold: <pass rate per category> on <eval set, size, source>. Agreed on <date>.
Must never fail: <list>
## Failure states
- Cut off: <what the user sees>
- Declined: <what the user sees>
- Nothing useful / no source: <what the user sees>
- Slow or unavailable: <what the user sees>
## Cost estimate
<Input and output tokens per request, calls per attempt, expected success rate>
Cost per success: <estimate> · Value per success: <estimate and how you got it>
## Non-AI alternative
<What you would build without a model, and why AI is better here, or not.>
## Open questions (ranked)
1. <Riskiest assumption> → <how and when the prototype will answer it>
2. <...>
3. <...>Review questions
Before approving a spec, check that you can answer yes to each:
- Could two people read the quality bar and agree on whether a given output passes?
- Can the primary metric be measured on launch day, with the events we have?
- Is there a designed state for refusals, cut-off answers and “nothing useful”, not just errors?
- Is every number sourced or marked as an estimate?
- Would the non-AI alternative deliver most of the value for much less?
- Does the riskiest open question have a plan to answer it within a week?
After the prototype
Once a prototype has run, add the sections described in turning a prototype into a spec: findings sorted into proved, suggested and assumed; decisions with their reasons; the seed eval set; and the ranked open risks.