An architecture decision record, or ADR, captures a choice, its context, and its consequences. For an agent, it is an effective way to explain why the codebase looks the way it does.
The shape of a good ADR
A short record states the problem, the options considered, the decision, and what follows from it. It should fit on a page.
Why agents benefit
Without context, an agent may "improve" something you chose deliberately, such as replacing a state-management approach or adding a library you decided against. An ADR gives it the reasoning and the boundary.
Writing them for agents
- State the decision as a rule: "Feature libraries must not import from other feature libraries."
- Explain the reason briefly.
- Include what to do instead.
- Reference the ADR from the instruction file.
Use them in task prompts
When assigning a task, point to the relevant ADRs. That keeps the agent's changes consistent with the existing design.
Keep the set curated
Retire or update records that no longer apply. A large pile of outdated decisions is worse than none.
Takeaway
ADRs are cheap to write and give an agent the design intent that code alone cannot convey.
Continue with the book
Explore the full treatment, worked examples, and exercises in Local AI Agents for Angular Teams.
Adapted from Local AI Agents for Angular Teams, published by Choral Software. Article text and original examples © 2026 Choral Software. All rights reserved.