Rich (with options)12 sections · ~1,500–3,000 words

Tyree-Akerman

Jeff Tyree & Art Akerman, IEEE Software 2005

The heaviest mainstream template: 12 sections, including assumptions, constraints, positions, argument, and related-decisions graph. For decisions you'll defend in front of an architecture board.

Use it when

The decision is permanent (one-way door) and the blast radius spans teams.
You're working in a regulated environment where decision provenance is part of the audit.
An architecture review board or RFC process expects the rigor.

Avoid when

Anything that fits in your head. The friction will kill the practice.
Teams that don't have a designated review forum — Tyree-Akerman without a reviewer is performance art.

Strengths

Captures Assumptions and Constraints separately — the difference matters six months later when you re-read.
Has an explicit Positions section, which is where alternatives live before they're evaluated.
Related Decisions field encodes the decision graph — supersedes, related-to, depends-on.

Weaknesses

Easy to write 5 pages and have nobody read past page 1.
The distinction between Issue, Decision, and Argument is real but takes practice.
Not friendly to PR-inline review.

Sections

8 required · 4 optional

Explicit options and pros/cons per option. The format you want when there's a real comparison.

01
Issue
Required
The architectural design issue you're addressing — phrased as a question.
```
How do we encrypt customer data at rest such that we satisfy SOC 2 CC6.1?
```

Decision

Required

Your chosen response to the issue, in one paragraph.

Adopt envelope encryption: AWS KMS-managed CMK + per-tenant DEK + libsodium for application-layer encrypt/decrypt.

03
Status
Required
Pending | Decided | Approved. With author and reviewer.
```
Approved — Author: A. Lee. Reviewer: ARB. Date: 2026-04-15.
```
04
Group
Optional
Logical grouping (security | persistence | observability …). Used to navigate a large decision register.
```
Security
```

Assumptions

Required

What you're taking as given. The list reviewers will challenge first.

- AWS remains our primary cloud for the next 24 months.
- Performance budget allows ~2ms per encrypt/decrypt at the application layer.

Constraints

Required

Hard requirements. Failing a constraint disqualifies an option.

- Customer data must be encrypted at rest with rotatable keys.
- Per-tenant key separation for blast-radius isolation.
- No new vendor on the SOC 2 scope this quarter.

07
Positions
Required
The candidate options, each with a short framing. Different from MADR's flat list — Tyree-Akerman expects each position to be defensible.
```
1. KMS envelope (chosen).
2. Application-managed keys with HashiCorp Vault.
3. Disk-level encryption only (LUKS / EBS-encrypt).
```

Argument

Required

The reasoning that selects from the positions. Cites the constraints and assumptions explicitly.

Position 1 is the only option that satisfies the rotation + per-tenant isolation constraints without adding a new vendor (Constraint 3).

Implications

Required

The downstream consequences — concrete things that change, break, or need new infrastructure.

- New runbook for KMS key rotation events.
- Latency budget eaten: ~1.6ms per request.
- New audit log entries for every encrypt/decrypt — observability cost +5%.

10
Related Decisions
Optional
Decisions this depends on, supersedes, or relates to. The graph is the whole point of the field.
```
Depends on: ADR-0011 (Cloud provider). Supersedes: ADR-0034 (Disk-level encryption).
```
11
Related Requirements
Optional
Cite the actual requirement IDs (compliance / spec) this decision satisfies.
```
SOC 2 CC6.1, GDPR Art. 32(1)(a).
```
12
Notes
Optional
Free-form: meeting minutes, dissenting opinions, follow-up tasks.
```
Two reviewers dissented on Position 2 (Vault). See thread #arch-2026-04-15.
```

Worked example

A real ADR written in the Tyree-Akerman format. Copy the markdown and adapt it.

TA-0014: Customer data encryption at rest

Issue

How do we encrypt customer data at rest such that we satisfy SOC 2 CC6.1 and GDPR Art. 32(1)(a) without adding a vendor to the audit scope?

Decision

Adopt envelope encryption: AWS KMS-managed Customer Master Key (CMK) + per-tenant Data Encryption Keys (DEK) + libsodium for application-layer encrypt/decrypt.

Status

Approved — Author: A. Lee. Reviewer: Architecture Review Board (ARB). Date: 2026-04-15.

Group

Security

Assumptions

AWS remains our primary cloud for the next 24 months.
Performance budget allows ~2ms additional latency per encrypted

field at the application layer.

Per-tenant blast-radius isolation is a requirement for our enterprise

tier (assumed from Sales spec, to be re-validated 2026-Q3).

Constraints

Customer data must be encrypted at rest with rotatable keys.
Per-tenant key separation.
No new vendor on the SOC 2 audit scope this quarter.
Recovery Time Objective (RTO) ≤ 1 hour for the keystore.

Positions

KMS envelope encryption (chosen).
Application-managed keys backed by HashiCorp Vault.
Disk-level encryption only (EBS-encrypt + LUKS).

Argument

Position 1 is the only option that satisfies all three primary constraints (rotation, per-tenant separation, no-new-vendor) without adding HashiCorp to the audit scope (which Position 2 would require). Position 3 fails the per-tenant separation constraint outright.

The latency cost of Position 1 (~1.6ms p99 per encrypt) is within the ~2ms assumption budget.

Implications

New runbook required for KMS key-rotation events (quarterly).
Application latency budget eaten: ~1.6ms p99 per encrypted field.
New audit log entries for every encrypt/decrypt operation — estimated

observability storage cost increase: ~5%.

DR drill required to validate RTO ≤ 1 hour for the keystore.

Related Decisions

Depends on: ADR-0011 (AWS as primary cloud).
Supersedes: ADR-0034 (Disk-level encryption only).
Related to: ADR-0058 (Audit log retention).

Related Requirements

SOC 2 CC6.1; GDPR Art. 32(1)(a); internal SEC-POL-04 §3.

Notes

Two reviewers (P. Singh, M. Costa) dissented on Position 2, arguing that Vault would future-proof a multi-cloud strategy. The ARB acknowledged the concern but ruled the audit-scope cost decisive. Revisit if a multi-cloud ADR is opened.

Field of application

Honest accounts of where this template was the right shape — and where it wasn't.

Context
Encryption-at-rest decision in a regulated environment.
Outcome
Tyree-Akerman's Constraints/Assumptions split was load-bearing — the audit reviewer asked exactly that question. The ADR was the answer.
Context
Picking an internal logging library.
Outcome
Wrong shape. 12 sections for a single-page decision. Should have been ADR-Lite.

Tags:heavyweight regulated review board