Spec Templates

Feature Spec

Goal, non-goals, acceptance criteria, and edge cases in one page.

API Spec

Endpoint contracts, request/response schemas, and error conventions.

DB Spec

Fields, constraints, indexes, migration strategy, and rollback notes.

Change Proposal

Start a change with goal, non-goals, acceptance criteria, open questions, and evidence requirements.

Design Doc

Record architecture choices, rejected alternatives, interfaces, constraints, rollout, and rollback.

Tasks Plan

Split implementation into reviewable slices with allowed files, acceptance links, and test commands.

Evidence Log

Attach tests, screenshots, logs, metrics, manual checks, and release stop signals to the spec.

AI Coding Review

Check generated code for scope drift, allowed files, missing criteria, and test evidence.

Engineering Constitution

Define the team rules for spec gates, evidence standards, AI coding limits, and exceptions.

Feature spec excerpt

A copied template should quickly become a decision record, not a list of empty headings.

## Refund retry behavior
Owner: Billing platform
Non-goal: no new payment provider

Acceptance:
- Given provider timeout on first refund attempt
  When worker retries with the same idempotency key
  Then only one refund_id is created
  And support cannot create a second refund while status is pending

Use this level of detail before asking engineering or an AI coding tool to implement the workflow.

API contract excerpt

API templates should make consumer impact visible before a schema diff reaches release review.

Endpoint: GET /orders/{id}
Change: add refund_status
Compatibility: risky for generated clients

Evidence:
- old mobile client handles unknown enum values
- webhook consumer ignores new field
- release note names migration window

If the preview feels too specific for your team, keep the structure and replace the domain values.

Use a feature spec when scope is unclear

Start here when the team is still debating what the feature should include. The feature spec forces the conversation around goals, non-goals, acceptance criteria, edge cases, dependencies, and rollout shape before anyone opens a pull request.

Use an API spec when teams must integrate

Reach for the API template when frontend, backend, mobile, or partner teams need a stable contract. It captures endpoint behavior, request and response examples, error semantics, compatibility rules, and what tests should protect the contract.

Use a DB spec when data changes are risky

Use the database template before migrations, schema redesigns, backfills, or reporting changes. It makes constraints, index impact, rollback strategy, and compatibility windows visible early enough for review.

1. Copy only the sections you will actually maintain

A good spec is not a ceremonial document. Keep sections that drive decisions: goal, non-goals, acceptance criteria, edge cases, dependencies, rollout, and test evidence. Remove boilerplate that nobody will review.

2. Replace vague intent with observable behavior

Change statements like "handle errors gracefully" into concrete outcomes: what the user sees, what the API returns, what is logged, what is retried, and what is deliberately rejected.

3. Review the spec before implementation

Run a short review with product, engineering, and QA. The goal is to catch missing cases before code exists, not to polish prose. The best review comments usually point to ambiguity, not grammar.

4. Attach test evidence before merge

When implementation starts, keep the spec next to the work. Each acceptance criterion should map to a test, a manual verification note, or a conscious reason why it is not automated yet.

Check for missing boundaries

Every copied template should answer what is out of scope, what happens with empty input, how permissions are enforced, how duplicates behave, and what failure mode the team is willing to accept.

Connect the template to a next step

If the spec is ready, turn it into implementation work with the Feature Spec Generator, validate API behavior with the API Contract Checklist, or harden edge cases with the Edge Case Checklist.

Choose the Feature Spec when behavior changes

Use it when users, roles, permissions, UI states, workflows, or acceptance criteria are changing. The value is not the document itself; it is the shared decision record that keeps product intent, implementation, and QA aligned.

Choose the API Spec when another system depends on you

Use it for endpoints, events, webhooks, background jobs, or any service boundary where a consumer needs stable fields, error behavior, retry rules, and compatibility guarantees.

Choose the DB Spec when data safety is the risk

Use it when a change touches persistent state, migration order, indexes, constraints, backfills, retention, or rollback. Database work needs a spec because mistakes often survive code review until production data appears.

Choose the smallest template that still exposes risk

A short, precise spec beats a large document nobody reviews. If a section does not help the team make a decision, remove it. If a missing section hides risk, add it before implementation starts.

It names decisions, not just sections

A filled template should say who can perform the action, which data changes, what happens on failure, how duplicates behave, and which parts are intentionally out of scope. Empty headings are not progress.

It gives QA observable evidence

Every acceptance criterion should lead to a visible result: UI state, API response, database row, log entry, metric, alert, or manual verification note. If nobody can prove it, the criterion is not ready.

It keeps AI coding bounded

When you pass a template to an AI coding tool, include the non-goals and ask for a change map. The output should explain which acceptance criterion each code change satisfies.

It changes when requirements change

Templates are not one-time artifacts. If a reviewer changes scope, rollout, or compatibility rules, update the spec before merging code so future readers see the final decision.

Name the owner and review date

When a template becomes part of an internal workflow, add the team owner, applicable systems, last reviewed date, and the situations where the template should not be used. This prevents an old copy from becoming an accidental release policy.

Revise the template after real incidents

If a release slips because of a missing edge case, unclear API behavior, or unsafe migration plan, update the relevant template section immediately. The best template library learns from the team's own review misses.

Should every task have a spec?

No. A typo fix or tiny copy change does not need a full document. Use a spec when the work changes behavior, data, APIs, rollout risk, or team coordination. The more people affected, the more useful the template becomes.

Can these templates be used with AI coding tools?

Yes. They are intentionally structured so an AI coding tool can receive a bounded request: implement only this scope, preserve these contracts, and provide test evidence for these acceptance criteria.