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

Why does a product keep a flow, a feature, or an architectural rule after everyone has forgotten its purpose? Michal Cichra approaches that problem from experience at Microsoft, Red Hat, and a decade spent on one product. At Safe Intelligence, his team had just released an agent-testing product. The consistency problems surrounding AI were familiar: teams already struggled to preserve the reasons behind their decisions.

Consider the five-monkeys ladder story that opens his explanation. Monkeys are punished with cold water when one tries to reach bananas; eventually, they stop one another from climbing. Replace the monkeys one by one, and the prohibition persists even after none of those present experienced the original punishment. Cichra explicitly questions whether the story is an urban legend. Its value here is as an analogy: a rule can survive long after its rationale disappears.

Humans forget, and humans leave. LLM context gets compacted, and an agent cannot depend on durable memory of earlier work. Eventually someone asks why a flow exists, what problem a feature solves, why the code has a particular shape, or where a change belongs. The founding engineer may no longer be available to explain. AI can make this familiar organizational problem arrive sooner. The rationale needs to remain recoverable outside the person or session that produced it.

An Architecture Decision Record, or ADR, records why a technical choice exists and how the team intends to enforce it. References and code examples make the decision actionable. The document should explain more than the rule itself: someone encountering the constraint needs enough context to make a correct change.

Cichra’s example is a layered architecture intended to prevent N+1 database queries. Import linting restricts which modules may depend on which others. Database reads return plain data shapes rather than ORM objects, so downstream code does not receive objects that can issue additional queries implicitly. The boundary controls both where database access happens and what crosses into the rest of the application; he also connects these constraints with avoiding duplication. He describes roughly fifty other ADRs defining the product’s architecture.

There is no mandatory ADR format. A text document can explain a decision, but it cannot enforce that decision on its own. A separate tool must detect the violation and provide useful feedback: which rule was broken, why the rule exists, and how to fix the problem. The agent can then retrieve the ADR for details. Recording the relevant files, folders, or language scope helps connect a failure to the code and decision it concerns.

A Product Requirements Document, or PRD, preserves a different kind of intent: why a feature exists, which problem it solves, and how the user moves through the application to use it. It can be short. The useful connection is between the problem, the desired outcome, and the journey that takes the user from one to the other. An exhaustive document is not required to retain that connection.

This is useful for an agent implementing the feature, but it is equally useful for the person returning to it six weeks later. The document makes the original purpose available when memory no longer does.

A written specification leaves a validation question open: how do you know the running product behaves as described? Markdown captures intended behavior, but does not test conformance. Reviewing generated tests is not necessarily a comfortable substitute; Cichra finds AI-written tests even harder to read than AI-written code. Behavior-Driven Development, or BDD, supplies an intermediate layer that describes behavior in language a person can review.

Cucumber makes that layer executable. Scenarios can connect directly to PRDs and critical user journeys. Their steps map to code that exercises the application and checks the result. This connects the readable specification to an actual validation path rather than leaving it as a description beside the implementation.

For example, a profile-saving journey can express the initial state, the action, and the expected persistence without exposing test plumbing:

Feature: Save a profile name
  Scenario: A saved name survives reopening the profile
    Given I am signed in
    And I am on my profile page
    When I change my display name to "Mira"
    And I save my profile
    And I reopen my profile page
    Then my display name should be "Mira"

Each step needs an executable implementation; the scenario alone does not perform the test. Its wording gives reviewers a clear behavioral contract to inspect before they examine the code behind it.

The scenario vocabulary belongs to the team. Different formulations can describe the same journey, provided people can read, review, and understand what the application is expected to do. Scenarios can also refer back to the documents explaining why that behavior exists. The result is a connection between product purpose, expected behavior, and executable checks.

Consistent interfaces need the same treatment. A design system and pattern library provide the shared vocabulary that made UI work consistent before agents were involved. Start with a concrete definition: a primary button is blue, with a specified shape and size. Then define its usage rule—for example, only one primary button should be visible on a page at any point in time. Appearance and usage are separate decisions, and both need to be explicit.

Components turn those decisions into reusable pieces. Document their colors, variants, and states, then provide previews and snippets that let humans and agents inspect them. Review the previews against the visual principles before reusing the components. As with code, build larger patterns by composing smaller pieces; otherwise each new screen becomes another opportunity to invent a competing convention.

Documents and reusable components still leave an operational question: how do people and agents keep following them? Cichra’s answer is a repeating work-and-feedback loop. His team’s harness combines Git hooks, skills, CI, linters, and other checks. An agent tasked with delivering a pull request must interact with Git, which provides a natural place to trigger feedback.

Hooks run predefined tasks locally, and CI runs the same tasks remotely. That duplication matters: local hooks can be bypassed, including with --no-verify, so hooks alone do not make checks unavoidable. Repeating the checks in CI catches changes that skipped local validation. The checks cover linting, formatting, type checking, code duplication, architectural boundaries, and document linting.

Automate mechanical rules so review can concentrate on higher-level decisions. Tabs, spaces, formatting, and other settled conventions do not need to be renegotiated in each code review. Encoding them as checks gives contributors consistent feedback and leaves reviewers more attention for design, behavior, and architectural consequences.

Architecture checks make abstract layering rules concrete by controlling module imports. In Cichra’s end-to-end BDD suite, tests cannot access the database or import modules capable of accessing it. That restriction forces the suite to exercise the application through browser behavior instead of reaching behind the interface to manipulate or inspect database state.

The product applies a related boundary: rendering templates cannot talk to the database. Together with returning plain data rather than ORM objects, this removes a route by which rendering can trigger an additional query for each item. Cichra describes his architecture as preventing N+1 queries entirely; the generalizable mechanism is narrower—preventing database access from rendering blocks that class of implicit query, rather than proving every database path is free of N+1 behavior. The aim is to make an unwanted dependency impossible instead of repeatedly finding its consequences in review.

The feedback loop then has a concrete repair path:

1. The agent attempts to commit or push a change.
2. A check detects a violation and rejects the attempt.
3. The failure links to the relevant decision document.
4. The agent reads the rationale, corrects the change, and tries again.

A rejection becomes useful when it points to the information needed to resolve it. The durable document restores context at the moment the agent needs it.

The cycle of doing work, receiving feedback, and revising stays the same across product features, UI work, and backend changes. What changes is the information and feedback most useful for the current task. Skills supply that focus.

• ADR and PRD work: An ADR skill guides the agent to decision records and the code they affect. PRD guidance serves the corresponding product-document workflow.
• UI work: The iteration loop skips some checks to prioritize quick browser feedback.
• Testing: A test skill uses code coverage and changed files to select the relevant portion of the suite rather than running everything.
• Goal execution: Decisions made by the model are retained so they can be reviewed later.

These skills specialize the work inside the loop without replacing its basic structure.

This approach has a cost: retrieving and understanding the relevant documents consumes context. Cichra reports that initial research can use roughly half the context window. He nevertheless tentatively describes the approach as working over the preceding half year. In his own sessions, he reports twenty or fifty context compactions without losing the ability to continue, because important information survives or can be retrieved again. These are personal experience reports, not measured reliability results.

The intended outcome is a multi-hour session in which an agent can pursue a clear goal autonomously while operating within explicit rules. That requires more than retaining every detail in the current conversation. It requires a way to recover the details that matter when the conversation no longer contains them.

Decision records preserve why architectural choices were made; product documents preserve why features exist; readable executable scenarios connect those intentions to behavior. Design systems extend the same discipline to interfaces, including enforceable constraints such as prohibiting inline styles outside the designated system. The harness connects those materials to the work itself: a change encounters a check, the check points back to intent, and the next revision can use that intent.