AI EngineerJune 3, 202612m

BDD, ADR, PRD, WTF: Capturing Decisions for Humans and AI Alike — Michal Cichra, Safe Intelligence

TL;DR

Humans and LLMs break for the same reason: limited context: Cichra uses the five-monkeys-and-banana story to frame the problem, saying teams forget why code and product flows exist, while LLMs compact context and have no memory.
ADRs turn architecture into something agents can actually follow: An architecture decision record captures why a rule exists, what files it applies to, and how it is enforced, such as linting module imports to prevent N+1 queries or blocking ORM objects from leaking out of database reads.
PRDs should stay light but preserve intent: Instead of massive docs, he recommends short product requirement documents that record the problem, goal, and user path through the app, mainly so both agents and humans still know why a feature exists six weeks later.
BDD closes the gap that spec-driven development leaves open: Using Cucumber, teams can write human-readable, executable scenarios tied back to PRDs and critical user journeys, which he says are often easier to review than AI-generated tests.
Design systems matter even more with agents building UI: He argues for documented component rules like "only one primary button visible on a page at a time," plus previews and reusable components so agents can see and reuse the intended patterns instead of generating chaos.
The real enforcement mechanism is the loop: Safe Intelligence uses git hooks, CI, linters, formatting, type checks, duplication checks, architecture checks, and document linting so agents get rejected, sent back to the right doc, and iterate until the pull request conforms.

The Breakdown

Michal Cichra argues that humans and LLMs fail for the same reason, limited context, and his fix is a practical documentation-and-enforcement stack: ADRs for architecture decisions, PRDs for feature intent, BDD for executable behavior, design systems for UI consistency, and a tight git-hook-to-CI loop that forces agents to follow the rules. The punchline is simple: if you cannot find a decision, you cannot enforce it, and if you cannot enforce it, both people and agents will drift.