A behavior card is a short, self-contained statement of one thing a product must or must not do, written so a coding agent can build and test it without reading anything else. On the agentic health startup I’m building, we converted 72 spec documents, over 1,000 pages, into 1,300 behavior cards. The documents still exist as the product’s source of truth. The cards are what the agents build from. That change, on the fourth version of the spec, is what let the build run.
Why didn’t the spec documents work?
They were written for people. Design documents carry their own history: the options we rejected, the questions still open, reviewer comments, a flag marking a decision as pending long after it was made. A person reading them knows which paragraph is stale. An agent reads every line as current.
There was also too much of it. With over 1,000 pages, the agents got about halfway and lost the story. Some stopped reading. Others spent heavily on tokens combing the corpus for an answer buried deep in the corpus.
Daniel Sogl’s recent JAVAPRO article on spec-driven development argues that missing project context, not weak models, is the root cause of poor AI-generated architecture. His example had too little context. Ours had too much, unranked. Both fail the same way: the agent can’t find the decision it needs.
Research points the same direction. An ETH Zurich study of AGENTS.md files found that LLM-generated context files slightly lowered coding agents’ success rates and raised inference cost by over 20 percent, while short human-written files helped a little (Gloaguen et al., arXiv 2602.11988). A 2026 preprint testing agents across customer support, healthcare claims and legal drafting found structured context lifted scores from 3.15 to 5.49, while adding more hardening on top slightly lowered them (Bousetouane, arXiv 2607.14275). More context is not better. Clearer context is.
What goes on a card?
Each card holds one behavior in its current state, in plain sentences. No history, no debate, no cross-reference the agent has to chase.
Rule: the behavior, as must / must not. Illustrative example: when a user describes an emergency, the product must show emergency guidance before anything else and must not continue the intake.
Function: the part of the product it governs. Example: the intake conversation.
Test criteria: how to tell it was built right. Example: emergency phrases trigger the guidance screen on the first turn, every time.
Dependencies: other cards it relies on or affects. Example: the emergency phrase list and the intake flow order.
Cards are grouped into packets, so the engineer can sequence work one feature or page section at a time. A few short context documents sit alongside them to help the agent interpret intent where a single card can’t carry it.
Definition — behavior card: a self-contained specification of one product behavior, written as must / must-not rules with test criteria and dependencies, designed for a coding agent to execute directly.
How do you convert documents into cards?
The conversion is a transposition, not a redesign. No features change. What changes is the form.
Settle conflicts first. If two documents disagree, a card will carry the disagreement. Resolve contradictions across the corpus before writing a single card.
Strip the process residue. Decision history, open questions and approval notes move to decision records the agents never see.
One behavior per card. Simple must / must-not sentences. If a card needs a paragraph of explanation, it is two cards.
Group into packets. Organize cards by feature so engineering can build and test one slice at a time.
Red-team the canon. We spent a weekend testing the cards for conflicts and accuracy before the agents saw them.
Let the agent ask. Before generating real code, the agent spent 12 to 14 hours over two days questioning the canon. Many questions were about things we thought we had decided.
That last step surprised me most. The agent’s questions weren’t about code. They were about what the product should do in situations the documents covered in prose but never pinned down. Those are market, user, operations and revenue decisions, surfacing in the spec instead of in testing.
Why keep the spec documents at all?
They serve a different reader. The full documents hold the reasoning: why a behavior exists, what we tried first, what the business needs it to protect. That is the product’s intellectual property and the reference for future design work. We locked the final document set as the historic source of truth.
The cards serve the build. They are derived from the documents, and when a behavior changes, the change is ruled once and carried into both. Two artifacts, two audiences, one decision.
What changed once the agents built from cards?
The build moved. Agent output with QA landed close to spec. The engineer’s hands-on time settled at about an hour per round of changes, with agents running day and night. The engineer distilled the cards into one working reference file and merged 20 pull requests against it in the first week.
It isn’t perfect. We still build one feature at a time to contain regressions, and some cards need supplemental guidance to land the intent. But the agents stopped getting lost.
Does this apply beyond product builds?
Yes. Any work an agent executes from documents has the same problem. Operating procedures, runbooks and policy manuals are written for people, carry their own history, and assume a reader who knows what is current. If an agent will run the process, the process needs cards.
How does PBA produce cards?
Product Behavior Architecture (PBA) is an AI-native product operating system that starts at the business model — market viability, user experience, operational feasibility and revenue model integrity — and carries those decisions through design into behavior cards an agent can execute. The documents hold the thinking. The cards hold the decisions.
Takeaway
Agents don’t need more spec. They need each decision stated once, in its current form, where they can find it. A behavior card does that. Converting our 72 documents into 1,300 cards is what turned a stalled build into a running one.
AI builds fast. How are your teams defining and deciding before the build?
Frequently Asked Questions
What is a behavior card?
A self-contained specification of one product behavior, written as must / must-not rules with test criteria and dependencies, so a coding agent can build and test it without reading anything else.
Why do coding agents struggle with long spec documents?
Long spec documents are written for people and carry history, open questions and unresolved conflicts. Agents read every line as current, so they stall, re-examine settled decisions, or spend heavily searching for the answer.
Do behavior cards replace the spec documents?
No. The documents remain the product’s source of truth and hold the reasoning. The cards are derived from them and are what agents build from; when a behavior changes, the change is ruled once and carried into both.
If you want to compare notes on your own spec set, book a discovery call: calendly.com/besserhealth/discovery
Related: Can a product team really run a 24-hour delivery cycle with AI agents? · Context Rot Is the New Technical Debt. · The Specification Was Perfect. Engineering Couldn’t Use It.
