Why Agent Systems Need Their Own ADR Discipline

Classic software systems change, but agent systems change while you are looking at them.

Model releases, framework majors, gateway pricing, and tool protocols shift on a quarterly (sometimes weekly) cadence.

Without a deliberate Architecture Decision Record (ADR) habit, teams forget why they chose LangGraph over a thin loop, OpenRouter over direct keys, or a single agent over a multi-agent graph - and they re-litigate every design review from scratch.

Summary

• Agent architecture choices are high-churn, multi-dimensional trade-offs; ADRs make them explicit, dated, and revisitable instead of tribal.
• Insight: Undocumented model, framework, and orchestration decisions become silent lock-in, surprise cost, and unsafe autonomy when people or vendors change.
• Key Concepts: ADR, decision context, consequences, supersession, model/provider pins, orchestration topology, review cadence.
• When to Use: Any team shipping agents past a demo - especially multi-model, multi-tool, or multi-agent systems.
• Limitations/Trade-offs: ADR overhead is real; document decisions that bind future work, not every prompt tweak.
• Related Topics: framework selection, single vs multi-agent, gateway vs direct, model migration notes, periodic ADR review.

Foundations

An Architecture Decision Record is a short, immutable note that captures:

1. The problem or force that forced a choice.
2. Options considered.
3. The decision taken.
4. Expected consequences (positive and negative).
5. Status over time (proposed, accepted, deprecated, superseded).

In traditional backends, ADRs often cover databases, message buses, and service boundaries.

In agent systems, the same format applies to a different set of high-impact choices:

Why "just use git blame" fails

Git history shows what changed.

It rarely captures:

• Options rejected and why.
• Constraints that were true then (budget, legal, team skill).
• Success criteria that would trigger a revisit.
• Which consequences were accepted knowingly.

Six months later a new engineer sees "we hardcode model X" and either cargo-cults it or rips it out without the original risk analysis.

Why agent ADRs need extra fields

Standard ADRs assume infrastructure that lasts years.

Agent decisions need time-boxed assumptions:

• Model id and capability as of a date (ids and ranks change).
• Cost assumptions (per-token and platform fees - verify at build).
• Protocol assumptions (MCP, A2A, provider tool schemas).
• Review trigger ("revisit when monthly spend exceeds $Y" or "when framework ships durable resume").

Without those fields, an "accepted" ADR becomes a museum plaque for a world that no longer exists.

Mechanics & Interactions

What an agent ADR must make forced

A useful agent ADR answers questions that otherwise stay in Slack:

Decision velocity vs documentation cost

Agent teams move fast.

That is not an argument against ADRs.

It is an argument for thin ADRs:

• One to two pages, not design novels.
• One decision per record (do not mix "pick LangGraph" with "pick Redis").
• Write when the choice binds others for more than a sprint.
• Skip for reversible experiment flags and pure content edits to prompts unless the prompt becomes a production contract.

Where ADRs sit relative to code

Constraints (legal, budget, skill)
        |
        v
   ADR (decision + consequences)
        |
        +--> config pins (model ids, base URLs)
        +--> runtime code (loop, tools, budgets)
        +--> evals / CI gates
        +--> runbooks / SLOs

The ADR is the why.

Config holds the current pins.

Code holds the how.

Evals prove the still true.

Interaction with framework choice

Choosing a framework is not only a library decision.

It encodes:

• State and checkpoint shape.
• Multi-agent primitives.
• HITL interrupt models.
• Ecosystem tracing defaults.

Document the control model you need, not only the brand name.

See An ADR Template for Agent Framework Selection and Framework-Free vs Framework-Based: When to Roll Your Own.

Interaction with model and gateway choice

Model and provider choices interact with cost routing, data retention, and failover.

An ADR that says "use GPT-class models" without recording gateway vs direct, data policy, and fallback chain is incomplete for production agents.

See Trade-off Guide: Managed Gateway vs Direct Provider Integration and Documenting Model and Provider Decisions for Future Migrations.

Interaction with multi-agent topology

"Multi-agent" is a topology decision with coordination cost.

Document why specialists exist (tools, privilege, model tier, org boundaries) rather than character names in a prompt.

See Trade-off Guide: Single Agent vs Multi-Agent Architecture.

Advanced Considerations & Applications

Supersession is a feature, not failure

In agent land, superseding an ADR in six months can be healthy.

The field moved: cheaper mid-tier models, better graph libraries, new protocols.

What is unhealthy is silent drift - code and config diverge from the last written decision with no record of the new rationale.

Practice:

1. Mark old ADR superseded by ADR-0NN.
2. Link both ways.
3. Note what stayed portable (tools, schemas, evals).

Lightweight vs heavyweight ADR programs

Prefer version-controlled Markdown next to the agent monorepo or platform docs, with a simple index.

Security and compliance ADRs

Some agent decisions are risk decisions in disguise:

• Shell or browser tools in prod.
• Customer data in prompts or long-term memory.
• Third-party gateway as subprocessor.
• Autonomous refunds or code merge.

Those deserve ADRs even if engineering "already knows."

Auditors and new hires do not inherit Slack context.

Multi-team platform ADRs

When multiple product teams share a runtime:

• Platform owns ADRs for loop, budgets, approved gateways, and default frameworks.
• Product teams own ADRs for domain tools, autonomy level, and workflow topology.
• Cross-cutting changes require a platform ADR and migration notes.

Without that split, every team re-decides provider keys and retry policy.

Trade-off table: document or skip?

Common Misconceptions

• "ADRs are only for big companies." Small teams forget faster; the format stays short.
• "We move too fast for docs." Undocumented rewrites are slower than a one-page ADR.
• "The README is enough." READMEs describe current state; ADRs preserve rejected options and triggers.
• "Framework docs replace ADRs." Framework docs explain how the library works, not why your product chose it.
• "Model choice is not architecture." For agents, model and routing are architecture - they dominate cost and behavior.
• "Accepted means forever." Accepted means "current until superseded"; schedule reviews.

FAQs

Related

• Architecture Decisions Basics - write your first agent ADR
• An ADR Template for Agent Framework Selection - ready template
• Trade-off Guide: Single Agent vs Multi-Agent Architecture - topology trade-offs
• Trade-off Guide: Managed Gateway vs Direct Provider Integration - access path trade-offs
• Documenting Model and Provider Decisions for Future Migrations - model migration notes
• Revisiting Old Agent Architecture Decisions as the Field Moves - review cadence
• Architecture Decisions Best Practices - operating checklist
• Framework Lock-In Risks and How to Avoid Them - portability discipline

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.