liveBook · Manning

Executable specification

As explained in Vibe Engineering

A specification expressed in a form that can be executed or checked automatically to verify system behavior.

AI-generated code can look correct while failing a requirement nobody made explicit. An executable specification turns intended behavior into a machine-checkable contract, such as a human-authored test suite. The agent generates an implementation; the contract, not the model’s choice of code, defines what must pass. section 1.4 section 1.8

Use prototypes to discover rules and edge cases, then encode them before generating production code. Run the checks in a verification gate, such as a CI/CD pipeline, and verify before merging. The specification can cover behavior, performance, and security, but its author remains responsible for deciding what correctness means. section 1.5 section 1.3 section 1.7

ISBN validation contract

A Python ISBN-13 validator must accept valid numbers with or without hyphens and reject invalid lengths, non-numeric characters, and incorrect checksums. A human-authored pytest suite checks those cases against generated implementations. This catches a hyphen-handling defect that syntactically clean code can conceal. section 1.4

import pytest
# Assume is_valid_isbn13 is the function to be generated
def test_valid_isbn_with_hyphens():
    assert is_valid_isbn13("978-0-306-40615-7") is True
def test_valid_isbn_without_hyphens():
    assert is_valid_isbn13("9780306406157") is True
def test_invalid_checksum():
    assert is_valid_isbn13("978-0-306-40615-0") is False
def test_invalid_length():
    assert is_valid_isbn13("978-0-306-40615") is False
def test_contains_non_numeric_characters():
    assert is_valid_isbn13("978-0-306-40615-X") is False

The pytest cases make the ISBN contract runnable and show the specific inputs and outcomes it checks. section 1.4

Refund policy contract

Turn “refunds within 30 days” into checkable scenarios for approval, expiry, and partial refunds exceeding the remaining amount. An agent can generate step definitions and property tests around the time boundary, while humans review the policy, time-zone assumptions, and rounding. section 1.5

Feature: Refund policy
  Rule: Time-bounded, single-order refunds
    Example: Within 30 days is allowed
      Given an order "O1" purchased at 2025-08-01T10:00:00Z
      When a refund of 25.00 USD is requested at 2025-08-28T09:59:00Z
      Then the refund is approved and remaining refundable equals 75.00 USD
 
    Example: After 30 days is rejected
      Given an order "O2" purchased at 2025-08-01T10:00:00Z
      When a refund is requested at 2025-08-31T10:00:01Z
      Then the request is rejected with reason "expired"
 
    Example: Partials must not exceed the original
      Given prior refunds of 90.00 USD on a 100.00 USD order
      When a refund of 20.00 USD is requested
      Then the request is rejected with reason "exceeds-remaining"

The Gherkin scenarios show how a product rule becomes concrete inputs, decisions, and rejection reasons. section 1.5

Passing tests is not proof that the contract is complete. The ISBN suite initially omitted valid inputs containing spaces: an implementation could pass every listed test and still fail real input. Ask an AI assistant to suggest missing cases, review its suggestions, and keep updating the contract as the team learns. Mechanical verification cannot replace judging whether the checks match the business intent. section 1.4.1 section 1.8

How Vibe Engineering covers it

How deep it goes
Works through test-suite and scenario-based contracts, their enforcement, and the risk of omitted requirements.
Examples
Uses ISBN-13 validation and a 30-day refund policy to expose formatting, checksum, time-boundary, and partial-refund cases.
What you can do after
Apply it via pytest or Gherkin scenarios to specify expected outcomes and check generated implementations.
How it connects
Connects specifications to test-driven development, CI/CD, context engineering, and semantic verification.

Also explained in

Compare how 2 books explain executable specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vibe Engineering. The section links point to the parts of the book it draws on.