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

Key Concepts

• ADR (Architecture Decision Record): A document capturing the "why" and "how" behind architectural choices.
• PRD (Product Requirements Document): A concise document outlining the problem, goal, and user journey for a feature.
• BDD (Behavior-Driven Development): A methodology using human-readable specifications (e.g., Cucumber) that are also executable as tests.
• Context Compact: The tendency for LLMs to lose or compress information over long sessions, necessitating external documentation.
• Reinforcement Loop: A system of git hooks, CI/CD, and linters that enforces rules and provides feedback to AI agents.
• Design System: A library of reusable components and visual rules to ensure UI consistency.

---

1. The Problem: Context Loss and Consistency

The speaker highlights a fundamental challenge in software development: teams often lose the "why" behind their code as time passes or original engineers leave. This is exacerbated by AI agents, which suffer from "context compact"—the inability to retain long-term memory or the rationale behind specific architectural patterns. Without explicit documentation, both humans and AI fall into the "monkey and the ladder" trap: following rules or patterns without understanding the underlying reasoning.

2. Frameworks for Capturing Decisions

To mitigate context loss, the speaker advocates for three primary documentation frameworks:

• ADR (Architecture Decision Record): Used to document architectural constraints.
  • Example: To prevent N+1 database queries, the team enforces a rule where database reads must return plain shapes rather than ORM objects. This is enforced via linting module imports.
• PRD (Product Requirements Document): A lightweight document that connects the problem to the solution and the user journey. It serves as a reference for both the developer and the AI agent to understand the feature's intent.
• BDD (Behavior-Driven Development): Using tools like Cucumber, teams write specifications in human-readable language. These specs are then parsed and executed as code, closing the gap between documentation and actual product behavior.

3. UI Consistency and Design Systems

Maintaining UI consistency with AI is difficult. The speaker suggests:

• Pattern Libraries: Defining specific components (e.g., a primary button) with strict rules (e.g., only one primary button per page).
• Component Previews: Creating visual snippets that agents can "see" and reference to ensure they adhere to the established design system.
• Enforcement: Using automated checks to prevent the use of inline styles or non-compliant components.

4. The Reinforcement Loop: Enforcing Rules

The speaker emphasizes that documentation is useless if it isn't enforced. The "loop" is the mechanism that keeps the AI agent aligned:

• Git Hooks & CI: Every pull request is subjected to automated tasks (linting, formatting, type checking, architecture checks).
• Automated Feedback: If an agent violates a rule (e.g., accessing the database from a forbidden module), the CI pipeline rejects the commit and provides a link to the relevant ADR or documentation.
• Shift in Code Review: The speaker argues that style, tabs, and basic formatting should no longer be topics for human discussion; they should be automated rules. Human review should focus on high-level concepts and architectural integrity.

5. Methodology: Skills and Focus

While the reinforcement loop remains constant, the "skills" applied within that loop vary based on the task:

• ADR Skill: Agents look up architectural rules before modifying code.
• Test Skill: Agents identify and run only the relevant subset of tests based on code coverage and file changes, rather than the entire suite.
• UI Skill: Agents are forced to iterate in a browser environment to verify visual consistency.

6. Notable Quotes

• "One thing harder than reading an AI code is reading AI tests."
• "What you cannot find, you cannot enforce."
• "There was a time where code reviews were about style and tabs and spaces and there is no space for that anymore. All these things are not for discussion. They are rules and they are enforced."

Synthesis and Conclusion

The core takeaway is that for AI agents to be effective and autonomous, they require a structured environment where decisions are explicitly recorded and automatically enforced. By combining ADRs, PRDs, and BDD with a robust CI/CD reinforcement loop, teams can prevent "context compact" and ensure that AI agents operate within the established architectural and design boundaries of the product. The goal is to move from manual, discussion-heavy development to a system where rules are codified, automated, and continuously validated.