Architecture Decisions Best Practices

Ten practices for documenting and revisiting agent architecture decisions - plus operating checks so ADRs stay true as models, frameworks, and gateways move.

Use them as a design rubric when writing ADRs and as a quarterly audit before topology or vendor changes.

How to Use This List

Walk A when writing a new ADR; B when encoding it in the system; C when operating reviews.
Tick items only when true in git, config, and calendar - not as aspirations.
Pair with Why Agent Systems Need Their Own ADR Discipline for motivation.
Re-check after new write tools, multi-agent splits, gateway changes, or framework majors.

A - Write Decisions That Bind

1. One binding choice per ADR. Do not mix framework pick with model vendor and topology in a single novel.
2. Capture forces, options, decision, and consequences (including accepted pain). Rejected options are mandatory.
3. Add falsifiable revisit triggers and a calendar date. "We will know later" is not a trigger.
4. Name an owner team. Orphan ADRs never get superseded cleanly.
5. Prefer thin ADRs in git over slide decks. Link spikes and evals; do not replace the record with them.

B - Connect ADRs to Runtime Reality

6. Encode decisions as config pins and allowlists. Roles for models; explicit gateway vs direct base URLs.
7. Keep tools, schemas, prompts, and gold-set evals portable. Framework and vendor ADRs must be supersedable.
8. Document fallback and degrade paths next to access-path choices. Incidents should not invent policy.
9. Separate privilege and HITL decisions when tools can write, pay, or shell. Security is architecture.
10. Link topology choices to metrics (turns, handoff failures, $/success). Multi-agent needs evidence, not cosplay.

C - Review, Supersede, and Learn

11. Review model pins monthly and the full ADR index quarterly. Record still valid when nothing changes.
12. Supersede with bidirectional links; never delete history. Amendments update pins; supersession changes forces.
13. Require dual-run or canary + eval before topology/framework/provider flips. Big-bang rewrites need a written exception.
14. Amend ADRs within days after SEVs that invalidate assumptions. Outages are review triggers.
15. Teach the ADR habit in onboarding. New hires should find decisions without Slack archaeology.

Applying These Practices in Order

Write (1-5): stops tribal architecture; cheapest clarity win.
Bind to runtime (6-10): prevents doc/code drift and unsafe autonomy.
Operate (11-15): keeps decisions honest as the agent field moves.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core documentation and binding practices. Items 11-15 extend them into review and organizational habit.

What is the first practice if we can only adopt one?

Write thin ADRs with options, decision, consequences, and revisit triggers for framework, access path, and topology (practices 1-3).

Do prompt tweaks need ADRs?

No. Version and eval prompts. Write an ADR when autonomy, safety policy, or vendor path changes in a lasting way.

How detailed should consequences be?

Enough that a new engineer understands the pain you accepted without reading the original spike.

Where should ADR files live?

In version control next to the agent services or platform repo, indexed and linked from READMEs and config headers.

How do these practices relate to frameworks?

They are framework-agnostic. LangGraph, CrewAI, MS Agent Framework, and custom loops are options inside ADRs, not replacements for them.

What metrics belong in topology reviews?

Task success, p95 latency, cost per success, stop-reason mix, and handoff failure rate when multi-agent.

Should every team invent its own ADR template?

Prefer one org template with agent-specific fields (roles, pins, data policy). See the framework selection template in this section.

How do we stop ADR thrash?

Require eval deltas and cost impact above a threshold before superseding framework or topology decisions.

What evidence shows practice 6 was violated?

Production still hardcodes vendor model ids and base URLs while the ADR describes roles and a different path.

Are decision records required for local/Ollama models?

Yes when they serve real users or touch sensitive data - document hardware, quality limits, and privacy claims.

Where should teams link this list?

In the section sidebar as the close-out checklist, and from RFCs that introduce new agent runtimes, gateways, or multi-agent graphs.

Why Agent Systems Need Their Own ADR Discipline - motivation
Architecture Decisions Basics - first ADR exercises
An ADR Template for Agent Framework Selection - template
Trade-off Guide: Single Agent vs Multi-Agent Architecture - topology
Trade-off Guide: Managed Gateway vs Direct Provider Integration - access path
Documenting Model and Provider Decisions for Future Migrations - model records
Revisiting Old Agent Architecture Decisions as the Field Moves - review cadence
Framework Lock-In Risks and How to Avoid Them - portability

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.

Architecture Decisions Best Practices

Ten practices for documenting and revisiting agent architecture decisions - plus operating checks so ADRs stay true as models, frameworks, and gateways move.

Use them as a design rubric when writing ADRs and as a quarterly audit before topology or vendor changes.

How to Use This List

Walk A when writing a new ADR; B when encoding it in the system; C when operating reviews.
Tick items only when true in git, config, and calendar - not as aspirations.
Pair with Why Agent Systems Need Their Own ADR Discipline for motivation.
Re-check after new write tools, multi-agent splits, gateway changes, or framework majors.

A - Write Decisions That Bind

1. One binding choice per ADR. Do not mix framework pick with model vendor and topology in a single novel.
2. Capture forces, options, decision, and consequences (including accepted pain). Rejected options are mandatory.
3. Add falsifiable revisit triggers and a calendar date. "We will know later" is not a trigger.
4. Name an owner team. Orphan ADRs never get superseded cleanly.
5. Prefer thin ADRs in git over slide decks. Link spikes and evals; do not replace the record with them.

B - Connect ADRs to Runtime Reality

6. Encode decisions as config pins and allowlists. Roles for models; explicit gateway vs direct base URLs.
7. Keep tools, schemas, prompts, and gold-set evals portable. Framework and vendor ADRs must be supersedable.
8. Document fallback and degrade paths next to access-path choices. Incidents should not invent policy.
9. Separate privilege and HITL decisions when tools can write, pay, or shell. Security is architecture.
10. Link topology choices to metrics (turns, handoff failures, $/success). Multi-agent needs evidence, not cosplay.

C - Review, Supersede, and Learn

11. Review model pins monthly and the full ADR index quarterly. Record still valid when nothing changes.
12. Supersede with bidirectional links; never delete history. Amendments update pins; supersession changes forces.
13. Require dual-run or canary + eval before topology/framework/provider flips. Big-bang rewrites need a written exception.
14. Amend ADRs within days after SEVs that invalidate assumptions. Outages are review triggers.
15. Teach the ADR habit in onboarding. New hires should find decisions without Slack archaeology.

Applying These Practices in Order

Write (1-5): stops tribal architecture; cheapest clarity win.
Bind to runtime (6-10): prevents doc/code drift and unsafe autonomy.
Operate (11-15): keeps decisions honest as the agent field moves.

FAQs

Why "ten practices" if there are fifteen checkboxes?

Items 1-10 are the core documentation and binding practices. Items 11-15 extend them into review and organizational habit.

What is the first practice if we can only adopt one?

Write thin ADRs with options, decision, consequences, and revisit triggers for framework, access path, and topology (practices 1-3).

Do prompt tweaks need ADRs?

No. Version and eval prompts. Write an ADR when autonomy, safety policy, or vendor path changes in a lasting way.

How detailed should consequences be?

Enough that a new engineer understands the pain you accepted without reading the original spike.

Where should ADR files live?

In version control next to the agent services or platform repo, indexed and linked from READMEs and config headers.

How do these practices relate to frameworks?

They are framework-agnostic. LangGraph, CrewAI, MS Agent Framework, and custom loops are options inside ADRs, not replacements for them.

What metrics belong in topology reviews?

Task success, p95 latency, cost per success, stop-reason mix, and handoff failure rate when multi-agent.

Should every team invent its own ADR template?

Prefer one org template with agent-specific fields (roles, pins, data policy). See the framework selection template in this section.

How do we stop ADR thrash?

Require eval deltas and cost impact above a threshold before superseding framework or topology decisions.

What evidence shows practice 6 was violated?

Production still hardcodes vendor model ids and base URLs while the ADR describes roles and a different path.

Are decision records required for local/Ollama models?

Yes when they serve real users or touch sensitive data - document hardware, quality limits, and privacy claims.

Where should teams link this list?

In the section sidebar as the close-out checklist, and from RFCs that introduce new agent runtimes, gateways, or multi-agent graphs.

Why Agent Systems Need Their Own ADR Discipline - motivation
Architecture Decisions Basics - first ADR exercises
An ADR Template for Agent Framework Selection - template
Trade-off Guide: Single Agent vs Multi-Agent Architecture - topology
Trade-off Guide: Managed Gateway vs Direct Provider Integration - access path
Documenting Model and Provider Decisions for Future Migrations - model records
Revisiting Old Agent Architecture Decisions as the Field Moves - review cadence
Framework Lock-In Risks and How to Avoid Them - portability

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.

Architecture Decisions Best Practices

Search Documentation

Architecture Decisions Best Practices