Why Etheon Uses MADR for AI Architecture Decisions

Enterprise AI systems are not built from models alone. They are built from decisions.

A team chooses whether to use a frontier model or an open-weight model. It decides whether an AI assistant should use retrieval-augmented generation or a fine-tuned model. It decides whether an AI agent can call tools directly or must pause for human approval. It chooses what data can be indexed, what logs can be retained, what actions are reversible, what model changes require evaluation, and what risks are acceptable in production.

Those are not small implementation details. They are AI architecture decisions. They shape cost, security, accuracy, privacy, reliability, governance, user trust, and future maintenance.

That is why Etheon uses MADR, or Markdown Architectural Decision Records, as a decision discipline for enterprise AI work. MADR is a structured format for capturing architecture-significant decisions in Markdown. The official MADR documentation defines an architectural decision as a justified software design choice that addresses a functional or non-functional requirement of architectural significance, and describes MADR as a streamlined template for recording those decisions in a structured way [1].

For Etheon, MADR is not paperwork. It is a production control. It helps make AI decisions explicit before they become hidden assumptions inside code, prompts, pipelines, RAG indexes, agent tools, vendor contracts, or deployment runbooks.

This article explains why Etheon uses MADR for AI architecture decisions, how it applies to enterprise AI systems, and why architecture decision records are becoming essential for organizations moving from AI prototypes to production workflows.

Why AI Needs Decision Records More Than Traditional Software

Architecture decision records are not new. Michael Nygard’s 2011 article on documenting architecture decisions proposed keeping short text records for architecturally significant decisions that affect structure, non-functional characteristics, dependencies, interfaces, or construction techniques [2]. The ADR idea became popular because software teams needed a way to remember not only what was built, but why it was built that way.

AI makes that need stronger.

In traditional software, a decision such as “use PostgreSQL instead of MongoDB” or “use event-driven architecture instead of synchronous APIs” can have long-term consequences. In enterprise AI, the decision space is even wider because the system may include probabilistic model behavior, retrieved documents, embeddings, prompts, agent tools, data retention, human oversight, legal constraints, vendor model updates, and evaluation thresholds.

A production AI system may fail because of a decision no one remembers:

- Why was this model selected?

- Why was this data source indexed?

- Why was this prompt allowed to override retrieved context?

- Why can the agent call this API?

- Why is human approval required for this action but not that action?

- Why is the vector index refreshed daily rather than hourly?

- Why are outputs stored for 30 days?

- Why was the open-source model rejected?

- Why was the vendor platform accepted despite lock-in?

- Why was this use case classified as moderate risk rather than high risk?

When these decisions are undocumented, teams repeat debates, lose context, inherit risk, and struggle to explain system behavior to buyers, auditors, security reviewers, and future engineers.

MADR gives the decision a place to live.

Why Etheon Chose MADR Instead of Informal Notes

Etheon uses MADR because AI architecture decisions must be structured, reviewable, versioned, and easy to read.

The MADR template includes sections such as context and problem statement, decision drivers, considered options, decision outcome, consequences, confirmation, and more information [1]. That structure fits enterprise AI because most AI decisions involve trade-offs rather than obvious answers.

For example, choosing a model is rarely “GPT versus open source” in the abstract. It is a trade-off between quality, cost, latency, deployment control, privacy, vendor dependency, fine-tuning, evaluation, and operational support. Choosing RAG is not simply “add a vector database.” It involves source authority, permission-aware retrieval, chunking, metadata, embeddings, citation requirements, stale content, and deletion propagation. Choosing agent autonomy is not simply “let the agent act.” It requires tool scope, approval gates, audit logs, rollback, and risk classification.

Informal notes do not reliably capture those trade-offs. Slide decks become stale. Slack discussions disappear. Meeting notes lack decisions. Tickets describe implementation tasks but often lose the reasoning. Architecture diagrams show the result but not the alternatives.

MADR creates a durable decision record.

A strong MADR answers:

- What problem forced the decision?

- Which constraints mattered?

- Which options were considered?

- Why was one option selected?

- What are the consequences?

- How will the team confirm the decision remains valid?

- What evidence supports the decision?

- When should it be revisited?

That is exactly the structure AI teams need.

The Enterprise AI Context: Decisions Are Becoming More Expensive

AI adoption is widespread, but production maturity is uneven. McKinsey’s 2025 global AI survey found that 88% of organizations reported regular AI use in at least one business function, while most organizations still had not scaled AI to enterprise-wide impact [3]. Gartner has warned that more than 40% of agentic AI projects may be canceled by the end of 2027 because of escalating costs, unclear business value, or inadequate risk controls [4]. Stanford HAI’s 2026 AI Index reports that responsible AI measurement is not keeping pace with capability, and documented AI incidents rose to 362 in 2025, up from 233 in 2024 [5].

Those findings point to the same lesson: enterprise AI does not fail only because models are weak. It fails because decisions are poorly framed, poorly governed, poorly measured, or poorly remembered.

For Etheon, MADR is one way to reduce that failure mode. It forces teams to document the logic behind AI architecture before the decision becomes expensive.

A bad AI architecture decision can create:

- Vendor lock-in.

- Uncontrolled cost growth.

- Data leakage.

- Weak evaluation.

- Poor observability.

- Inadequate human oversight.

- Prompt injection exposure.

- Tool abuse risk.

- Poor RAG quality.

- Non-compliance.

- Slow model migration.

- Unclear ownership after launch.

A good decision record does not eliminate risk. It makes risk visible and manageable.

MADR as an AI Governance Tool

AI governance frameworks increasingly emphasize accountability, lifecycle management, risk assessment, and documentation. The NIST AI Risk Management Framework helps organizations manage AI risks to individuals, organizations, and society and organizes risk management around Govern, Map, Measure, and Manage functions [6]. ISO/IEC 42001 provides a management-system standard for organizations developing, providing, or using AI systems, helping them manage AI risks and opportunities while balancing innovation with governance [7].

MADR supports these governance expectations at the architecture level.

A governance policy may say, “High-risk AI systems require human oversight.” A MADR explains how that oversight is implemented in a specific system:

- Which actions require approval?

- Who approves them?

- What evidence is shown?

- What can reviewers override?

- What is logged?

- What happens when review is skipped?

- Why was this design selected over another design?

A governance policy may say, “AI systems must protect sensitive data.” A MADR explains the architecture decision:

- Was permission-aware retrieval selected?

- Was tenant isolation selected?

- Was source-native retrieval rejected due to latency?

- Was vector index encryption required?

- Was logging redacted?

- What consequences does the decision create?

This is why MADR works well for AI governance. It connects abstract policy to concrete system design.

Where Etheon Uses MADR in the AI Lifecycle

Etheon uses MADR across the AI lifecycle, not only during engineering.

Discovery

During AI product discovery, MADRs capture early decisions about use-case scope, build-versus-buy direction, model class, risk tier, and whether AI is appropriate at all.

Example MADR topics:

- Use secure RAG instead of fine-tuning for internal knowledge assistant.

- Start support workflow in human-reviewed mode instead of autonomous mode.

- Reject agentic automation for payment release because risk exceeds current controls.

- Use rules engine for deterministic approval logic instead of LLM decision-making.

Architecture

During architecture design, MADRs document system-level decisions.

Example MADR topics:

- Use hybrid search plus vector retrieval.

- Use a model gateway to avoid provider lock-in.

- Keep vector index per tenant.

- Use customer-managed keys for high-sensitivity deployments.

- Store prompts and outputs for 30 days with redaction.

- Use a small language model for classification and frontier model fallback for complex cases.

Security and Governance

During security review, MADRs document risk-driven controls.

Example MADR topics:

- Require approval for external email sending by AI agent.

- Disable broad MCP tool access and allow only scoped tools.

- Redact tool payloads before observability logging.

- Treat retrieved documents as untrusted context.

- Prohibit AI access to payroll and M&A repositories in general assistant.

OWASP’s 2025 Top 10 for LLM and generative AI applications identifies risks such as prompt injection, sensitive information disclosure, supply chain vulnerabilities, excessive agency, vector and embedding weaknesses, misinformation, and unbounded consumption [10]. MADRs help translate those risk categories into system-specific design decisions.

Evaluation

AI evaluation needs decision records because evaluation thresholds often involve trade-offs. OpenAI’s evaluation guidance notes that generative AI can produce different outputs from the same input, making traditional software testing insufficient by itself [8]. Microsoft Foundry’s observability documentation describes evaluators for quality, RAG-specific metrics such as groundedness and relevance, safety and security, and agent-specific metrics such as tool call accuracy and task completion [9].

Example MADR topics:

- Use groundedness and citation accuracy as release gates for RAG assistant.

- Require tool-call accuracy threshold before enabling agent write access.

- Use human expert review for high-risk finance outputs.

- Add prompt injection tests to regression suite.

- Reject public benchmark-only model selection.

Production and Maintenance

After launch, MADRs capture operational decisions:

- Migrate from one model version to another.

- Change retrieval refresh cadence.

- Expand user access from pilot to department-wide use.

- Add a new tool to an agent’s allowlist.

- Change log retention.

- Introduce model routing for cost optimization.

- Retire an AI workflow because value did not meet threshold.

In Etheon’s view, architecture decisions continue after launch because AI systems evolve.

Why MADR Fits Enterprise AI Better Than Unstructured ADRs

Traditional ADRs are useful. MADR is especially useful for Etheon because it is lightweight but structured.

The MADR documentation states that decisions should be as easy as possible to write down and version, and it offers a Markdown-based template that can live close to the project documentation or repository [1]. This matters for AI systems because decisions are made across product, engineering, data, security, legal, compliance, and business teams. The format must be readable by all of them.

Etheon uses MADR because it creates a common decision language:

- Product leaders understand context and outcome.

- Engineers understand options and consequences.

- Security teams understand risk drivers.

- Data teams understand source and access decisions.

- Legal and compliance teams understand governance assumptions.

- Buyers understand why a path was chosen.

- Future maintainers understand what they inherited.

A MADR is not a long enterprise architecture document. It is a focused decision artifact. That makes it practical for fast-moving AI projects.

The MADR Structure Etheon Applies to AI Decisions

Etheon adapts MADR to AI system design with the following sections.

Status

The status shows whether the decision is proposed, accepted, rejected, deprecated, or superseded.

This matters for AI because architecture evolves quickly. A model decision from January may be superseded by a better, cheaper, safer model in June. A tool access decision may be deprecated after a security incident. A RAG index design may be replaced when permission requirements change.

Context and Problem Statement

This section explains the business and technical problem.

For AI, context should include the workflow, users, data, risk, constraints, and why a decision is required.

Example:

“The support triage assistant needs to retrieve customer billing policy and account history, but users have different regional permissions. The team must choose a retrieval architecture that prevents cross-region data exposure while keeping latency under two seconds.”

Decision Drivers

Decision drivers are the forces that matter.

For AI, common drivers include:

- Accuracy.

- Latency.

- Cost.

- Data sensitivity.

- Regulatory exposure.

- Human oversight.

- Model quality.

- Vendor lock-in.

- Auditability.

- Deployment control.

- Tool safety.

- Evaluation complexity.

- Maintenance burden.

This section prevents teams from selecting an option based on one dimension only.

Considered Options

This section documents alternatives.

For example:

- Use source-native retrieval.

- Use indexed retrieval with ACL metadata.

- Use separate vector indexes per region.

- Exclude restricted sources from MVP.

The point is not only to record the chosen option. It is to show what was rejected and why.

Decision Outcome

This section states the chosen option and rationale.

A good outcome is specific:

“Chosen option: separate vector indexes per region for MVP, because it reduces cross-region leakage risk and simplifies permission testing. We accept higher operational overhead during pilot and will revisit indexed retrieval with ACL metadata after access-control tests pass.”

This is what AI architecture needs: explicit trade-offs.

Consequences

Consequences show what becomes easier or harder.

For AI, consequences may include:

- Better privacy but higher infrastructure cost.

- Faster launch but less customization.

- Stronger quality but higher latency.

- More control but greater maintenance burden.

- Lower cost but more model evaluation work.

- Safer autonomy but slower workflow throughput.

This section is essential because AI decisions often require accepting a known downside.

Confirmation

MADR includes confirmation as an optional section describing how compliance with the decision will be validated [1]. Etheon treats confirmation as especially important for AI.

Examples:

- Confirm through retrieval permission tests.

- Confirm through red-team prompt injection tests.

- Confirm through model evaluation score.

- Confirm through human review acceptance threshold.

- Confirm through audit log review.

- Confirm through cost monitoring after pilot.

- Confirm through data deletion propagation test.

This turns decision records into verifiable controls.

The Types of AI Architecture Decisions Etheon Records

Model Selection Decisions

AI teams need to document why a model was chosen.

Questions include:

- Frontier model or small language model?

- Proprietary API or open-weight model?

- Private deployment or managed service?

- Single model or model router?

- Which model handles fallback?

- What evaluation threshold supports the choice?

- What data terms are acceptable?

- What happens if the model is deprecated?

A model decision without a MADR becomes hard to revisit. A model decision with a MADR becomes manageable.

RAG Architecture Decisions

RAG decisions include:

- Source-native retrieval or indexed retrieval.

- Vector search, keyword search, or hybrid search.

- Chunk size and overlap.

- Embedding model.

- Metadata strategy.

- Source authority ranking.

- Citation requirements.

- Permission model.

- Refresh cadence.

- Deletion propagation.

- Index isolation.

These decisions directly affect answer quality and data exposure.

AI Agent Decisions

AI agent decisions include:

- What goal can the agent pursue?

- Which tools can it call?

- What identity does it use?

- What actions require approval?

- Can it write to systems?

- Can it send external communications?

- How are tool calls validated?

- How are loops stopped?

- How is cost controlled?

- How can it be paused?

Given Gartner’s warning about agentic AI project cancellations due to cost, unclear value, and inadequate risk controls, agentic architecture decisions must be documented carefully [4].

Evaluation Decisions

Evaluation decisions include:

- Which datasets are used?

- Which metrics are release gates?

- Which evaluator is automated?

- Which evaluator requires human review?

- What is the minimum groundedness score?

- What is acceptable tool-call accuracy?

- What refusal behavior is required?

- What security tests block production?

OpenAI and Microsoft both emphasize structured evaluation and observability for production AI systems [8][9]. MADR documents why the evaluation strategy is appropriate for a use case.

Data and Privacy Decisions

Data decisions include:

- Which sources are approved?

- Which sources are excluded?

- Can prompts be logged?

- Can outputs be retained?

- What region is required?

- Are embeddings considered sensitive?

- What redaction is required?

- Who can access traces?

- How long are logs stored?

- Can vendor systems process this data?

These decisions are central to enterprise AI privacy and compliance.

Human Oversight Decisions

Human oversight decisions include:

- Which outputs require review?

- Which actions require approval?

- Who reviews?

- What evidence is shown?

- Can reviewers override?

- Are overrides logged?

- What training is required?

- What happens when review volume is too high?

The EU AI Act’s risk-based approach and requirements around human oversight for high-risk systems make human review design increasingly important for enterprise AI governance [11].

How MADR Helps Buyers Make Better AI Decisions

Etheon’s use of MADR also supports buyers. Decision-stage buyers need to understand not only what the AI system will do, but how architecture trade-offs were made.

MADR helps buyers see:

- Why the proposed architecture fits the workflow.

- Which risks were considered.

- Which alternatives were rejected.

- Why a model was selected.

- What trade-offs were accepted.

- How the decision will be tested.

- What can change later.

- What requires buyer approval.

- What operational responsibilities remain after launch.

This creates transparency. It reduces the “black box vendor” problem. It also helps enterprise teams make internal decisions faster because stakeholders can review the reasoning in one structured record.

For example, a buyer evaluating a secure internal AI assistant may ask why Etheon recommends permission-aware RAG over fine-tuning. A MADR can show that fine-tuning was rejected because it would not reliably enforce document-level permissions, would make source freshness harder to manage, and would not provide citations. Secure RAG may be chosen because it retrieves from approved sources, enforces permissions before context reaches the model, supports citations, and allows source updates without retraining.

That is a decision record that helps a buyer make a decision.

MADR and AI Compliance Readiness

AI regulation is increasing. The EU AI Act is described by the European Commission as the first comprehensive legal framework on AI worldwide, and its risk-based obligations are being implemented in phases [11]. Even when a specific system is not high-risk, enterprises increasingly need evidence of responsible design.

MADR supports compliance readiness by documenting:

- Intended purpose.

- Risk drivers.

- Design alternatives.

- Chosen controls.

- Human oversight.

- Data decisions.

- Evaluation gates.

- Operational consequences.

- Confirmation tests.

It does not replace legal analysis, security review, DPIAs, conformity assessments, model cards, or technical documentation. But it gives those processes an architecture-level evidence trail.

For ISO/IEC 42001-aligned organizations, MADRs can support lifecycle governance, impact assessment, risk treatment, design control, supplier review, and continual improvement [7]. For NIST AI RMF-aligned teams, MADRs can support Govern, Map, Measure, and Manage activities by linking decisions to context, risk, measurement, and mitigation [6].

MADR is not compliance by itself. It is a practical instrument for making compliance explainable.

The Etheon MADR Pattern for AI Projects

Etheon applies a practical MADR pattern for AI projects:

1. Create a MADR when a decision changes architecture, risk, data, autonomy, cost, or maintainability.

2. Write the MADR before the decision becomes code when possible.

3. Review the MADR with the right stakeholders.

4. Link MADRs to implementation tickets, evaluation reports, and security reviews.

5. Update status when a decision is superseded, deprecated, or confirmed.

6. Use confirmation criteria to validate that the decision works in production.

7. Revisit MADRs after incidents, model changes, vendor changes, or risk changes.

This keeps decision-making close to the system.

Example MADR Topics for Enterprise AI

Below are examples of MADRs Etheon may create during an enterprise AI engagement.

1. MADR topic: Use secure RAG instead of fine-tuning for policy assistant

Why it matters: Affects freshness, citations, privacy, and access control.

2. MADR topic: Use hybrid search for customer support knowledge base

Why it matters: Affects retrieval quality for exact and semantic queries.

3. MADR topic: Require human approval before AI sends external email

Why it matters: Affects brand, legal, privacy, and customer trust.

4. MADR topic: Use model gateway for frontier model access

Why it matters: Affects vendor lock-in, routing, cost, and fallback.

5. MADR topic: Exclude HR compensation data from general internal assistant

Why it matters: Affects privacy and employee trust.

6. MADR topic: Use small model for ticket classification

Why it matters: Affects latency, cost, and evaluation design.

7. MADR topic: Store AI traces with redacted retrieved context

Why it matters: Affects observability and privacy.

8. MADR topic: Start agent in recommend-only mode

Why it matters: Affects autonomy, safety, and rollout speed.

9. MADR topic: Use per-tenant vector indexes

Why it matters: Affects security, cost, and operational complexity.

10. MADR topic: Require tool-call accuracy threshold before write access

Why it matters: Affects agent production readiness.

Each decision may seem narrow. Together, they form the architecture.

What Happens When Etheon Does Not Use MADR

Not every decision needs a MADR. Etheon does not use decision records for every small implementation detail.

A MADR is not needed for:

- Minor UI copy.

- Low-impact refactoring.

- Small bug fixes.

- Temporary implementation choices.

- Decisions already captured by an accepted standard.

- Purely tactical tasks that do not affect architecture, risk, cost, or governance.

The test is simple:

Will someone ask “why did we do it this way?” later?

If yes, write a MADR.

Common Mistakes MADR Prevents in AI Projects

Mistake 1: Choosing a model without recording why

Teams often remember that a model was selected, but not why. MADR records the evaluation basis and trade-offs.

Mistake 2: Treating RAG as a generic component

RAG has security and quality decisions hidden inside it. MADR forces those decisions into the open.

Mistake 3: Expanding agent autonomy without a risk decision

Agent autonomy should increase only after a documented decision and evaluation evidence. MADR supports that gate.

Mistake 4: Losing security rationale after launch

When auditors, buyers, or security teams ask why logs are retained or redacted, the MADR provides context.

Mistake 5: Repeating architecture debates

If a decision was already made and documented, teams can revisit it with evidence instead of restarting the conversation.

Mistake 6: Forgetting consequences

AI decisions often have downsides. MADR forces teams to write them down.

Why MADR Fits Etheon’s Research Culture

Etheon’s public positioning emphasizes real-time, adaptive, self-healing AI systems and trust-oriented safety, privacy, and governance commitments [12][13]. Those kinds of systems require disciplined decisions because adaptive AI introduces lifecycle questions that static applications do not.

If a system can learn, adapt, route, retrieve, or act, the architecture must answer:

- What can adapt?

- Under what constraints?

- Who approves adaptation?

- What is measured before and after change?

- What triggers rollback?

- What evidence is logged?

- What risks are acceptable?

- What is prohibited?

MADR gives Etheon a way to record those answers.

It also supports Etheon’s research style: hypotheses, alternatives, evidence, decision, consequences, and confirmation. In AI R&D, not every decision can be proven in advance. But every important decision should state the evidence available, the uncertainty remaining, and the condition under which the decision should be revisited.

MADR as a Bridge Between Research and Production

AI research explores uncertainty. Production systems require commitments. MADR connects the two.

A research phase might discover that an open-weight model performs well on classification but poorly on long-context reasoning. A MADR can document the decision to use the open-weight model for high-volume classification and route complex cases to a frontier model. A prototype might show that autonomous tool use is too risky. A MADR can document the decision to keep the agent in human-reviewed mode. A security review might show prompt injection risk in retrieved documents. A MADR can document the decision to treat retrieved content as untrusted evidence and block tool execution based on retrieved instructions.

This makes research actionable. It turns findings into architecture.

How Buyers Can Read Etheon MADRs

A buyer reviewing an Etheon MADR should look for five things:

1. Is the problem clearly stated?
The MADR should explain the business and technical context.

2. Are decision drivers explicit?
It should show the forces that mattered: security, cost, latency, privacy, quality, usability, compliance, or maintainability.

3. Were real alternatives considered?
A decision record should not pretend there was only one option unless there truly was.

4. Are consequences honest?
Good decisions have trade-offs. The MADR should name them.

5. Is confirmation measurable?
The MADR should explain how the decision will be validated.

A useful MADR should make the buyer more confident, not because it hides complexity, but because it exposes and manages complexity.

The Etheon Recommendation

Etheon uses MADR because enterprise AI systems are made of decisions that must be remembered, reviewed, tested, and governed.

For Etheon, the rule is direct:

Every architecture-significant AI decision should leave a record.

That record should explain the context, drivers, options, decision, consequences, and confirmation plan. It should be easy to read, easy to version, and close enough to the system that engineers, product teams, security reviewers, and buyers can use it.

MADR helps Etheon make better decisions about:

- AI model selection.

- RAG architecture.

- AI agent autonomy.

- Tool access.

- Human oversight.

- Data privacy.

- Logging and retention.

- Evaluation thresholds.

- Vendor trade-offs.

- Production support.

- Governance.

AI architecture decisions are too consequential to live only in meetings. They need a format. They need a trail. They need a way to be challenged, accepted, revisited, and improved.

That is why Etheon uses MADR for AI architecture decisions.

References

[1] MADR, “Markdown Architectural Decision Records.” https://adr.github.io/madr/

[2] Michael Nygard, “Documenting Architecture Decisions.” https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

[3] McKinsey, “The State of AI: Global Survey 2025.” https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai

[4] Gartner, “Gartner Predicts Over 40% of Agentic AI Projects Will Be Canceled by End of 2027.” https://www.gartner.com/en/newsroom/press-releases/2025-06-25-gartner-predicts-over-40-percent-of-agentic-ai-projects-will-be-canceled-by-end-of-2027

[5] Stanford HAI, “The 2026 AI Index Report.” https://hai.stanford.edu/ai-index/2026-ai-index-report

[6] NIST, “AI Risk Management Framework.” https://www.nist.gov/itl/ai-risk-management-framework

[7] ISO, “ISO/IEC 42001:2023 — AI Management Systems.” https://www.iso.org/standard/42001

[8] OpenAI, “Evaluation Best Practices.” https://developers.openai.com/api/docs/guides/evaluation-best-practices

[9] Microsoft Foundry, “Observability in Generative AI.” https://learn.microsoft.com/en-us/azure/foundry/concepts/observability

[10] OWASP, “Top 10 for Large Language Model Applications.” https://owasp.org/www-project-top-10-for-large-language-model-applications/

[11] European Commission, “AI Act — Regulatory Framework.” https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai

[12] Etheon, “Real-Time Intelligence, Reimagined.” https://www.etheon.ai/

[13] Etheon, “Security & Privacy.” https://www.etheon.ai/safety/security-and-privacy/