Architecture Decision Records
Capture architectural decisions so agents understand why the codebase is shaped this way.
Key takeaways
- ADRs preserve the tradeoffs, rejected alternatives, and constraints that the final code cannot show, so agents understand why the system is shaped this way.
- Without an ADR, an agent may "improve" code by undoing a deliberate constraint, such as splitting a monolith or upgrading a pinned dependency into a known bug.
- Use the four core sections (Context, Decision, Alternatives Considered, Consequences) and explain why each rejected alternative lost.
- Add an explicit "Agent Guidance" section that tells agents what not to change and which runbooks to update.
- Status values (proposed, accepted, deprecated, superseded) signal whether a decision is still current.
Agents can read code, but code rarely explains why a decision was made. Architecture Decision Records (ADRs) preserve the tradeoffs, rejected alternatives, and constraints that are invisible in the final implementation.
Why ADRs Matter for Agents
Without ADRs, an agent may "improve" the code by undoing a deliberate constraint.
| Missing ADR | Agent risk |
|---|---|
| Why a monolith remains | agent splits services prematurely |
| Why a cache is write-through | agent changes consistency behavior |
| Why a dependency is pinned | agent upgrades into a known bug |
| Why a queue is used | agent replaces async flow with sync calls |
ADR Template
---
title: Use PostgreSQL advisory locks for billing jobs
status: accepted
date: 2026-05-24
owner: platform-team
related:
- /docs/runbooks/billing-jobs
---
# Use PostgreSQL advisory locks for billing jobs
## Context
[Problem, constraints, and current system.]
## Decision
[The decision in one or two paragraphs.]
## Alternatives Considered
| Alternative | Why rejected |
|---|---|
| Redis lock | Additional runtime dependency |
| Queue-level lock | Does not protect manual retry path |
## Consequences
- Positive:
- Negative:
- Operational notes:
## Agent Guidance
- Do not replace this lock with an in-memory lock.
- If billing jobs are refactored, update this ADR and the runbook.ADR Status Values
| Status | Meaning |
|---|---|
| proposed | under review |
| accepted | current decision |
| deprecated | no longer recommended |
| superseded | replaced by a newer ADR |
Agent Guidance Section
Add a short section that tells agents what not to change.
## Agent Guidance
- This decision is still active.
- Do not remove the retry queue without replacing the idempotency guarantee.
- Any change must update `docs/runbooks/payment-retry.md`.Checklist
| Item | Check |
|---|---|
| ADR states context, decision, alternatives, and consequences | [ ] |
| rejected alternatives explain why | [ ] |
| status is current | [ ] |
| agent guidance is explicit | [ ] |
| related runbooks/API docs are linked | [ ] |