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

Michal Cichra from Safe Intelligence addresses a critical challenge in modern software development, particularly when using AI agents: maintaining consistency and preserving institutional knowledge. The core problem, illustrated by the “five monkeys” analogy, is that teams—and LLMs with their limited context—inevitably lose the “why” behind architectural and product decisions over time.

Capturing Decisions with ADRs and PRDs

To combat this, the talk advocates for systematically capturing decisions:

• Architectural Decision Records (ADRs): These documents go beyond stating what a rule is; they explain why it exists. For example, an ADR might state that to prevent N+1 queries, rendering templates are forbidden from accessing the database. This rule is then enforced by linting module imports. When an agent (or human) violates this rule, the enforcement tool links directly to the ADR, providing the context needed to understand the problem and fix it correctly.
• Product Requirements Documents (PRDs): These are lightweight documents that capture a feature’s purpose, the problem it solves, and the intended user journey. They serve as a crucial reference for developers and agents to stay aligned with the product goals.

Closing the Loop with Behavior-Driven Development (BDD)

Spec-driven development is popular but leaves a gap: how do you ensure the final product actually behaves according to the markdown spec? Cichra argues that “one thing harder than reading AI code is reading AI tests.” The solution is to revive Behavior-Driven Development (BDD) using Cucumber.

BDD provides a human-readable, executable layer that connects directly to PRDs and user journeys. By writing scenarios in a format like Gherkin (Given, When, Then), teams create specifications that are both understandable by product managers and directly executable as tests. This closes the loop between the specification and the implementation, ensuring the product does what it’s supposed to do.

The Enforcement Harness

The system’s power lies in its enforcement mechanism, or “harness.” This is a continuous loop built around the development workflow:

1. The Goal: An agent’s objective is to deliver a pull request.
2. The Gate: To do so, it must use git. The process is guarded by git hooks and CI pipelines.
3. The Rules: These hooks and CI jobs run a battery of automated checks: linting, formatting, type checking, and, most importantly, architectural validation. For example, a linter can be configured to make N+1 queries structurally impossible by forbidding database-accessing modules from being imported into rendering templates.
4. The Feedback Loop: If a commit is rejected, the agent receives a link back to the relevant ADR or rule, reads the document to understand the context, and iterates on the solution. This automates away debates over style or settled architectural patterns, allowing code reviews to focus on higher-level concepts.

Consistent UIs and Managing Context

For front-end development, the same principles apply. Design Systems and Pattern Libraries are presented as the definitive way to build consistent UIs. Agents are given a library of components, rules (e.g., “only one primary button per page”), and code snippets, and are enforced to use them, preventing stylistic chaos.

While this approach is context-heavy for LLMs, the speaker notes that context compacts are manageable. Because all critical rules and decisions are recorded in git (as ADRs, specs, etc.), the agent can always look them up again, enabling long-running, autonomous sessions within a well-defined set of guardrails.

• Tags:
• LLM
• Testing
• AI Agent
• CI/CD
• Software Architecture
• BDD
• Spec-Driven Development
• ADR
• Design Systems
• Cucumber
• Git Hooks