Writing Specs AI Can Execute

Good specs work for both humans and AI agents. These 12 patterns help you write specs that are clear, actionable, and free of ambiguity.

Each pattern connects back to the first principles: Context Economy (fit in working memory), Signal-to-Noise (every word matters), Intent Over Implementation (capture why), Bridge the Gap (humans + AI understand), and Progressive Disclosure (add complexity when needed).

1. Use Consistent Structure

Keep the same section order in every spec: ## Problem, ## Solution, ## Success Criteria, and optionally ## Trade-offs.

Consistent structure helps both humans and AI parse specs quickly. When every spec follows the same pattern, there's no guessing where to find information.

## Problem
User onboarding takes 14 minutes on average due to a multi-step form.

## Solution
Compress the flow into 2 screens and defer profile enrichment to after signup.

## Success Criteria
- Average onboarding time < 5 minutes
- NPS increases by 10 points
- Completion rate > 92%

2. Show Examples, Not Just Descriptions

Concrete examples beat abstract descriptions. Show actual API calls, CLI commands, and data formats instead of describing them in prose.

AI models learn from examples. Real payloads and invocations reduce hallucination and make specs immediately actionable.

POST /api/invite {"email":"ceo@example.com","role":"admin"}
→ 201 {"id":"usr_123","status":"pending"}

3. State What's Out of Scope

Explicitly list what you're NOT building. This prevents scope creep and keeps AI agents from implementing features you don't want.

Out of Scope:
- Mobile app parity
- OAuth provider expansion
- Advanced analytics dashboard

4. Define Success Before Implementation

Write measurable completion criteria before describing how to build something. This guides implementation toward the right goals.

Use 3-5 testable criteria with specific numbers or thresholds.

## Success Criteria
- P95 ingestion latency < 2s
- Zero data loss in synthetic stress test (1M events)
- Errors logged with correlated trace IDs

5. Capture Intent, Not Step-by-Step Instructions

Explain why you're making design choices, not just what to build. Intent stays stable even when implementation details change.

Avoid micro-managing with detailed task lists or function names. Focus on the reasoning.

We choose eventual consistency to favor ingestion throughput. Strict ordering is not a requirement for this use case.

6. Use Frontmatter for Metadata

Machine-readable frontmatter (status, priority, tags, dependencies) enables tooling to query, filter, and sequence work automatically.

---
status: in-progress
priority: high
tags: [api, ingestion]
depends_on: [052-branding-assets]
---

7. Write in Plain Language

Clear prose is easier for both humans and AI to understand. Use short paragraphs (≤4 sentences), active voice, and eliminate filler words.

The current batch processor retries indefinitely. This hides systemic failures and inflates cost. We will cap retries to 5 and emit structured error events.

8. Use Real Examples Over Synthetic Ones

Real data from logs, tests, or production is better than made-up examples. Ground truth reduces hallucination risk.

When you do use synthetic examples, label them clearly.

Edge Case (Real): User deleted org mid-invoice generation → orphan invoice
Edge Case (Synthetic): Simulated 10K concurrent signups for rate limiter

9. Document Constraints Explicitly

Hard limits (SLAs, memory caps, deadlines) need to be visible. This prevents over-engineering and keeps solutions viable.

Add a Constraints section before diving into design details.

Constraints:
- Memory cap: 256MB per lambda invocation
- Cold start budget: <300ms
- Migration window closes 2025-12-15

10. Mark Unknowns Clearly

Use uppercase markers (TBD, OPEN QUESTION, PUNT) for incomplete areas instead of leaving them ambiguous.

This signals to AI agents where uncertainty exists and prevents false confidence.

OPEN QUESTION: Do we stream partial results or wait for full batch?
TBD: Rate limiting strategy for partner tier

11. Update Specs After Implementation

When you build something, update the spec to reflect what you actually did. Document deltas between the plan and reality.

This keeps specs as the single source of truth. Future AI agents rely on current information, not stale plans.

IMPLEMENTATION DELTA: Dropped Redis cache layer—Postgres query tuned to 14ms P95, cache unnecessary.

12. Maintain Single Source of Truth

The spec should be the authoritative reference. Don't duplicate information in wikis, docs, or comments.

Link to other resources instead of copying. Archive superseded specs instead of quietly editing them.

Archived: 033-cache-layer-design replaced by current ingestion spec.

Applying the Patterns

Start every spec with these steps:

1. Problem & Success Criteria - Define what you're solving and how you'll know it's done (Patterns 1 & 4)
2. Constraints & Boundaries - Document hard limits and what's out of scope (Patterns 3 & 9)
3. Examples - Add concrete examples early, before abstract descriptions (Patterns 2 & 8)
4. Intent & Rationale - Explain why you're making design choices (Pattern 5)
5. Mark Unknowns - Use TBD/OPEN QUESTION while iterating (Pattern 10)
6. Reconcile Reality - Update the spec after implementation to match what you built (Pattern 11)

This workflow ensures specs stay lean, clear, and in sync with reality (Pattern 12).

Pattern Quick Reference

Pattern	Context Economy	Signal-to-Noise	Intent Over Implementation	Bridge the Gap	Progressive Disclosure
1. Consistent Structure	✓	✓
2. Show Examples		✓		✓
3. Out of Scope					✓
4. Success First	✓		✓
5. Capture Intent			✓
6. Frontmatter Metadata				✓	✓
7. Plain Language				✓
8. Real Examples		✓
9. Document Constraints	✓
10. Mark Unknowns					✓
11. Update After Build			✓
12. Single Source		✓		✓

Checklist Before Marking Complete

• Problem stated before solution
• Success criteria are measurable
• At least one real example per API/process
• Boundaries and constraints documented
• All TBDs resolved or tracked
• Spec updated to reflect implementation

Common Mistakes

Problem	Why It Fails	Fix
Task list instead of rationale	Loses intent, hard to adapt	Explain why, not just what
No success criteria	Can't validate or prioritize	Add 3-5 measurable targets
Abstract examples	AI hallucinates details	Use real payloads from logs/tests
Hidden constraints	Over-engineering	Surface limits in Constraints section
Stale after implementation	Misleads future work	Update immediately after building