Practical articles for engineering and product teams working with spec-first delivery. The focus is on writing clearer requirements, tightening review loops, and shipping with fewer production surprises.
The orientation article for the whole site. Covers the core model, the tradeoffs against informal delivery, and the three questions every spec needs to answer before implementation starts.
Read the full guideA reusable spec structure covering scope, non-goals, acceptance criteria, edge cases, rollout, and rollback. Adapt it to your team's review and test workflow.
Get the templateA concrete rollout plan for moving from solo practice to team discipline, with weekly checkpoints and a measurement model that shows whether the change is sticking.
See the 30-day planBrowse by topic or scroll through the full list. Articles are ordered newest first.
A provider team renamed a JSON field without contract tests in place. The consumer silently created 340 orders with missing data before anyone noticed. This postmortem covers the timeline, root cause, and five action items that would have prevented it.
Read articleAcceptance criteria written in Given/When/Then map directly to fixture setup, test actions, and assertions. This article walks through the mapping, shows a worked example, and covers how QA enters the workflow at each stage.
Read articleA test harness is not a test suite — it is the infrastructure that makes test suites reliable, fast, and maintainable. This guide covers the five layers of a backend API test harness and the order in which to build them for maximum return on investment.
Read articleBoth practices exist to catch problems before they reach production — but at different layers. Harness engineering builds the validation infrastructure. Spec-first defines what correct looks like before a line of code is written.
Read articleFrontend and backend drift happens when the contract is agreed verbally and never written down. This guide shows how a shared OpenAPI spec enforces alignment across retries, version increments, and partial-failure scenarios.
Read articleAI coding tools drift without constraints — adding fields, renaming functions, expanding scope. This article shows how to structure prompts around your spec so the output stays inside the boundaries you set.
Read articleIdempotency needs to be decided in the spec, not discovered during a retry incident. This article walks through how to document idempotency keys, safe retry windows, and duplicate-detection behavior before implementation starts.
Read articleA step-by-step guide to turning an OpenAPI spec into an automated contract test suite that runs in CI. Covers Pact, schema validation, breaking-change detection, and what to gate on before merge.
Read articleOpenClaw works best when teams constrain what the model can decide before prompting starts. This guide covers the required artifacts, the operating model, and the runtime controls that prevent unreviewed changes from reaching production.
Read articleMost teams plan the rollout and improvise the rollback. This guide shows how to write both into the spec before implementation, including stop-loss thresholds, rollback definitions, and operator runbooks.
Read articleConcurrency bugs are almost always visible in the spec as missing decisions. This article covers how to surface race conditions, lock behaviors, and conflict resolution policies at the requirements stage rather than in production.
Read articlePerformance requirements that say "fast" or "responsive" are untestable. This article shows how to write latency targets, throughput thresholds, and degradation limits using the Given/When/Then format so that QA can verify them without interpretation.
Read articleError codes and retry behavior are often left to engineering judgment. This guide shows how to spec error taxonomy, client-facing messages, and retry contracts so that behavior is consistent and testable before the first line of code is written.
Read articleNon-goals prevent scope creep, but only if they name specific decisions. This article explains the difference between useful non-goals that stop review questions and vague exclusions that get ignored, with before/after examples from real spec reviews.
Read articleEdge cases buried in prose or left for engineering to "handle" consistently cause post-release defects. This article covers how to enumerate boundary inputs, permission edges, and failure states in a format QA can execute without interviewing the author.
Read articleChoosing the wrong versioning strategy creates breaking changes that reach clients without warning. This guide compares URI versioning, header versioning, and deprecation windows, with a decision matrix for common API lifecycle situations.
Read articleA detailed postmortem reconstruction showing how an under-specified payment retry behavior reached production and caused overcharges — and how a spec-first review would have caught the decision gap before code was written.
Read articleA full walkthrough of one CRM feature — from initial PRD to reviewable technical spec — showing the specific decisions that were made explicit, the acceptance criteria that were written, and the scope changes that were caught in review rather than in production.
Read articleA reusable spec document template covering mission, scope, non-goals, stakeholders, acceptance criteria, edge cases, rollout plan, and rollback definition. Includes a filled example and a blank version ready to copy into your team's workflow.
Read articleA diagnostic list of the failures that appear most often in spec reviews: vague acceptance criteria, missing non-goals, undefined failure behavior, and accountability gaps. Each mistake includes the symptom, the root cause, and the fix.
Read articleA pre-implementation checklist for spec authors and reviewers. Covers the 12 questions that catch the most expensive ambiguities before code is written, organized by the stakeholder who is best positioned to answer each one.
Read articleIntroducing spec-first discipline to an existing team is harder than writing specs solo. This guide gives a four-week adoption plan with specific weekly activities, success metrics, and strategies for handling resistance from engineers or PMs.
Read articleA spec is only as good as the tests that can be derived from it. This article shows how to write acceptance criteria, input boundaries, and failure conditions in a format that produces clear, non-overlapping test cases without requiring QA to interview the author.
Read articleThe most common objection to spec-first work is that it slows down agile delivery. This article examines where the two approaches actually conflict, where they reinforce each other, and how high-performing teams combine both without creating process overhead.
Read articlePRDs and technical specs are often confused or collapsed into one document — and that creates accountability gaps. This article clarifies what each document owns, which roles write and review each, and how they hand off to each other in a healthy delivery workflow.
Read articleSpec-first development means making the hidden decisions visible before coding starts. This complete guide covers the core model, the three questions every spec must answer, how the approach compares to informal delivery, and how to apply it from the next sprint forward.
Read article