Skill Hub — Architecture

Architecture Decision Record

Record why a significant architectural choice was made, what options were rejected, and what consequences follow.

What this skill is for

This skill produces a concise, durable record of a significant architecture decision. It captures the context that forced a choice, the options that were considered, the decision that was made, and the consequences — positive and negative — that follow from it. The output prevents future teams from revisiting the same question without context, and it protects against the gradual erosion of architectural intent as personnel change.

When to use this skill

You must choose between two or more technical approaches and the choice will be hard to reverse.
A design review identified a decision point that needs explicit documentation.
A new team member or vendor is questioning a design choice that was made two years ago.
An audit or compliance review requires evidence that architecture decisions were made with due diligence.
You are standardizing decision records across a program so that all projects produce comparable documentation.

Real work situations

Example 1: Synchronous vs asynchronous customer master distribution

A project must decide how to distribute customer master data from SAP MDG to three downstream systems. Option A is synchronous SOAP services with immediate consistency. Option B is asynchronous events via SAP Event Mesh with eventual consistency. The ADR records that Option B was chosen because two downstream systems have lower availability than MDG, and synchronous calls would create cascading failures. The consequence is that downstream systems may see stale data for up to 30 seconds, which is acceptable for this business domain.

Example 2: Custom development vs standard SAP functionality

A business unit requests a custom pricing calculation in SAP SD because the standard procedure does not support their regional discount matrix. The ADR records that custom development was rejected in favor of configuring the standard condition technique with a new condition type and scale base. The consequence is that the solution stays within clean core boundaries but requires more complex condition record maintenance.

Example 3: Cloud vs on-premise data warehouse

A company must replace its aging SAP Business Warehouse system. The ADR evaluates cloud data warehouse, SAP Datasphere, and on-premise HANA upgrade. It records that SAP Datasphere was chosen because it preserves existing BW query investments while adding cloud scalability. The consequence is a hybrid landscape with data federation complexity that the operations team must manage.

Example 4: Microservices vs modular monolith for extensions

A development team wants to build a set of extensions to SAP S/4HANA using microservices on SAP BTP. The ADR records that a modular monolith on BTP Cloud Foundry was chosen instead because the team size is four developers, the expected load is moderate, and the operational overhead of distributed tracing and service mesh exceeds the team's capacity. The consequence is that future scaling beyond the monolith will require a deliberate re-architecture.

Inputs required

The decision question, stated as a single sentence (for example: "How should customer master data be distributed to downstream systems?").
The context: what situation, constraint, or requirement forces this decision now.
At least two viable options with descriptions, not just one preferred option.
Evaluation criteria: what dimensions matter (cost, time, risk, maintainability, scalability, compliance).
Stakeholder input: who advocated for each option and why.
Reversibility assessment: how hard and expensive it would be to change this decision later.

Questions to ask

What specific situation forces this decision now, rather than later or never?
What is the cheapest option, what is the fastest option, and what is the safest option? Are they the same?
Who will maintain this decision in two years, and do they have the skills for the chosen option?
What happens if we need to reverse this decision in six months? What would it cost?
Which option keeps us closest to standard SAP or standard platform functionality?
What are we giving up by choosing this option? What capability do we lose?
Does this decision create a new dependency, a new vendor lock-in, or a new single point of failure?

Working method

State the decision question. Write one sentence that captures exactly what must be decided. Avoid framing the question to favor one option.
Describe the context. Explain the situation, constraints, and requirements that make this decision necessary. Include deadlines, budget limits, and regulatory factors.
Define evaluation criteria. List 3–5 criteria that will be used to compare options. Weight them if the team agrees on relative importance.
List options. Describe each option at a consistent level of detail. Include at least two viable options and a "do nothing" or status quo option where relevant.
Evaluate each option. Against each criterion, record pros, cons, and risks. Be honest about drawbacks of the option you prefer.
Make the decision. State which option is chosen and why. Cite the criteria that tipped the balance.
Record consequences. List positive consequences (what we gain) and negative consequences (what we accept or lose). Include technical debt, new dependencies, and skill requirements.
Assess reversibility. Rate the decision as easily reversible, moderately reversible, or irreversible. Describe what would be required to reverse it.
Assign ownership and review date. Name the person or role accountable for this decision. Set a date when the decision should be revisited.
Link related decisions. Reference other ADRs that this decision depends on or affects.

Decision rules

If only one option is viable, the decision is not architectural — it is a constraint. Record it as a constraint note, not an ADR.
If the preferred option is custom development when a standard alternative exists, require explicit justification with named trade-offs.
If a decision is irreversible or expensive to reverse, escalate to program or enterprise architecture for approval before recording.
If an option introduces a new vendor or platform, evaluate exit cost and data portability explicitly.
If two options score equally on all criteria, choose the one that is closer to existing team skills and operational tooling.
If a decision contradicts a previous ADR, record the superseding relationship and update the status of the old ADR.
If no one can be named as the decision owner, the decision is not ready to be recorded.

Deliverables

Architecture Decision Record (ADR) — The primary artifact: context, options, decision, consequences, reversibility, owner, review date.
Decision Log Entry — One-line summary for a master decision log: ID, date, question, decision, status.
Stakeholder Input Summary — Who advocated for which option and their key arguments (optional but valuable for contentious decisions).

Templates

Architecture Decision Record (Markdown)

---
artifact: Architecture Decision Record
id: ADR-001
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded
owner: Name | Role
review_date: YYYY-MM-DD
---

## Decision question


## Context


## Evaluation criteria


## Options considered

### Option 1: <Name>
- Description:
- Pros:
- Cons:
- Risks:

### Option 2: <Name>
- Description:
- Pros:
- Cons:
- Risks:

### Option 3: <Name> (if applicable)
- Description:
- Pros:
- Cons:
- Risks:

## Decision


## Consequences

### Positive
- 

### Negative
- 

## Reversibility


## Related decisions

Decision Log Entry

| ID | Date | Question | Decision | Status | Owner | Review Date |
|----|------|----------|----------|--------|-------|-------------|
| ADR-001 | YYYY-MM-DD | How to distribute customer master data | Async via Event Mesh | Accepted | Integration Architect | YYYY-MM-DD |
| ADR-002 | YYYY-MM-DD | Custom pricing vs standard condition technique | Standard with new condition type | Accepted | SD Functional Lead | YYYY-MM-DD |

Quality checklist

The decision question is a single sentence with no embedded preference.
At least two viable options are described at a consistent level of detail.
Every option has at least one con or risk recorded honestly.
The decision explicitly cites which criteria tipped the balance.
Consequences include both positive and negative outcomes.
Reversibility is rated and the reversal cost is described.
A named owner and a review date are assigned.
The ADR is linked to related decisions where applicable.
The ADR has been shared with the team that will implement and operate it.

Common mistakes

Mistake: Recording only the chosen option, not the rejected ones. Consequence: Future teams revisit the same question because they do not know why alternatives were discarded.
Mistake: Framing the decision question to favor one answer. Consequence: The ADR becomes rationalization, not documentation, and loses credibility.
Mistake: Omitting negative consequences. Consequence: The team is surprised by technical debt, operational burden, or capability loss that was known but not communicated.
Mistake: Writing ADRs for trivial decisions. Consequence: The decision log becomes noise, and important decisions are lost in volume.
Mistake: Never revisiting decisions. Consequence: An ADR accepted three years ago under different constraints continues to constrain the architecture even though the context has changed.

Agent instructions

When using this skill, an AI agent must:

Extract the decision question. If the user describes a situation without a clear question, help them formulate one neutral sentence.
Require at least two options. If the user presents only one option, ask what alternatives were considered or what the status quo would look like.
Be honest about drawbacks. For every option, including the preferred one, list at least one con or risk. Do not sanitize the record.
Use the template. Produce the ADR in the exact Markdown template format provided. Fill every section.
Do not invent stakeholder input. If the user does not provide who advocated for which option, leave the stakeholder summary empty or ask for it.
Assess reversibility realistically. Do not default to "moderately reversible." Consider data migration, contract terms, skill retraining, and integration rework.
Link to related skills. If the ADR concerns integration, reference Event-Driven Architecture or API Integration. If it concerns data, reference Data Contracts.

Related skills

Solution Architecture Review — The review process that often surfaces decisions needing ADRs.
System Context Mapping — Define the boundaries that decisions affect.
Event-Driven Architecture — Deep-dive for decisions about asynchronous patterns.
API Integration — Deep-dive for decisions about API design and ownership.

Related Atlas pages

SAP Event-Driven Architecture — Context for decisions about event-based integration in SAP landscapes.
SAP Clean Core Strategy — How clean core principles constrain custom vs standard decisions.
Data Contracts — How data agreements affect architectural choices.
API Contracts — How API design commitments constrain and enable decisions.

Verification status and limitations

This skill is a public working interpretation of architecture decision recording practice. It is not an official standard from any framework body. It focuses on the lightweight ADR format suitable for project and program use. It does not cover enterprise architecture board governance, formal architectural review boards, or compliance-mandated decision processes. Use it as a practical method for capturing context and rationale, not as a substitute for organizational governance where required.