Spec Writing
Parent: Code Plan Writing · researched 2026-05-29T19:03:51.778Z· 7 sources · 10 concepts · skill spec-writing
An engineering spec is a contract. It says WHAT a system, component, endpoint, or message must do — independent of HOW it is implemented.
Overview
- An engineering spec is a contract. It says WHAT a system, component, endpoint, or message must do - independent of HOW it is implemented. [source]
- Three forms dominate modern practice: [source]
- API specs - machine-readable contracts for HTTP (OpenAPI 3.1) and event-driven (AsyncAPI 3.0) interfaces [source]
- Behavior specs - executable narratives (Gherkin / Given-When-Then) [source]
- Data specs - schema contracts (JSON Schema, Avro, Protobuf) [source]
- Joel Spolsky's 2000 series "Painless Functional Specifications" introduced the discipline: a functional spec describes how a product works from the user's perspective; a technical spec describes internal implementation. [source]
1. Spec says WHAT, not HOW
2. Contract-first design
- Contract-first development: agree on the contract before writing code. The OpenAPI / AsyncAPI document is the source of truth. [source]
3. OpenAPI 3.1 for HTTP APIs
- Key top-level fields: [source]
- openapi - version (3.1.0) [source]
- info - name, version, description [source]
- servers - base URLs per environment [source]
- paths - endpoints, verbs, parameters, request/response shapes [source]
- components - reusable schemas, parameters, responses, security schemes [source]
- YAML is preferred over JSON for human authoring. [source]
4. AsyncAPI 3.0 for events
- Key concepts in v3.0: [source]
- Channels are addressable destinations (Kafka topic, AMQP queue) - decoupled from operations [source]
- Operations describe what an application does on a channel using action: send or action: receive [source]
- Messages are defined once and referenced from channels and operations [source]
5. Gherkin / Given-When-Then for behavior specs
6. Spec-as-contract mindset
- A spec is a promise. Once published: [source]
- Versioning - non-breaking changes bump minor; breaking changes bump major. [source]
- Backward compatibility - additive changes (new optional field) are safe; removals, renames, type changes are breaking. [source]
- Deprecation policy - published timeline (e.g., 12 months notice for major version sunset). [source]
7. Versioning conventions
8. Examples are part of the spec
- OpenAPI's examples field and Gherkin's Examples: table are not decorative - they are the spec. CI tools validate that examples conform to the declared schema. [source]
Anti-Patterns
- Implementation leakage - spec mentions Redis, Postgres, language choice. [source]
- No examples - schemas without concrete payloads. [source]
- Hand-waved errors - "returns an error on failure" without listing codes. [source]
- Missing versioning policy. [source]
- Spec-test drift - spec says one thing, implementation does another, no CI check. [source]
- Optional everything - every field is optional, every status code is default. [source]
References
- Joel Spolsky, "Painless Functional Specifications, Part 2" [source]
- OpenAPI Specification v3.1: https://spec.openapis.org/oas/v3.1.0 [source]
- AsyncAPI 3.0.0 Specification: https://www.asyncapi.com/docs/reference/specification/v3.0.0 [source]
- Cucumber, "Gherkin Reference": https://cucumber.io/docs/gherkin/reference/ [source]
Children
- WHAT not HOW (Spolsky) (frontier)
- Contract-first design (frontier)
- OpenAPI 3.1 (frontier)
- AsyncAPI 3.0 (frontier)
- Gherkin / Given-When-Then (frontier)
- Spec-as-contract mindset (frontier)
- Versioning conventions (frontier)
- Spec file vs code doc decision (frontier)
- Examples as part of spec (frontier)
Frontier under this node: AsyncAPI 3.0, Contract-first design, Examples as part of spec, Gherkin / Given-When-Then, OpenAPI 3.1, Spec file vs code doc decision, Spec-as-contract mindset, Versioning conventions, WHAT not HOW (Spolsky)