What Is Spec-First Development? (Complete Guide)
Use this as the orientation piece if you want the overall model, tradeoffs, and where spec-first work pays off.
Read the full guide
Spec-First Library
Spec Coding Blog
Practical articles for teams using spec-first delivery. The focus is on writing clearer requirements, tightening review loops, and shipping with fewer surprises.
72 ArticlesCovering writing, API contracts, delivery process, case studies, and resources
7 TopicsOrganized for faster browsing across adoption, execution, and review
4 per pageStatic pagination keeps long archives readable
How to Write a Technical Spec
A complete template, worked example, and free generator covering acceptance criteria, edge cases, and the sections every spec needs.
Open the template guideHow to Adopt Spec-First in a Team (30-Day Plan)
If you are moving beyond a solo trial, this gives you a concrete rollout rhythm and measurement model.
See the 30-day planChoose a Learning Path
Pick the path that matches the problem in front of you. Each path starts with a practical article, then points toward a template, checklist, or tool you can use in the same session.
Learn the method before you change your process
Start with the complete guide, then compare spec-first with agile and use the adoption plan only after the team agrees on the behavior you want to protect.
Start the foundations pathTurn vague requirements into testable criteria
Use the technical spec guide, acceptance criteria examples, and edge-case articles when a ticket is too broad for implementation.
Follow the writing pathProtect contracts, migrations, and rollback paths
Start here when a change touches external consumers, database shape, idempotency, compatibility, or release safety.
Follow the contract pathGive AI tools boundaries they can be reviewed against
Start with a spec packet, then move into prompts, risk registers, PR review gates, and test evidence before generated code reaches production.
Follow the AI pathTopic Hubs
Use these hubs when you want a structured route through the library instead of one article at a time. Each hub includes a decision table, copy-ready block, and related guides.
Spec-First Development Hub
Start here for the method, core decisions, review gates, and evidence habits.
Open hubAPI Contracts Hub
Use this route for schema diffs, compatibility, versioning, webhooks, and deprecation.
Open hubAcceptance Criteria Hub
Turn success statements into testable criteria with failure paths and proof.
Open hubAI Coding Governance Hub
Connect prompts, risk registers, acceptance mapping, and test evidence.
Open hubAll Articles
Browse by topic first, then move into pagination. It is the fastest way to find material that fits your current delivery stage.
1. AI Coding Spec Packet Before Code Generation
A copy-ready packet for giving AI coding tools a bounded task, acceptance criteria, file ownership, tests, and review evidence before code generation starts.
Read article2. Refund Example: Vibe vs Spec Coding
Same order refund feature built two ways — vibe coding ships fast but drowns in edge-case bugs,…
Read article3. Acceptance Criteria Examples You Can Copy
20 real-world acceptance criteria examples in Given/When/Then format covering authentication, e-commerce, APIs, data processing, payments, and notifications.
Read article4. Technical Spec Template, Examples, and Generator
How to write a technical specification: a complete template, real-world walkthrough, section-by-section guidance, and a free online generator to draft your own.
Read article5. Building a Test Harness for API Services
A practical guide to building test harness infrastructure for backend API services — from fixtures and mocks to contract tests and CI integration,…
Read article6. Superpowers for Spec-First AI Coding
Superpowers is an open-source framework that enforces spec-first discipline on AI coding agents.
Read article7. Spec Review Anti-Patterns and When to Skip Specs
Learn when specs help, when they slow teams down, and which spec review anti-patterns create ceremony without reducing risk.
Read article8. Spec-First Feature Flags Guide
Specify feature flags with lifecycle rules, audience targeting, canary rollout, dark launch behavior, monitoring, and cleanup criteria.
Read article9. Backward Compatibility Specs and Deprecation Paths
Define backward compatibility rules for API specs, including deprecation timelines, migration paths, Sunset headers, and breaking-change review.
Read article10. Harness Engineering vs Spec-First
Harness engineering builds validation infrastructure. Spec-first defines correctness before code is written. Two approaches that work better together than alone.
Read article11. Database Schema Specs Before Migrations
Define database schemas before writing migrations, including columns, constraints, indexes, API alignment, and rollout order.
Read article12. AI Coding Prompts That Follow Specs
AI coding tools drift without constraints — adding fields, renaming functions, expanding scope.
Read article13. AI Coding Governance with Spec-Driven Prompts
Govern AI-assisted coding with spec-driven prompts: define scope, boundaries, evidence, and audit trails before generated code reaches review.
Read article14. AI Coding PR Review with Acceptance Criteria
Review AI-generated pull requests against acceptance criteria: inspect the diff, run evidence checks, and catch failures a quick skim misses.
Read article15. AI Coding Risk Register Before Merge
Use a pre-merge risk register for AI-generated code: flag auth, data, contract, migration, rollback, and observability risks.
Read article16. AI Coding with Test-Evidence Gates
Use test-evidence gates for AI-generated code: require meaningful tests before merge and catch hallucinated implementations before release.
Read article17. API Change Management for AI-Generated Clients
Manage API changes for AI-generated clients with structured changelogs, announcement channels, compatibility rules, and CI gates.
Read article18. API Error Taxonomy for AI-Assisted Integrations
Design API error taxonomies AI-generated clients can use, with stable codes, retry categories, and machine-readable details.
Read article19. API Schema Diff Review Before Release
How to run an API schema diff review before every release: what diff tools catch, what they miss, and the human checks that still matter for OpenAPI and GraphQL.
Read article20. Contract-First SDK Generation with Human Review
Generate SDKs from an API contract with a clean split between generated clients, hand-authored ergonomics, and the human review gate that matters.
Read article21. Designing API Specs for Agentic Clients
Design API specs for LLM-powered agentic clients with discoverable fields, idempotency, dry-runs, semantic descriptions, and safe destructive actions.
Read article22. Review Checklist for AI-Written Migrations
Review AI-written database migrations for locking behavior, rollback safety, batch size, dry-run evidence, and production data scale.
Read article23. Spec Skills for Bug Triage and Incident Notes
Using Spec Skills to triage bug reports into actionable incident notes: the repro-check pass, severity inference, and the postmortem-seed prompt that saves hours.
Read article24. Spec Skills Case Study: From Ticket to Spec
Follow a vague support ticket as it becomes a shippable technical spec using Spec Skills, guided questions, and review-ready output.
Read article25. Spec Skills and Spec-First Delivery
See how Spec Skills fits spec-first delivery through constrained prompts, spec injection, boundary enforcement, and reviewable AI output.
Read article26. Spec Skills for Acceptance Criteria Drafting
Drafting testable acceptance criteria with Spec Skills: the structured prompt, the failure-mode pass, and the human review that catches what the AI misses.
Read article27. Spec Skills Prompt Library for Product Teams
Building and maintaining a Spec Skills prompt library for product teams: what to store, how to version, which prompts earn their keep, and which become landfill.
Read article28. Spec Skills Prompt Patterns for Spec Workflows
Use Spec Skills prompt patterns for feature specs, acceptance criteria, spec reviews, risk registers, and controlled AI coding workflows.
Read article29. Spec Skills vs General AI Coding Tools
Compare Spec Skills with general AI coding tools across spec discipline, guardrails, context control, review workflows, and team adoption.
Read article30. Spec Skills Workspace Setup for Dev Teams
Setting up a Spec Skills workspace for a dev team: repo layout, the /specs directory, prompt library location, CI gates, and the rollout week-by-week.
Read article31. Acceptance Criteria Prompt Templates
Prompt templates for usable acceptance criteria: five-slot structure, failure-mode seeding, and a review loop before scenarios reach QA.
Read article32. Using Spec Skills to Review API Contracts
Use Spec Skills to review API contract changes with schema diffs, semantic drift checks, breaking-change flags, and consumer impact prompts.
Read article33. API Deprecation Plan Inside Your Contract
Build API deprecation into the contract with Sunset headers, migration timelines, customer notices, and usage reporting from day one.
Read article34. Marketplace Payout Spec: Reconciliation
Write a marketplace payout spec with reconciliation rules, dispute handling, hold periods, ledger entries, audit evidence, and payout review gates.
Read article35. Mobile Push Notification Preference Spec
Spec patterns for mobile push notification preferences: category vs channel model, quiet hours, OS-level permission handling, and the cross-device delivery contract.
Read article36. Partner API Onboarding Spec Checklist
Use this partner API onboarding checklist for sandbox access, rate plans, agreements, go-live gates, monitoring, and offboarding.
Read article37. Quality Gates for AI-Assisted Development Specs
Quality gates for AI-assisted code: pre-prompt spec checks, diff review, test evidence, and human sign-off before generated code ships.
Read article38. Real-Time Collaboration Spec: Conflict Resolution
How to spec real-time collaboration: OT vs CRDT, presence protocol, offline edits, conflict resolution, and the operational transform vs three-way-merge decision.
Read article39. Spec-Driven Frontend-Backend Alignment
Use spec-first work to align frontend and backend teams around shared schemas, generated clients, error shapes, and parallel-build review.
Read article40. Subscription Change Spec: Proration Rules
Write subscription change specs for proration, mid-cycle plan changes, trials, downgrades, credit handling, and renewal boundaries.
Read article41. Writing Backward-Compatible API Change Specs
Write backward-compatible API change specs with additive fields, safer input widening, enum expansion, default values, and release review rules.
Read article42. Billing Reconciliation Spec: Tolerances
Write a billing reconciliation spec with tolerance thresholds, exception queues, daily close rules, and clear handling for penny-level differences.
Read article43. Contract Testing Plan: From OpenAPI to CI
Add contract testing from OpenAPI to CI with generated tests, provider checks, consumer expectations, and reliable fixtures.
Read article44. Data Sync Between Services: Spec Guide
Specify cross-service data sync with ordering guarantees, conflict handling, backfill plans, and event-driven or pull-based tradeoffs.
Read article45. Database Migration Rules Inside a Technical Spec
Write database migration rules into your spec, including expand-contract steps, compatibility windows, online DDL, and rollback plans.
Read article46. Designing Idempotent Workflows with Specs
How to specify idempotency keys, deduplication windows, and state-machine transitions so retries and partial failures don't double-charge or corrupt data.
Read article47. Event-Driven Systems: Specification Patterns
Specification patterns for event-driven systems: schema versioning, command vs fact events, orchestration choices, idempotent handlers, and replay safety.
Read article48. How to Scope Non-Goals in Technical Specs
Write non-goals that stop scope creep, name deferred work, and give reviewers a clear boundary before implementation starts.
Read article49. Mobile API Spec Considerations for Offline Mode
Spec a mobile API for offline mode with local-first writes, sync windows, conflict handling, outbox behavior, and rejection recovery.
Read article50. Notification System Spec: Delivery Guarantees
Spec notification delivery guarantees by channel, fallback ladder, suppression rules, and the at-most-once vs at-least-once decision.
Read article51. Payment Workflow Spec: Failure and Retry Matrix
Write payment workflow specs with retryable errors, declined-card handling, timeout behavior, 3DS branches, and dunning states.
Read article52. Queue Processing: Exactly-Once vs At-Least-Once
Write queue contracts for at-least-once delivery with idempotent consumers, dead-letter rules, replay procedures, and duplicate safeguards.
Read article53. Rollout and Rollback Design for High-Risk Releases
Design high-risk releases with stop-loss metrics, rollout windows, rollback types, and owners who can pause expansion.
Read article54. Spec-First Error Handling Patterns for APIs
Error-handling patterns the spec must decide before implementation: envelope shape, retryable categories, partial-success semantics, and the rule for 5xx vs 4xx.
Read article55. Versioning Strategies for API Contracts
Compare URL, header, date-based, and evolution-only API versioning, with spec rules for compatibility and deprecation timelines.
Read article56. Webhook Consumer Spec: Signature, Retry, and Order
How to write a webhook consumer spec: signature verification, replay protection, retry and backoff rules, ordering assumptions, and idempotent handler design.
Read article57. Writing Edge Cases That QA Can Actually Test
Write edge cases QA can execute with concrete inputs, starting states, expected outputs, and release-blocking priority.
Read article58. Billing Incident Postmortem: Spec-First Fix
A postmortem-style walkthrough of a billing bug that shipped because the spec never addressed proration, and the exact sections that would have caught it.
Read article59. 10 Common Mistakes in Software Specifications
Avoid ten specification mistakes that hide decisions, blur acceptance criteria, skip failure paths, and push scope arguments into implementation.
Read article60. How to Adopt Spec-First in a Team (30-Day Plan)
A 30-day adoption plan for Spec-First: choose the first workflow, set a review threshold, and measure whether rework drops.
Read article61. How to Write Testable Software Specifications
Turn software requirements into testable specs with observable outputs, failure paths, evidence types, and QA-ready acceptance criteria.
Read article62. PRD vs Technical Spec: What's the Difference?
PRD vs Technical Spec: What's the Difference becomes clearer when the team makes the hidden decisions visible before coding starts.
Read article63. Spec-First vs Agile: Conflict or Complement?
Fit Spec-First into agile delivery by defining which tickets need a spec, where review belongs, and how sprint rework gets reduced.
Read article64. Spec Review Checklist Before Coding
Use this pre-coding review checklist to separate blockers from preferences, record accepted risks, and attach test evidence before implementation begins.
Read article65. What Is Spec-First Development? (Complete Guide)
What is spec-first development? A complete guide to surfacing hidden decisions about scope, contracts, edge cases, and acceptance criteria before coding starts.
Read article66. How to Run Effective Technical Design Reviews
Most design reviews waste time on bikeshedding because there is no spec to anchor the conversation. Learn how to structure reviews that produce decisions.
Read article67. Architecture Decision Records Guide
Architecture Decision Records capture the reasoning behind technical choices.
Read article68. Effective Postmortems That Prevent Recurrence
Write postmortems that produce owned action items, trace incidents to missing decisions, and prevent the same failure from recurring.
Read article69. Technical Debt Prioritization Guide
A practical framework for categorizing technical debt, measuring its real cost with code metrics and incident data, prioritizing paydown work,…
Read article70. Code Review Best Practices for Better Quality
Practical code review techniques that catch real defects: how specs with acceptance criteria change what reviewers look for,…
Read article71. Postmortem: Missing Contract Tests
A reconstructed postmortem of a breaking API change that reached production because no contract test caught the field rename.
Read article72. Specs to Test Harnesses Workflow
How to turn spec-first acceptance criteria into executable test cases using your test harness.
Read articleStatic pagination · Page 1/18 · 72 articles