| name | spec-writing-best-practices |
| description | Write a requirements spec that is testable, scoped, and implementation-aware without turning into architecture. Use this when acting as the spec writer for a task. |
| owner | spec |
| trigger | null |
| version | 1 |
Spec Writing Best Practices
Use this before finalizing a spec deliverable.
Goal
Produce a spec that gives the architect and planner enough clarity to proceed without guessing, while avoiding premature implementation detail.
Checklist
- Scope the task cleanly.
State what is in scope and what is out of scope. Do not leave adjacent work ambiguous.
- Make acceptance criteria testable.
Prefer concrete outcomes, observable behavior, and clear failure conditions. Avoid vague words like "supports" or "handles well" without defining what success means.
- Separate requirements from implementation.
Describe what the system must do. Only mention implementation constraints when they are already required by the existing codebase or the task itself.
- Capture data and contract expectations.
In
## Data Design and ## API Contracts, specify the shapes other agents will depend on. If something is unknown, say so explicitly instead of implying certainty.
- Include edge cases that can change architecture or testing.
Empty input, retries, partial failure, invalid state, missing data, auth failure, concurrency, migration, and backward-compatibility risks are the usual misses.
- Include non-functional requirements only when they matter.
Performance, security, compatibility, observability, and rollout constraints should be concrete and relevant, not boilerplate.
Guardrails
- Do not invent new architecture layers, file boundaries, or agent ownership here. That is for architecture and planning.
- Do not duplicate the same requirement in multiple sections with slightly different wording.
- If the codebase already constrains a decision, read it first and align the spec with reality.
- If the task depends on a third-party API or framework behavior, activate
external-api-knowledge before locking the contract language.
Deliverable Standard
Before submitting, ask:
- Could a reviewer derive a meaningful test plan from
## Acceptance Criteria alone?
- Could an architect identify required contracts and data shapes without reinterpreting the task?
- Would two different implementation agents read this spec and reach roughly the same understanding?
If not, tighten the spec before calling submit_deliverable.
