An AI coding agent sees your code, but it does not see why the code looks the way it does. Architecture Decision Records (ADRs) are short text files that store one decision each: the context, the choice, and the consequences. Because they are plain Markdown in the repository, an agent can read them before it changes anything. This stops the agent from „fixing“ a deliberate design, for example by adding a direct database call across a bounded context. Recent research on agentic architecture knowledge management (AgenticAKM) goes one step further and lets agents also write and update these records.
A minimal ADR, saved as docs/adr/0007-use-events-between-contexts.md:
# 7. Use events between Billing and ShippingStatus: acceptedContext: Billing and Shipping are separate bounded contexts.Direct calls made them deploy together.Decision: They talk only through domain events (OrderPaid).Consequences: No shared database tables. Eventual consistency.
Then add one rule to the agent instructions file (for example AGENTS.md): „Read docs/adr before changing module boundaries, and add a new ADR if you change a decision.“
Sources: AgenticAKM (arXiv), ADRs Are the Best Thing You Can Give Your AI Agent.
Kommentar verfassen