How to use these templates

Pick the smallest template that can carry the risk of the change. A copy change does not need the same ceremony as a data migration. A billing permission change needs more than a ticket title. The goal is proportional rigor: enough structure to remove ambiguity without making the spec heavier than the work.

Keep requirement keywords meaningful. If your team uses MUST, SHOULD, and MAY, define them once and reserve MUST for acceptance-blocking behavior. RFC 2119 is a good reference point for disciplined requirement language. For a guided first pass, use the Spec Builder, then compare the output against the templates below.

"requirement levels"
RFC 2119

Template 1: Feature technical spec

# Technical Spec: [Feature Name]

Status: Draft | In review | Approved | Implemented
Owner:
Reviewers:
Last updated:

## Summary
[One paragraph: system, behavior change, reason.]

## Problem
[Evidence of the current problem. Link PRD, issue, support ticket, metric, incident, or research.]

## Goals
- [Observable outcome]
- [Observable outcome]

## Non-goals
- [Adjacent work out of scope]
- [Refactor or migration not included]

## Current behavior
- [What happens today]
- [Relevant files, services, APIs, data, UI states]

## Proposed behavior
- REQ-1: [One testable requirement]
- REQ-2: [One testable requirement]
- REQ-3: [One testable requirement]

## Design
### Data model
[Tables, columns, indexes, migrations, retention, ownership]

### API / contracts
[Routes, methods, payloads, responses, error codes, backwards compatibility]

### UI / states
[Screens, states, transitions, accessibility requirements]

### Permissions / security / privacy
[Authorization, sensitive data, audit logs, rate limits]

## Edge cases
- [Empty state]
- [Invalid input]
- [Unauthorized user]
- [Duplicate request]
- [Dependency failure]

## Acceptance criteria
- Given [state], when [action], then [result].
- Given [edge state], when [action], then [safe result].

## Verification
- Automated:
- Manual:
- Build/lint/typecheck:
- Observability:

## Rollout
[Feature flag, migration order, backfill, rollback, support notes]

## Open questions
- [Question] — owner, blocker/non-blocker, deadline.

Template 2: AI agent implementation brief

Use this when a spec already exists or the task is small enough that the brief itself is the spec. This format is optimized for coding agents because it makes working directory, scope, non-goals, verification, and reporting explicit. 

# Agent Implementation Brief

Goal:
[Observable outcome]

Working directory / repo:
[Path, branch, or PR]

Read first:
- [Spec, issue, design, source file, test file]
- [Existing implementation pattern]

Allowed edits:
- [Files, folders, modules, or surfaces]

Do not change:
- [Explicit non-goals]
- [Contracts, dependencies, design surfaces, unrelated code]

Requirements:
- REQ-1:
- REQ-2:
- REQ-3:

Examples:
- Given [state], when [action], then [result].
- Input: [payload]
  Output: [payload]

Verification:
- During iteration:
- Final gate:
- Manual check:

Stop and ask if:
- [Missing credential]
- [Repeated failing test]
- [Ambiguous product decision]
- [Destructive migration risk]

Final report:
- Files changed
- Verification output
- Deviations from brief
- Remaining risks

Template 3: Spike spec

A spike is not a license to wander. It is a bounded investigation. The output should be a decision, not just notes. Use a spike spec when the team cannot safely choose an implementation path without research or prototyping. 

# Spike Spec: [Decision to Make]

Status:
Owner:
Timebox:

## Decision needed
[The specific engineering or product decision this spike must support.]

## Background
[Current system, constraints, previous attempts, relevant links.]

## Options to evaluate
1. [Option A]
2. [Option B]
3. [Option C]

## Evaluation criteria
- Correctness:
- Complexity:
- Migration risk:
- Performance:
- Security/privacy:
- Operational burden:
- Reversibility:

## Investigation plan
- [Read source/docs]
- [Prototype]
- [Benchmark or test]
- [Talk to owner]

## Out of scope
- [Implementation beyond prototype]
- [Unrelated refactors]

## Deliverable
- Recommendation:
- Evidence:
- Risks:
- Follow-up spec needed?

Template 4: Change request spec

Use this when the system already exists and the work is a bounded modification. The key is to state the current contract and the new contract side by side. 

# Change Request Spec: [Change]

Status:
Owner:

## Current contract
[Behavior/API/data/UI state today.]

## Requested change
[New behavior.]

## Reason
[Bug, customer request, compliance, product change, performance, cleanup.]

## Compatibility
- Existing clients:
- Existing data:
- Rollback:

## Requirements
- REQ-1:
- REQ-2:

## Tests to update or add
- [Existing tests]
- [New tests]

## Manual verification
- [Flow]

## Release notes / support notes
[Anything customer-facing teams need.]

Template 5: Bug-fix spec

Many bug fixes are too small for a full spec, but the risky ones still need structure. The most important parts are reproduction, expected behavior, suspected boundary, non-goals, and regression verification. 

# Bug-Fix Spec: [Bug]

Status:
Owner:
Severity:

## Symptom
[What user/operator sees.]

## Reproduction
1. [Step]
2. [Step]
3. [Observed result]

## Expected behavior
[What should happen.]

## Suspected area
[Files, service, dependency, recent change, logs.]

## Non-goals
- [Adjacent cleanup not included]
- [Behavior not being changed]

## Fix requirements
- REQ-1:
- REQ-2:

## Regression tests
- [Test that fails before and passes after]

## Verification
- [Automated command]
- [Manual reproduction]
- [Log/metric check if relevant]

Template quality bar

ISO/IEC/IEEE requirements guidance is broader than these templates, but the quality bar transfers: requirements should be well-formed, attributes should be explicit, and sets of requirements should be reviewed for consistency and completeness. A template is not a shortcut around those checks.

For AI coding agents, also keep a separate repository instruction file when rules are stable across tasks. Cursor, OpenAI, GitHub, and Anthropic all document persistent instruction patterns. The template should carry the task-specific decisions, not duplicate every standing convention.