One of the biggest friction points in distributed engineering teams isn't technical — it's the spec. Here's the format that reduced our back-and-forth significantly.
The problem with most specs
Most engineering specs are either too vague ("build a notification system") or too prescriptive ("use Redis pub/sub with these exact keys"). Neither works well.
The first requires endless clarification before starting. The second removes the engineering judgment that makes a senior developer worth hiring.
The 6-section format
1. Context (2–4 sentences)
Why does this need to exist? What breaks without it?
Example: "Our billing webhook handler processes all events synchronously. When Stripe sends a burst, the endpoint times out and Stripe retries, causing duplicate processing. This caused 3 support tickets this week."
2. Success criteria
Observable behaviors, not implementation steps.
- Stripe webhooks return 200 within 200ms
- Duplicate events are idempotent (same event ID = no side effect)
- Failures are retried with backoff (3 attempts: 5min / 15min / 60min)
- Failed events after retries are stored for manual review
3. Constraints
What can't change? What's the technology boundary?
4. Open questions
What decisions is the engineer expected to make?
Example: "Queue implementation is your call — evaluate BullMQ vs Inngest and document the tradeoff in the PR."
5. Out of scope
What explicitly doesn't need to be solved here.
6. Dependencies / resources
Links to relevant code, docs, or people to consult.
Why "open questions" is the most important section
When you skip it, engineers either make decisions silently (you find out at review) or block waiting for approval. Writing "here are the decisions I'm delegating to you" gives senior engineers the autonomy they want while keeping you in the loop on design surface.
Anti-patterns
The spec-by-wireframe — a Figma screenshot with no written context. Engineers can't build from UI designs alone.
The spec with a hidden solution — "We need a caching layer" when you actually mean "add Redis here." If you've decided, just say so.
The spec that changes mid-implementation — if requirements change, write an addendum. Don't edit the original. Engineers need to track what changed.
What sections do you include that I haven't mentioned? Comments welcome.
Top comments (0)