What is a Product Behavior Contract?
A Product Behavior Contract (PBC) is a Markdown-first specification of what a software product promises to do — its behaviors, rules, states, and actors in one readable contract, with each claim grounded in the code that proves it. It’s written so product, engineering, QA, and security can read the same artifact, each from their own lens.
It is not a requirements doc — that’s intent. It is not a test suite — that’s pass or fail. It’s the layer in between that nobody has owned: what the product commits to, in plain language, backed by evidence you can check.
Why it exists
Every layer of software has a source of truth. Code style has linters. Architecture has ADRs. APIs have OpenAPI. But product behavior — what happens when a subscription lapses, who is allowed to change this, why this refund fires — lives in people’s heads, in chat threads, and in code that only its author can read.
That gap was always there. AI coding agents made it the main event. Code now ships faster than any human can absorb it: you review the diff, sign off, move on — and a week later you can’t say whether a behavior was a decision or a default your agent left in. The industry has started calling this comprehension debt — the distance between what a system does and what anyone actually understands about it. The faster the code is written, the more the understanding becomes the scarce part.
You can’t document your way out of it, because documentation inherits the same gap: prose written at a point in time, disconnected from the code, drifting from the day it’s saved. What’s needed isn’t more docs. It’s a different kind of artifact — one tied to the evidence and honest about what it doesn’t know. That artifact is a Product Behavior Contract.
What makes a PBC different
It describes the product, not the agent. As the space fills up you’ll see related ideas — runtime behavioral contracts that constrain what an autonomous agent is allowed to do, enforced while it runs. A PBC sits upstream of that: it describes what the product does and commits to, in terms a person can read and an agent can ground against — before anything is enforced. You can’t enforce what no human has agreed is true.
It isn’t docs, and it isn’t scaffolding. Wikis and design docs describe intent and then drift. Spec-driven development writes code from a spec. A PBC works the other direction: it captures the truth of a product that already exists — every claim traced to the file or function that proves it, and every gap flagged honestly as a gap rather than smoothed over with confident prose.
What a PBC looks like
A PBC is plain Markdown — a .pbc.md file — with structured blocks inside readable prose. Each file describes a slice of the product (auth, billing, tenancy) using a small, lintable set of block types:
pbc:behaviorwhat the product doespbc:rulesconstraints that always holdpbc:statesthe states things move throughpbc:actorswho acts on the systempbc:glossarythe shared vocabularypbc:groundinglinks each claim to its source code
Two things make it trustworthy. Grounding: every claim links back to the specific file or function it was traced from, so you verify it instead of trusting it — and when the code changes, you know which behaviors are affected. And honest status: a claim the evidence fully supports reads differently from one that’s still uncertain, and where the evidence runs out, the contract says so. Because it’s Markdown in your repo, you own it, version-control it, diff it, and read it without any tool. See live examples in the viewer.
The open foundation
The .pbc.md format is an open, vendor-neutral specification (currently v0.6.0-draft): the spec, docs, and examples are CC BY-SA 4.0; the reference CLI and viewer are Apache-2.0. It ships with a reference CLI and a browser viewer, all open source at github.com/stewie-sh/pbc-spec, with live examples at pbc.stewie.sh. The format is designed to outlive any single tool — if you ever stop using ours, your contracts are still yours and still readable.
Stewie Reflect is the product built on this foundation: point it at a repo snapshot and it writes a first-pass Product Behavior Contract — an owner’s manual for the product inside — with every claim grounded in the evidence and the gaps flagged. The format is open; the intelligence that recovers it is the product.