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

Michal Cichra, Safe Intelligence

AI Engineer Europe 2026

[Talk page](https://ai.engineer/talks/504PvfXou5Y-bdd-adr-prd-wtf-capturing-decisions-humans) · [Video](https://www.youtube.com/watch?v=504PvfXou5Y)

## BDD, ADR, PRD, WTF: Capturing Decisions for Humans and AI Alike

Decision records, executable scenarios, reusable UI patterns, and automated checks preserve the reasons behind a product when people forget and agent context disappears.

Familiarity with Git, automated tests, and database-backed applications will help with the examples.

### Why do we still have this rule?

[0:22](https://www.youtube.com/watch?v=504PvfXou5Y&t=22s)

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.**

![Slide titled WTF highlights limited context, human forgetting and departures, LLM compaction and missing memory, alongside questions about flows, problems, code shape and placement.](https://ai.engineer/api/talk-essay-media/0a504cdb9c7ff058fa7849e3893bc26740d8b2e26340a3cb401fa50591f4ff01)

Humans and LLMs share limited context, leaving questions about product and code decisions.

### Record the architectural reason and the enforcement path

[2:03](https://www.youtube.com/watch?v=504PvfXou5Y&t=123s)

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.

### Keep the product purpose lightweight

[3:26](https://www.youtube.com/watch?v=504PvfXou5Y&t=206s)

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.

### Make the behavior specification executable

[4:07](https://www.youtube.com/watch?v=504PvfXou5Y&t=247s)

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](https://cucumber.io/docs/cucumber/step-definitions/) 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.

![Enter Cucumber slide with a Feature and Given/When/Then scenario example, text linking scenarios to PRDs and critical user journeys, and a cartoon cucumber.](https://ai.engineer/api/talk-essay-media/b9a23a3e5b49703c089956d04d4f40db2918f4a17fe0dac1f4354907b488e0b6)

Cucumber connects executable specifications to PRDs and critical user journeys.

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

```gherkin
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.

### Give agents a visual vocabulary they can reuse

[6:00](https://www.youtube.com/watch?v=504PvfXou5Y&t=360s)

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.

### Put feedback on the path to a pull request

[7:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=438s)

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](https://git-scm.com/docs/githooks), 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.

### Prevent forbidden dependencies, then explain the repair

[8:43](https://www.youtube.com/watch?v=504PvfXou5Y&t=523s)

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.

![Example: Enforced Architecture slide lists import boundaries, BDD tests barred from direct database access, application layers, commit-time failures and early agent feedback.](https://ai.engineer/api/talk-essay-media/a60a3c9ab08ea4094d4d0c14982ee97e4d4765338b88213373944e1268405a9c)

Architecture rules link to ADRs and reject dependency violations at commit time.

### Keep the loop, change its focus

[9:50](https://www.youtube.com/watch?v=504PvfXou5Y&t=590s)

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.

### Make recovery possible after context compaction

[11:04](https://www.youtube.com/watch?v=504PvfXou5Y&t=664s)

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.

![TL;DR slide lists recording decisions, capturing goals, running specs, ruling the UI and enforcing the loop, followed by May the SPEC be with you.](https://ai.engineer/api/talk-essay-media/e09ffa3e0a03b06536a9e6fe0f861b38508ae3febbd18fa361a7e660293a94aa)

ADRs, PRDs, BDD, a design system and a harness form the closing summary.

## Resources

- [Cucumber step definitions](https://cucumber.io/docs/cucumber/step-definitions/) — How readable Gherkin scenario steps connect to executable code, with examples in several languages.
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) — Michael Nygard's lightweight approach to recording architectural context, decisions, status and consequences.
- [Git hooks reference](https://git-scm.com/docs/githooks) — Reference for checks triggered during commits and pushes, including rejection behavior and bypass options.
- [Introducing Spec27](https://safeintelligence.ai/introducing-spec27-spec-driven-validation-for-ai-applications-and-agents/) — Safe Intelligence's April 2026 announcement of specification-driven validation for AI applications and agents.
- [Understanding ORM relationship loading](https://docs.sqlalchemy.org/en/20/orm/queryguide/relationships.html) — SQLAlchemy examples explaining implicit database queries, eager loading and guards against unwanted lazy loads.

## Slides

### AI Engineer Europe

[0:00](https://www.youtube.com/watch?v=504PvfXou5Y&t=0s) [AI Engineer Europe logo in white on a black background.](https://assets.ai.engineer/sites/aiecode2025/sha256/24e440bf5dfd4ecccd4fffdc9ef9243be07fff10b16e87c6b80fbc594828e3ea.webp)

AI Engineer
EUROPE

### Presenting sponsor

Google DeepMind is the presenting sponsor.

[0:05](https://www.youtube.com/watch?v=504PvfXou5Y&t=5s) [Google DeepMind presenting sponsor card.](https://assets.ai.engineer/sites/aiecode2025/sha256/9a43b90b83b6eca77e82f00387f025461fb2cd84d99ed7f55e0f7cc2bbdddc7d.webp)

PRESENTING SPONSOR

Google DeepMind

### Platinum sponsors

[0:10](https://www.youtube.com/watch?v=504PvfXou5Y&t=10s) [Platinum sponsor logos for Braintrust, WorkOS and OpenAI.](https://assets.ai.engineer/sites/aiecode2025/sha256/ff5cdbf449d7a81d1741a4bf18c6f35bc5f477b750e8407ef0b11cc0a5ce21af.webp)

PLATINUM SPONSORS

Braintrust
WorkOS
OpenAI

### Michal Cichra

Cichra draws on his product experience to discuss AI consistency and capturing decisions, and invites attendees to find him at the booth.

[0:21](https://www.youtube.com/watch?v=504PvfXou5Y&t=21s) [Michal Cichra introduction slide with Spec27 and Safe Intelligence logos and an invitation to visit the booth.](https://assets.ai.engineer/sites/aiecode2025/sha256/afdb0cfe28f8038497c3db2b9e1239c801a38c8d61dfd731a85feaeb18b38eee.webp)

Michal Cichra

/Spec27
SAFE INTELLIGENCE

Find me at the booth.

2

Interface text:
AIE
Google DeepMind

### BDD, PRD, ADR, WTF

Cichra introduces ADRs, PRDs and BDD after raising AI consistency and decision capture as recurring product challenges. He lists a design system as a bonus.

[0:51](https://www.youtube.com/watch?v=504PvfXou5Y&t=51s) [Slide asks why the acronyms matter and defines ADR, PRD and BDD, with a design system listed as a bonus.](https://assets.ai.engineer/sites/aiecode2025/sha256/637628840ad3cafdf3b0248b3a76bcc358c3a94866c8874d0434d5b028f4069a.webp)

BDD, PRD, ADR, WTF

WTF  Why does any of this matter?
ADR  Architecture Decision Record
PRD  Product Requirements Document
BDD  Behavior Driven Development
+  Bonus: design system

3

Interface text:
AIE
Braintrust
WorkOS
OpenAI

### The 5 Monkeys Story

In the story, monkeys learn to stop climbers after cold showers. Even after every original monkey is replaced, the group keeps attacking climbers without knowing why.

[0:57](https://www.youtube.com/watch?v=504PvfXou5Y&t=57s) [A story about monkeys continuing to prevent climbing after the original monkeys have been replaced.](https://assets.ai.engineer/sites/aiecode2025/sha256/ec793dee4f6e7a4645c8831f69cf04f55dce750431403d8e7555ff5e319fcff6.webp)

The 5 Monkeys Story

Cage. Ladder. Bananas on top.
Cold shower every time one climbs.
Other monkeys beat up the poor fella.

Replace them one by one.
None of the OGs remain.
And yet — they still beat up the climber.

4

Interface text:
AIE
Braintrust
WorkOS
OpenAI

### WTF

Humans forget or leave, while LLMs compact context and lack memory between sessions. Both can leave teams asking why a flow or code exists when the founding engineer is unavailable.

[1:24](https://www.youtube.com/watch?v=504PvfXou5Y&t=84s) [Humans and LLMs have limited context, leaving questions about product flows and code unanswered.](https://assets.ai.engineer/sites/aiecode2025/sha256/2e9104822eef4a2d18589eacb7a3b0f6e6a164144fc24195df7ff864fa02e696.webp)

WTF

Humans and LLMs share one trait.

Limited context.
• Humans forget · people leave
• LLMs compact · no memory between sessions

Questions pile up:
• Why do we have this flow?
• What problem is this solving?
• Why is the code shaped like this?
• Where does this belong?

You may not have the founding engineer to answer.

5
AIE
AI Engineer EUROPE

### ADR

Architecture decision records capture what was decided, why, and how it is enforced. Cichra gives import linting as an example: it enforces code layers designed to prevent N+1 queries.

[2:01](https://www.youtube.com/watch?v=504PvfXou5Y&t=121s) [Architecture decision records capture what was decided, why, how it is enforced, and references for detail.](https://assets.ai.engineer/sites/aiecode2025/sha256/9fc520333d2536267d7fb8ab62f7a41b4f88e74959642f4c171b38ac0a324b60.webp)

ADR

Architecture Decision Record.

Record. Your. Decisions.

• What decision was made
• WHY it was made
• HOW it is enforced
• ADR for the decision
• Reference docs for examples and detail

6

Interface text:
AIE
AI Engineer EUROPE

### ADR: what it looks like

After direct template queries hid N+1 problems until production, this ADR requires templates to receive only pre-fetched typed data. import-linter blocks ORM imports in templates.

[2:45](https://www.youtube.com/watch?v=504PvfXou5Y&t=165s) [An example decision record bans ORM queries in templates and describes import linting as enforcement.](https://assets.ai.engineer/sites/aiecode2025/sha256/4d2e59773457a0db688045ea0b1105e3cd57e03fe5c8b4080a776e242d0df9fe.webp)

ADR: what it looks like

---
id: "038"
status: Accepted
enforced_by: import-linter
file_patterns:
  - "*/templates/**"
  - "*/templatetags/**"
---

# No ORM queries in templates

Context: Templates called .filter() and .count() directly, making N+1 queries invisible until production.

Decision: Templates receive only pre-fetched typed data. ORM models are banned from the template layer.

Enforced: import-linter blocks ORM imports in templates.

Interface text:
AIE
7
Engineering the future of AI

[3:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=198s) [An architecture decision record bans ORM queries in templates and describes enforcement with import-linter.](https://assets.ai.engineer/sites/aiecode2025/sha256/64b4fe03240f9f18d314842b18497b7eb66ea90e65b8cbe460d3cdcef008e6ec.webp)

ADR: what it looks like

---
id: "038"
status: Accepted
enforced_by: import-linter
file_patterns:
  - "*/templates/**"
  - "*/templatetags/**"
---

# No ORM queries in templates

Context: Templates called .filter() and .count() directly, making N+1 queries invisible until production.

Decision: Templates receive only pre-fetched typed data. ORM models are banned from the template layer.

Enforced: import-linter blocks ORM imports in templates.

Interface text:
AIE
7
AI Engineer
EUROPE

### PRD

A lightweight PRD records a feature’s purpose, problem, goal and user journey, giving the team a basis for deciding whether the feature still matters.

[3:23](https://www.youtube.com/watch?v=504PvfXou5Y&t=203s) [A product requirements document captures product goals and questions about a feature’s purpose, outcome, and continued value.](https://assets.ai.engineer/sites/aiecode2025/sha256/a8fc502061a34f6c71cf4a90df24cf8eafe42773b47729524946c44fd075d689.webp)

PRD

Product Requirements Document.

Capture. Product. Goals.

• WHY does this feature exist?
• WHAT problem does it solve?
• WHAT outcome do we expect?
• Does this still matter?
• Should we keep it?
• Can we delete it?

8

AIE
AI Engineer EUROPE

### PRD: what it looks like

A compact PRD connects the need to catch regressions with a user journey: connect a model, schedule evaluations, and receive an alert on regression.

[3:44](https://www.youtube.com/watch?v=504PvfXou5Y&t=224s) [A sample PRD describes scheduled evaluation runs, their purpose, problem, goal, and user journey.](https://assets.ai.engineer/sites/aiecode2025/sha256/c3b6508b3c637799b2aae89352c1fac895e0006c81aaee99a71955e9723494d0.webp)

PRD: what it looks like

---
id: prd-019
status: Active
owner: "@mikz"
---

# Scheduled eval runs

Why: Regressions should be caught automatically.

Problem: Evals only run when someone remembers to trigger them.

Goal: Let users schedule evals and get alerted on failure.

Journey: connect model → set schedule → receive alert on regression.

9

AIE
AI Engineer
EUROPE

### BDD

Cichra presents BDD’s readable, executable specifications as a human-language layer for checking whether a product behaves as its spec describes.

[4:05](https://www.youtube.com/watch?v=504PvfXou5Y&t=245s) [Behavior-driven development uses readable, executable specifications to connect intent with code.](https://assets.ai.engineer/sites/aiecode2025/sha256/558d35233faa8e15ba8c0eb12518de024c4301f7cc70643483da270a23a5cc4c.webp)

BDD

Behavior Driven Development.
Run. Your. Specs.

• Who wants to read AI code? Or AI tests?
• BDD is not new, but suddenly relevant again
• Readable and executable — intent meets code

10

Interface text:
AIE
AI Engineer EUROPE

### Bonus: Design System

A design system helps agents build consistent UIs: document rules, preview component states in Lookbook, and compose reusable components from smaller pieces.

[5:58](https://www.youtube.com/watch?v=504PvfXou5Y&t=358s) [A design system defines UI rules and previews component states, building components bottom-up.](https://assets.ai.engineer/sites/aiecode2025/sha256/1ede6b61d89cf6c96d09bdc30063519fb0c6e8c2709c697f0b15bff235e9a75c.webp)

Bonus: Design System

Design for UI components.
Rule. Your. UI.

• Rules: one primary button per page, no exceptions
• Components: all states previewed in Lookbook
• Built bottom-up, like code

12

Interface text:
AIE
AI Engineer EUROPE

[6:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=378s) [Design-system rules include one primary button per page, component-state previews, and bottom-up composition.](https://assets.ai.engineer/sites/aiecode2025/sha256/618cad323878354d0657d15b3f5ddf17637876ae57920dd08dff3ce6b03c704b.webp)

Bonus: Design System

Design for UI components.
Rule. Your. UI.

• Rules: one primary button per page, no exceptions
• Components: all states previewed in Lookbook
• Built bottom-up, like code

12

Interface text:
AIE
Engineering the future of AI

### Cool Ideas. Now What?

Cichra proposes a reinforcement loop to keep the team and agents consistent, reminding agents of their rules and how to follow them.

[7:17](https://www.youtube.com/watch?v=504PvfXou5Y&t=437s) [The slide asks how teams and agents stick to the ideas and proposes a reinforcement loop.](https://assets.ai.engineer/sites/aiecode2025/sha256/dc135e275dd94d2cb11b67febb3555177819762f761e6daf8a512854a4018c77.webp)

Cool Ideas. Now What?

How do the team and the agents actually stick to this?

You need a reinforcement loop.

13

Interface text:
AIE
Google DeepMind

### The Loop Needs a Harness

Git hooks and CI run the same commands to enforce rules across commits, pushes and pull requests. Checks cover linting, architecture, types and quality; tests run outside hooks.

[7:42](https://www.youtube.com/watch?v=504PvfXou5Y&t=462s) [Git hooks and CI enforce rules using linters, architecture checks, type checks, quality checks, and tests outside hooks.](https://assets.ai.engineer/sites/aiecode2025/sha256/c2617fb29b8e87360dbfba3109872f8961706433f5132b6cd963fb896d2f2656.webp)

The Loop Needs a Harness

Enforce how.

If you can't measure it, you can't enforce it.

Enforce rules on commit, on push, on PR.

Git hooks and CI run the same commands.

• Linters
• Architecture checks
• Type checks
• Quality checks
• Tests (not in hooks)

14

Interface text:
AIE
Engineering the future of AI

[8:03](https://www.youtube.com/watch?v=504PvfXou5Y&t=483s) [Slide describes enforcing rules through Git hooks and CI, including linting, architecture checks, type checks, quality checks, and tests outside hooks.](https://assets.ai.engineer/sites/aiecode2025/sha256/82c784d5f69b8a8ea659f2292704aabe8c7a16f73b924112785fb3e35a3222d2.webp)

The Loop Needs a Harness

Enforce how.

If you can't measure it, you can't enforce it.

Enforce rules on commit, on push, on PR.

Git hooks and CI run the same commands.

• Linters
• Architecture checks
• Type checks
• Quality checks
• Tests (not in hooks)

14

Interface text:
AIE
AI Engineer
EUROPE

### Example: Enforced Architecture

Import rules linked to ADRs keep application layers separate and prevent BDD tests from accessing database modules. Violations fail at commit time, giving the agent early feedback.

[8:46](https://www.youtube.com/watch?v=504PvfXou5Y&t=526s) [Slide describes enforced import boundaries, layered application code, and early feedback on violations.](https://assets.ai.engineer/sites/aiecode2025/sha256/4541db17eb3d0421508ef2837cd8b9395ad333889cd70d0099b378e57f287fb9.webp)

Example: Enforced Architecture

We enforce import boundaries.
Rules link to ADRs.

• BDD tests cannot talk directly to the database
• Application code stays split into layers
• Violations fail fast — at commit time

Agent gets early feedback and works through it to reach the goal.

15

Interface text:
AIE
AI Engineer EUROPE

### Skills Provide Focus

The agent uses the same work, feedback, and iteration loop across tasks. Skills change its focus: checking architecture rules, connecting work to product goals, iterating on UI, or running targeted tests.

[9:48](https://www.youtube.com/watch?v=504PvfXou5Y&t=588s) [Slide lists skills for architecture decisions, product goals, UI iteration, focused tests, and goal execution.](https://assets.ai.engineer/sites/aiecode2025/sha256/0f710e0f3c9e96f6bbe70b9197af7dd265f608cf8c2f436fe994e656c10e0acf.webp)

Skills Provide Focus

The loop is generic.
Skills provide focus.

• $adr — which rules govern these changes
• $prd — which goals does this serve
• $ui-loop — iterate fast, reconcile after
• $test - run focused test suite
• Goal execution — decisions and pending work

16

Interface text:
AIE
Engineering the future of AI

### Drawbacks

Research can consume half the context; Cichra says important information survives compaction and the agent can look it up again. The slide pairs a slow feedback loop with the goal of long-running tasks.

[11:03](https://www.youtube.com/watch?v=504PvfXou5Y&t=663s) [Drawbacks: context-heavy work and a slow feedback loop; the goal is long-running tasks.](https://assets.ai.engineer/sites/aiecode2025/sha256/e8371e17988c7f8af25341e05b908faa2771d295bc706f2d8dfb521863aa6545.webp)

Drawbacks

Context-heavy.
Slow feedback loop.

But that's the goal, no?
Long-running tasks.

17

AIE
AI Engineer EUROPE

### TL;DR

ADRs and PRDs preserve decisions and product goals; BDD makes specifications executable, design systems guide consistent UI, and a harness ties the loop together.

[11:47](https://www.youtube.com/watch?v=504PvfXou5Y&t=707s) [Summary slide: ADRs record decisions, PRDs capture goals, BDD runs specifications, design systems rule the UI, and a harness enforces the loop. Closing line: May the SPEC be with you.](https://assets.ai.engineer/sites/aiecode2025/sha256/7debd77ad25b004304f33f0df0f3cfb11433b409e76e2fc522cb63433dccd4b3.webp)

TL;DR

• ADRs — record decisions
• PRDs — capture goals
• BDD — run your specs
• Design system — rule your UI
• Harness — enforce the loop

May the SPEC be with you.

18

Interface text:
AIE
Braintrust
WorkOS
OpenAI

## Full transcript

[0:00](https://www.youtube.com/watch?v=504PvfXou5Y&t=0s) [upbeat music] Hi, I'm Michal.

[0:16](https://www.youtube.com/watch?v=504PvfXou5Y&t=16s) Uh, welcome to Capturing Decisions for Humans and AI Alike.

[0:22](https://www.youtube.com/watch?v=504PvfXou5Y&t=22s) Yesterday, with a team from Safe Intelligence, we have released Pact.27, a new product to test agents. Before that, I was in Microsoft, Red Hat, and spent ten years working on a single product.

[0:35](https://www.youtube.com/watch?v=504PvfXou5Y&t=35s) The consistency problems we face with AI and the story of capturing decisions show up in every product I have seen, and these notes are distilled from that experience. And you can find me at the booth.

[0:48](https://www.youtube.com/watch?v=504PvfXou5Y&t=48s) Um, so BDD, PRD, ADR, like this lot of acronyms, uh, why does any of it matter? So let's unpack it from the end.

[0:59](https://www.youtube.com/watch?v=504PvfXou5Y&t=59s) You probably know this story. Uh, I hope it's not an urban legend, uh, but scientists put five monkeys in a cage with bananas on a ladder,

[1:07](https://www.youtube.com/watch?v=504PvfXou5Y&t=67s) then gave them a cold shower every time a monkey tried to get a banana.

[1:11](https://www.youtube.com/watch?v=504PvfXou5Y&t=71s) Other monkeys beaten up the poor fella. Then they replaced the monkeys one by one, and none of the originals remained, and yet they have beaten up every monkey that tried to climb the ladder, not knowing why.

[1:26](https://www.youtube.com/watch?v=504PvfXou5Y&t=86s) So humans and LLMs, they suffer from the same trait: limited context. People forget. LLMs, context compacts. Humans leave. LLMs have no memory. After a while of operating a product, the team starts asking, "Why do we have this flow?

[1:44](https://www.youtube.com/watch?v=504PvfXou5Y&t=104s) What is the goal of this feature? Why is this code shaped like that? Why-- where does this belong?" And you might not have the founding engineer available to answer.

[1:56](https://www.youtube.com/watch?v=504PvfXou5Y&t=116s) And these problems show in every org, uh, maybe with AI much sooner than they used to.

[2:03](https://www.youtube.com/watch?v=504PvfXou5Y&t=123s) So ADR is Architecture Decision Record. It records why you do something and how you enforce it or how you wanna do that. And you can cover examples by reference docs and code snippets.

[2:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=138s) For example, we split code in layers to prevent N+1 queries. We enforce that split by linting imports in modules. And we also enforce reading from database, returns, um, plain shapes instead of ORM objects, so we cannot, um, cannot make these, uh, these queries and to prevent duplication.

[2:38](https://www.youtube.com/watch?v=504PvfXou5Y&t=158s) And also linting it by module imports and another like fifty ADRs that define the architecture of the product.

[2:47](https://www.youtube.com/watch?v=504PvfXou5Y&t=167s) There is not a single format that, that you need to use. It's just a concept. Um, it's a text, so there is no specific, uh, way how to enforce it.

[2:58](https://www.youtube.com/watch?v=504PvfXou5Y&t=178s) You still need a tool to enforce it. But the tool will tell you that this is the rule, why are you doing this, and how are you supposed to fix it.

[3:08](https://www.youtube.com/watch?v=504PvfXou5Y&t=188s) Then the agent will go and try to find this document, why this reason exists, and more information about how to fix it. Also, you can define, like, which files it actually concerns to, like, is it some Python files or some folders, and how you actually enforce it.

[3:26](https://www.youtube.com/watch?v=504PvfXou5Y&t=206s) PRD is a Product Requirements Document, uh, that's something lighter. When you're building a feature, you describe why that thing exists and what problems it solves and how user goes through the app to actually interact with it.

[3:41](https://www.youtube.com/watch?v=504PvfXou5Y&t=221s) What's the journey through the application. It can be very light. It doesn't need to be really long and exhaustive, like a massive document. Uh, you can just capture why the problem and the goal and the journey that connects them.

[3:57](https://www.youtube.com/watch?v=504PvfXou5Y&t=237s) And it's not just for the agents, but also for you six weeks from now when you forget why you did that.

[4:07](https://www.youtube.com/watch?v=504PvfXou5Y&t=247s) Now BDD, um, it's a Behavior-Driven Development. You have probably seen Spec-Driven Development lately, uh, but if you practiced it, uh, you might have suffered the same thing as me.

[4:21](https://www.youtube.com/watch?v=504PvfXou5Y&t=261s) How do you validate that the product actually adheres to the spec? It's a markdown document. You describe how it's supposed to work, but how do you know it actually works like that?

[4:31](https://www.youtube.com/watch?v=504PvfXou5Y&t=271s) One thing harder than reading an AI code is reading AI tests. Um, so what if you had an intermediate layer that actually describes how the product behaves in a human language?

[4:46](https://www.youtube.com/watch?v=504PvfXou5Y&t=286s) And BDD is not new and shiny, but it's, it can be executable and readable,

[4:52](https://www.youtube.com/watch?v=504PvfXou5Y&t=292s) so enter Cucumber. It's almost forgotten, suddenly useful again. It's definitely easier to review than your average test.

[5:02](https://www.youtube.com/watch?v=504PvfXou5Y&t=302s) You can connect scenarios directly to your PRDs and critical user journeys. It can be readable, executable, and it closes the loop that a Spec-Driven Development leaves open.

[5:15](https://www.youtube.com/watch?v=504PvfXou5Y&t=315s) These rules, uh, these specs are later parsed by steps, and they are executed as code. But what you can do is that you can actually write and read these, and you can review these, and you can understand these.

[5:30](https://www.youtube.com/watch?v=504PvfXou5Y&t=330s) The language is on you. It doesn't need to be, um, enforced. Like, you-- There are multiple ways how to write these, uh, these features. And

[5:43](https://www.youtube.com/watch?v=504PvfXou5Y&t=343s) that's it. But they describe how you're supposed to go through the application, why this thing exists, and how it runs. And similarly, they can refer back to all the documents that you have about why things exist.

[6:00](https://www.youtube.com/watch?v=504PvfXou5Y&t=360s) So, and as a bonus, making consistent UIs with agents is just another level of hard. Like design system and pattern library are the way to build consistent UIs. Like that was the way before AI, and it is the way now.

[6:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=378s) So you document your language. You say, for example, "A primary button is this and that. It is blue, it has this shape, it has this color, and it's this size."

[6:26](https://www.youtube.com/watch?v=504PvfXou5Y&t=386s) And you say your rules. You say, "We will have only one primary button visible on a site at any, on a, on, on a page at any point in time."

[6:35](https://www.youtube.com/watch?v=504PvfXou5Y&t=395s) And then you can enforce these rules. Similarly, you define components and patterns. So for example, if you have multiple colors of these buttons and multiple states, you define components and you define previews, and you demonstrate how they work, and you create snippets of previews so you can actually see them, and the agents can see them.

[6:57](https://www.youtube.com/watch?v=504PvfXou5Y&t=417s) And then you can go and review and like, "Do these actually adhere to the principles that I have? Do they adhere to the visuals?" And then you reuse them.

[7:04](https://www.youtube.com/watch?v=504PvfXou5Y&t=424s) As with code, you build these from the ground up, from small pieces into bigger ones. You compose them, and you reuse them. Otherwise, it's, uh, chaos, like with the code.

[7:18](https://www.youtube.com/watch?v=504PvfXou5Y&t=438s) So cool. These are cool ideas, but how to actually enforce this?

[7:25](https://www.youtube.com/watch?v=504PvfXou5Y&t=445s) So my team and agents stick with it. How do I keep it consistent? Well, with the loop.

[7:32](https://www.youtube.com/watch?v=504PvfXou5Y&t=452s) So you probably have heard about closing the loop, reinforcement loop, the harness, how to remind the agent of their rules and how to follow them.

[7:44](https://www.youtube.com/watch?v=504PvfXou5Y&t=464s) So our loop is simple. It is Git hooks, skills, CI, and linters, and bunch of other checks. Agent's goal is to deliver a pull request, and they, to do that, they need to use Git.

[7:59](https://www.youtube.com/watch?v=504PvfXou5Y&t=479s) So we use Git hooks, Git hooks to run predefined tasks, and these tasks are later executed on a CI. They are the same tasks that they are executed as, as hooks.

[8:09](https://www.youtube.com/watch?v=504PvfXou5Y&t=489s) If, for example, agents would get lazy and not wanna execute them or skip them, then they get caught.

[8:14](https://www.youtube.com/watch?v=504PvfXou5Y&t=494s) And we include linting, formatting, type checking, code duplication, architecture checks, document li- linting, everything that's, that's possible.

[8:23](https://www.youtube.com/watch?v=504PvfXou5Y&t=503s) So 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.

[8:33](https://www.youtube.com/watch?v=504PvfXou5Y&t=513s) They are rules, and they are enforced, and they are automated because there is no space for discussion about these anymore. It's more about the high level concepts.

[8:43](https://www.youtube.com/watch?v=504PvfXou5Y&t=523s) What you cannot find, you cannot enforce. So for example, we enforce architecture of the product and of the code. We separate modules, um, and their imports, so what you can use from where.

[9:00](https://www.youtube.com/watch?v=504PvfXou5Y&t=540s) For example, our end-to-end BDD test suite cannot access database, so we forbid from accessing any module that could access database and basically force the module to, the modules to operate without database and really use only the browser features of the application.

[9:16](https://www.youtube.com/watch?v=504PvfXou5Y&t=556s) Similarly, in the product itself, we enforce we cannot talk to database from rendering templates, so we know that there are no N+1 queries ever. We just define ways to prevent these problems from happening ever.

[9:30](https://www.youtube.com/watch?v=504PvfXou5Y&t=570s) You cannot keep finding them. You need to prevent them entirely.

[9:36](https://www.youtube.com/watch?v=504PvfXou5Y&t=576s) Then the com-- the agent tries to commit it and push it, and they get feedback on the commit and get rejected, and they get linked back to the document, and they go read it and fix it and iterate.

[9:50](https://www.youtube.com/watch?v=504PvfXou5Y&t=590s) So there are some drawbacks. Um, it is... Oh, sorry, it's not drawbacks. Um, so this loop is generic, uh, this loop where they do some work, they, they push it, and they get feedback, and they iterate.

[10:04](https://www.youtube.com/watch?v=504PvfXou5Y&t=604s) But the loop can be multiple things, right? Like sometimes you're working on a product feature, sometimes you're working on a UI, sometimes you're working on more backendish sh- like backendish things.

[10:14](https://www.youtube.com/watch?v=504PvfXou5Y&t=614s) So that loop is the same, but what changes is the focus of the loop. So we have different skills. Uh, there is ADR that whenever there is an ADR mentioned, the agent will look up ADRs, how to operate with them, uh, how to find code that affect, that's affected by these ADRs.

[10:32](https://www.youtube.com/watch?v=504PvfXou5Y&t=632s) For PRD the same. For w- for UI loop, we actually skip bunch of checks and rather force it to iterate in a browser quickly.

[10:42](https://www.youtube.com/watch?v=504PvfXou5Y&t=642s) And test skill that actually identifies tests to run based on code coverage and file changes, so we run just the focus part of the suite and not the entire suite.

[10:53](https://www.youtube.com/watch?v=504PvfXou5Y&t=653s) And some goal execution to actually keep decisions that the model made so we can review them later. But all of these provide focus in the loop, but the loop stays, stays the same.

[11:04](https://www.youtube.com/watch?v=504PvfXou5Y&t=664s) There are drawbacks. Uh, it is very context heavy. Like you can run out of half of the context, uh, in, um, starting the research. Um, but I have no fear of context compacts like this actually for like last half year actually works, I think.

[11:22](https://www.youtube.com/watch?v=504PvfXou5Y&t=682s) So in my sessions, there are twenty, fifty context compacts, and it's, it's okay because the important things survive, and the agent will always look them up again. So and that's the goal anyway, right?

[11:37](https://www.youtube.com/watch?v=504PvfXou5Y&t=697s) Like you want to have multiple hour sessions with a clear goal that agent can operate autonomously with the rules that you define. So that's the goal anyway, like.

[11:48](https://www.youtube.com/watch?v=504PvfXou5Y&t=708s) So there are decisions that you can record. There are parts of the product that you can describe why these exist. There is, um, Cucumber or BDD that can have executable specifications that you can actually rev-- read and review and understand.

[12:08](https://www.youtube.com/watch?v=504PvfXou5Y&t=728s) Design systems can help you to build consistent UI from components and, um, again, enforce it. That, for example, there are no inline styles anywhere else. And you employ harness to loop it all together.

[12:24](https://www.youtube.com/watch?v=504PvfXou5Y&t=744s) So may the spec be with you. That's it. [applause] [outro jingle]
