Specification
What we mean when we say 'spec'
A semantic contract: vocabulary your project supplies itself — ready to drop into your CLAUDE.md / AGENTS.md.
- Persona Use Cases in Cockburn's Fully Dressed format (Primary Actor, Trigger, Main Success Scenario, Extensions, Postconditions) at User Goal level
- Rules and requirements as one numbered list (BR-IDs). Each entry is one statement in an EARS pattern (ubiquitous "shall", event-driven "When", state-driven "While", unwanted behaviour "If … then", optional feature "Where"), with its source. EARS is the grammar of the rules, not a second list: there is no separate requirements register.
- System Use Cases for each technical interface (API endpoint, CLI command, event, file format): input/validation, processing, output/status codes, error responses
- Activity Diagrams for all flows (not just the happy path)
- Acceptance criteria in Gherkin format (Given/When/Then). Each scenario cites the rule it proves, at least one scenario per use-case extension. The rule is the contract, the scenario is the proof.
- Supplementary Specifications as needed: Entity Model, State Machines, Interface Contracts, Validation Rules
When we talk about a "specification" or "spec", we mean: