Architecture decision records preserve why rules exist and connect those rules to the tools that enforce them.
2
Cucumber scenarios provide a readable, executable link between product requirements, user journeys, and tests.
3
Git hooks, skills, CI, and linters keep agents inside the project's rules even after their context is compacted.
Summary
Michal Cichra argues that teams need to record both product decisions and the reasons behind technical rules because humans forget and AI agents lose context. ADRs explain architectural choices and point to enforcement, such as import linting that prevents database access from rendering code. PRDs capture a feature's purpose, the problem it solves, and the user's journey through the application. Cichra uses Cucumber and behavior-driven development to close the gap between a markdown specification and the behavior that tests verify. Readable, executable scenarios can link directly to PRDs and critical user journeys. The enforcement loop uses git hooks, CI, linters, skills, and focused checks. Failed commits send the agent back to the relevant document, where it can find the reason and fix the code. Cichra is open about the cost: his sessions may use 20 to 50 context compacts, but the agent can recover because the rules are stored in the repository.
Recorded reasons prevent teams from repeating rules they no longer understand
Cichra compares teams and language models to the story of monkeys that keep stopping others from climbing a ladder after the original reason has disappeared. People forget, agents lose context, and the founding engineer may no longer be available to explain a flow or a code shape. An architecture decision record, or ADR, records why a decision exists, how the team wants to apply it, and how it is enforced. It can link to reference documents and code examples. The format is flexible, but the document gives tools and agents an explanation to consult when a rule blocks a change.
Architecture documents become useful when tools can enforce their decisions
An ADR can describe a layered code structure that prevents N+1 queries. Import linting then restricts which modules can depend on others, while database reads return plain shapes instead of ORM objects. Cichra says the repository has around 50 additional ADRs covering its architecture. The document alone does not enforce anything. A tool must identify the violated rule, explain why it exists, show how to fix it, and define which files or folders it concerns. When an agent encounters that feedback, it can find the document and use the stated reason to guide its change.
PRDs capture the purpose and user journey of a feature without becoming large specifications
A product requirements document explains why a feature exists, which problem it solves, and how a user moves through the application. Cichra says a PRD can stay light. It only needs to capture the reason, problem, goal, and journey that connects them. The document is useful to agents while they build the feature, but it also helps the human team later. Six weeks after implementation, someone can read the PRD and recover why the feature was built and how it was meant to work.
Cucumber scenarios close the gap between a written specification and verified behavior
Cichra's problem with spec-driven development is that a markdown file can describe intended behavior without proving that the product follows it. AI-generated tests are difficult to read, so he proposes an intermediate layer in human language. Cucumber scenarios are readable and executable. They can link directly to PRDs and critical user journeys, then be parsed into steps that run as code. Teams can review the scenarios, understand the intended path through the application, and refer back to the documents that explain why the behavior exists. This gives the specification a direct connection to what the test suite executes.
Design systems give agents concrete rules for building consistent interfaces
Cichra applies the same documentation approach to UI work. A design system can state that a primary button has a defined color, shape, and size, and that only one primary button should be visible on a page at a time. Components can include multiple states, previews, and snippets that show how they look. Humans and agents can inspect those previews and compare new work with the stated principles. The components are composed from smaller pieces and reused across the product. Without that structure, Cichra says, interface work becomes chaotic in the same way that unstructured code does.
The repository enforces rules through a repeated work and feedback loop
The enforcement loop combines git hooks, skills, CI, linters, and other checks. Agents need git to deliver a pull request, so hooks run predefined tasks before the same tasks run in CI. The checks cover formatting, type checking, duplication, architecture, and document linting. Cichra says style issues should be automated rather than debated in code review. When an agent tries to commit or push a change that violates a rule, the commit is rejected. The feedback links back to the relevant document, so the agent can read the reason, correct the code, and iterate.
Module boundaries can prevent entire classes of mistakes
Cichra describes rules that make certain bad patterns structurally unavailable. The end-to-end BDD suite cannot access the database, so its modules are forbidden from importing anything that could reach the database. Tests must exercise the browser-facing behavior instead. In the product itself, rendering templates cannot talk to the database. That boundary prevents N+1 queries from appearing there. The aim is to stop relying on repeated detection and repair. If the module imports are restricted, the unwanted behavior cannot be introduced through that path.
Different workflows change the checks while keeping the same loop
The basic cycle stays the same across product features, UI work, and backend changes: the agent works, pushes its result, receives feedback, and iterates. The focus changes through different skills. An ADR skill tells the agent how to find decisions and affected code. A PRD skill provides the corresponding product guidance. A UI loop skips some checks and sends the agent quickly into browser-based iteration. A test skill selects tests from code coverage and changed files instead of running the whole suite. Cichra also mentions recording model decisions so the team can review them later.
Context compaction is manageable when the important rules live outside the session
Cichra says the process is context-heavy and can consume half of an agent's context during initial research. He reports seeing 20 to 50 context compacts in his sessions, but says this has worked for roughly the last half year. The agent does not need to remember every detail permanently. Important information survives in the repository, and the agent can look it up again when a hook, skill, or failed check sends it back to the relevant rule. That supports multi-hour sessions with a clear goal and more autonomous operation.
