Enforcing Architectural Decisions and Specs for AI Agents
AI Engineergo watch the original →
the gist
To keep AI agents consistent, move architectural rules and product requirements out of the prompt and into automated CI/CD enforcement, using BDD for executable specs and git hooks for structural linting.
Automating Architectural Enforcement
Instead of relying on LLM context to maintain architectural integrity, move rules into the codebase where they can be enforced by CI and git hooks. This approach treats architectural decisions as non-negotiable constraints rather than suggestions. For example, to prevent N+1 query issues, implement module import linting that strictly forbids rendering templates from accessing database modules. Similarly, restrict E2E test suites from importing any modules that interact with the database, forcing tests to operate solely through browser-level interactions. When an agent violates these rules, the commit is rejected, and the agent is forced to reference the relevant Architecture Decision Record (ADR) to understand the constraint and iterate on the solution.
Closing the Spec-to-Code Gap
Behavior-Driven Development (BDD) using Cucumber provides an executable bridge between Product Requirements Documents (PRDs) and the actual implementation. While markdown specs often drift from reality, BDD scenarios serve as human-readable, executable tests that verify the product behaves exactly as described. These scenarios should be mapped directly to critical user journeys. By maintaining these specs in a format that both humans and agents can parse, the team ensures that the product requirements remain the source of truth for both development and automated testing.
Managing Agent Context
High-quality agent performance requires a structured loop where the agent receives immediate feedback from the environment. Rather than attempting to fit every rule into a single prompt, define specific 'skills' for the agent that trigger based on the task type, such as UI-focused iterations or backend-specific architectural checks. While this approach is context-heavy, it is sustainable; the agent does not need to hold all rules in its active memory if it is trained to look up relevant documentation and linting errors as part of its standard operating procedure. This creates a loop where the agent works, receives feedback from the harness, and iterates until the code passes all automated gates.