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:

The problem or force that forced a choice.
Options considered.
The decision taken.
Expected consequences (positive and negative).
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:

Decision class	Examples	Why it ages badly without a record
Orchestration pattern	ReAct vs plan-and-execute vs multi-agent	Rewrites are expensive; thrash looks like product bugs
Framework vs custom runtime	LangGraph, CrewAI, MS Agent Framework, thin loop	Upgrade and lock-in risk
Model and provider	Frontier vs mid-tier; OpenAI vs Anthropic vs gateway	Cost, quality, data policy
Access path	Managed gateway vs direct SDK	Compliance, failover, fee model
Tool surface	MCP servers, shell, browser, write tools	Security blast radius
Memory and state	Checkpoint store, vector memory, session only	Portability and privacy
Human gates	Which actions need approval	Risk and latency trade-off
Eval and deploy	What blocks ship	Quiet regressions

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:

Question	If unanswered, you get…
Who owns the loop: framework or us?	Parallel mini-runtimes
Single agent or multi-agent?	Coordination tax or god-agent risk
How do models get called?	Ad hoc keys and no failover
What is portable vs pinned?	Full rewrites on vendor change
What would reverse this decision?	Eternal "we always did it this way"
How do we measure if it still works?	No eval gate, only demos

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:

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

Lightweight vs heavyweight ADR programs

Style	Works when	Breaks when
Folder of Markdown in repo	Most product teams	Nobody reviews; no status field
ADR + RFC for big bets	Platform-wide standards	Every tiny choice needs an RFC
Ticket-only "decisions"	Very small teams	Search and supersession die
Wiki essays	Narrative culture	Detached from deployable pins

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?

Change	Write an ADR?	Notes
Adopt/replace agent framework	Yes	High lock-in
Gateway vs direct for inference	Yes	Compliance + ops
Single vs multi-agent topology	Yes	Coordination cost
Default model tier for a product surface	Yes	Cost/quality
Swap model id within same tier after eval	Optional short note	Link to migration recipe
Prompt wording tweak with eval pass	No	Keep in prompt versioning
Add one read-only tool	Usually no	Unless privilege model changes
Grant write/shell/payment tools	Yes	Security ADR

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

What is the minimum viable ADR for an agent team?

Context, options (at least two), decision, consequences, status, date, owner, and a revisit trigger. One to two pages.

When should we write the first agent ADR?

When the first choice would be painful to reverse without notes: framework, gateway, multi-agent split, or production tool privileges.

How is an ADR different from a design doc?

Design docs explore; ADRs commit. Keep exploration in RFCs if needed, then distill the binding choice into an ADR.

Should every prompt change get an ADR?

No. Version prompts and eval them. Write an ADR when prompt policy changes autonomy, safety, or product contract in a lasting way.

Where should ADRs live?

In git, under something like docs/adr/ or architecture/decisions/, linked from the agent service README and from config that encodes pins.

Who is allowed to supersede an ADR?

Whoever owns the system today, with the same review bar as the original (tech lead + security when tools or data policy change).

Do open-source agent frameworks ship ADRs we can copy?

They ship opinions and defaults. Your ADR must capture your constraints: data residency, team skill, cost caps, and risk.

How do ADRs interact with feature flags?

Flags implement gradual rollout. ADRs still record the target architecture and exit criteria for the flag.

What if two ADRs conflict?

That is a process bug. Supersede one, or write a new ADR that resolves the conflict explicitly.

Are diagrams required?

No. A short topology sketch helps for multi-agent or gateway hybrid designs, but clarity beats art.

How often should we review agent ADRs?

On a calendar (for example quarterly) and on triggers (model generation change, SEV, 2x cost, new protocol requirement). See Revisiting Old Agent Architecture Decisions as the Field Moves.

Can ADRs be private for security reasons?

Keep sensitive credentials out. The decision and threat model can still be recorded with redacted details and links to private threat docs.

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.

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.

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:

The problem or force that forced a choice.
Options considered.
The decision taken.
Expected consequences (positive and negative).
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:

Decision class	Examples	Why it ages badly without a record
Orchestration pattern	ReAct vs plan-and-execute vs multi-agent	Rewrites are expensive; thrash looks like product bugs
Framework vs custom runtime	LangGraph, CrewAI, MS Agent Framework, thin loop	Upgrade and lock-in risk
Model and provider	Frontier vs mid-tier; OpenAI vs Anthropic vs gateway	Cost, quality, data policy
Access path	Managed gateway vs direct SDK	Compliance, failover, fee model
Tool surface	MCP servers, shell, browser, write tools	Security blast radius
Memory and state	Checkpoint store, vector memory, session only	Portability and privacy
Human gates	Which actions need approval	Risk and latency trade-off
Eval and deploy	What blocks ship	Quiet regressions

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:

Question	If unanswered, you get…
Who owns the loop: framework or us?	Parallel mini-runtimes
Single agent or multi-agent?	Coordination tax or god-agent risk
How do models get called?	Ad hoc keys and no failover
What is portable vs pinned?	Full rewrites on vendor change
What would reverse this decision?	Eternal "we always did it this way"
How do we measure if it still works?	No eval gate, only demos

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:

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

Lightweight vs heavyweight ADR programs

Style	Works when	Breaks when
Folder of Markdown in repo	Most product teams	Nobody reviews; no status field
ADR + RFC for big bets	Platform-wide standards	Every tiny choice needs an RFC
Ticket-only "decisions"	Very small teams	Search and supersession die
Wiki essays	Narrative culture	Detached from deployable pins

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?

Change	Write an ADR?	Notes
Adopt/replace agent framework	Yes	High lock-in
Gateway vs direct for inference	Yes	Compliance + ops
Single vs multi-agent topology	Yes	Coordination cost
Default model tier for a product surface	Yes	Cost/quality
Swap model id within same tier after eval	Optional short note	Link to migration recipe
Prompt wording tweak with eval pass	No	Keep in prompt versioning
Add one read-only tool	Usually no	Unless privilege model changes
Grant write/shell/payment tools	Yes	Security ADR

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

What is the minimum viable ADR for an agent team?

Context, options (at least two), decision, consequences, status, date, owner, and a revisit trigger. One to two pages.

When should we write the first agent ADR?

When the first choice would be painful to reverse without notes: framework, gateway, multi-agent split, or production tool privileges.

How is an ADR different from a design doc?

Design docs explore; ADRs commit. Keep exploration in RFCs if needed, then distill the binding choice into an ADR.

Should every prompt change get an ADR?

No. Version prompts and eval them. Write an ADR when prompt policy changes autonomy, safety, or product contract in a lasting way.

Where should ADRs live?

In git, under something like docs/adr/ or architecture/decisions/, linked from the agent service README and from config that encodes pins.

Who is allowed to supersede an ADR?

Whoever owns the system today, with the same review bar as the original (tech lead + security when tools or data policy change).

Do open-source agent frameworks ship ADRs we can copy?

They ship opinions and defaults. Your ADR must capture your constraints: data residency, team skill, cost caps, and risk.

How do ADRs interact with feature flags?

Flags implement gradual rollout. ADRs still record the target architecture and exit criteria for the flag.

What if two ADRs conflict?

That is a process bug. Supersede one, or write a new ADR that resolves the conflict explicitly.

Are diagrams required?

No. A short topology sketch helps for multi-agent or gateway hybrid designs, but clarity beats art.

How often should we review agent ADRs?

On a calendar (for example quarterly) and on triggers (model generation change, SEV, 2x cost, new protocol requirement). See Revisiting Old Agent Architecture Decisions as the Field Moves.

Can ADRs be private for security reasons?

Keep sensitive credentials out. The decision and threat model can still be recorded with redacted details and links to private threat docs.

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.

Why Agent Systems Need Their Own ADR Discipline

Search Documentation

Why Agent Systems Need Their Own ADR Discipline