Start from a reusable Markdown template, then adapt it to your team conventions. Use a single spec for small work, or a complete packet when the change needs proposal, behavior, design, tasks, and evidence.
Use this when the request is risky enough that one file will blur intent, behavior, design, implementation, and proof.
docs/specs/checkout-coupon/ proposal.md why now, who is affected spec.md requirements and scenarios design.md decisions and trade-offs tasks.md reviewable implementation slices test-evidence.md proof required before mergeGenerate a packet
A packet stays useful because each file has one job. Reviewers can challenge the proposal without rewriting tasks, or update evidence without changing product intent.
Goal, non-goals, acceptance criteria, and edge cases in one page.
Open feature templateEndpoint contracts, request/response schemas, and error conventions.
Open API templateFields, constraints, indexes, migration strategy, and rollback notes.
Open DB templateUse these when a team or AI coding agent needs a reviewable chain from intent to implementation evidence. If the main question is where the spec should live, start with the Spec as Code Hub.
Start a change with goal, non-goals, acceptance criteria, open questions, and evidence requirements.
Open spec.md templateRecord architecture choices, rejected alternatives, interfaces, constraints, rollout, and rollback.
Open design.md templateSplit implementation into reviewable slices with allowed files, acceptance links, and test commands.
Open tasks.md templateAttach tests, screenshots, logs, metrics, manual checks, and release stop signals to the spec.
Open evidence.md templateCheck generated code for scope drift, allowed files, missing criteria, and test evidence.
Open review templateDefine the team rules for spec gates, evidence standards, AI coding limits, and exceptions.
Open constitution templateA 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 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.
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.
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 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.
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.
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.
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.
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.
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.
If the spec is ready, turn it into implementation work with the Feature Spec Generator, validate API behavior with the API Contract Checklist, harden edge cases with the Edge Case Checklist, or keep it versioned with the Spec as Code Hub.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.