---
id: wiki-2026-0508-adr-architecture-decision-record
title: ADR (Architecture Decision Records)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [ADR, Architecture Decision Record, Decision Log, Lightweight ADR]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [architecture, documentation, decisions, governance]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: markdown
  framework: madr
---

# ADR (Architecture Decision Records)

## 매 한 줄
> **"매 architecturally significant decision 을 매 immutable, dated, numbered markdown 파일로 기록하는 lightweight practice."** Michael Nygard 의 2011 blog post 가 origin, 매 이후 MADR / Y-statement 등 variants 가 표준화. 2026 현재 매 GitOps + LLM agent 시대에 매 ADR 은 매 single source of truth — 매 *왜 이 design 인가* 의 history 를 매 codebase 안에 매 living document 로 유지.

## 매 핵심

### 매 5 essential fields (Nygard original)
- **Title**: 매 short, declarative — `0007: Use Postgres for OLTP`.
- **Status**: `proposed | accepted | deprecated | superseded by NNNN`.
- **Context**: 매 forces — 매 problem, 매 constraint, 매 stakeholder.
- **Decision**: 매 actually chosen approach (one paragraph).
- **Consequences**: 매 positive + negative + neutral. 매 honest trade-offs.

### 매 MADR (Markdown ADR) extras
- Decision drivers, considered options, pros/cons of each.
- 매 numbered (`adr/0001-record-architecture-decisions.md`).
- 매 PR 에 포함 — 매 code change 와 매 same review.

### 매 응용
1. 매 framework / DB / cloud provider 선택.
2. 매 API style (REST vs gRPC vs GraphQL).
3. 매 auth, observability, deploy strategy.
4. 매 LLM model / provider 선택.

## 💻 패턴

### 1) Nygard ADR template
```markdown
# 0007. Use Postgres for OLTP

Date: 2026-05-10
Status: Accepted

## Context
We need an OLTP store with strong ACID, JSON support, and managed offerings
across AWS/GCP/Azure. Team size 12. Expected QPS 5k.

## Decision
Adopt Postgres 17 (RDS / Aurora / Cloud SQL / Neon).

## Consequences
+ Mature ecosystem, ACID, JSONB, pgvector.
- Vertical scaling ceiling — needs Citus / sharding past ~30TB.
~ Team will invest in `psql` / pgbouncer expertise.
```

### 2) MADR full template
```markdown
# Use Postgres for OLTP

* Status: Accepted
* Deciders: @alice, @bob, @carol
* Date: 2026-05-10

## Context and Problem Statement
...

## Decision Drivers
* ACID, managed offering, ecosystem
* Cost ceiling at 5k QPS
* Vector search (pgvector)

## Considered Options
* Postgres
* MySQL
* CockroachDB
* DynamoDB

## Decision Outcome
Chosen option: "Postgres", because it dominates on drivers (1) and (3),
and matches (2) within budget.

### Positive Consequences
* JSONB, pgvector, mature tooling
### Negative Consequences
* Sharding burden later
```

### 3) Y-statement (one-liner ADR)
```text
In the context of <use case>,
facing <concern>,
we decided for <option>
to achieve <quality>,
accepting <downside>.
```

### 4) adr-tools (CLI)
```bash
brew install adr-tools
adr init doc/adr
adr new "Use Postgres for OLTP"
adr new -s 7 "Use CockroachDB instead of Postgres"  # 매 supersede
adr generate toc > doc/adr/README.md
```

### 5) GitHub PR-based workflow
```bash
git checkout -b adr/0007-postgres
$EDITOR doc/adr/0007-use-postgres-for-oltp.md
git commit -m "ADR-0007: Use Postgres for OLTP"
gh pr create --label adr --reviewer @platform-team
```

### 6) Status transitions
```markdown
# 0007. Use Postgres
Status: Superseded by [0019](0019-use-cockroachdb.md)
```

### 7) LLM-assisted drafting (2026)
```text
You are an ADR scribe. Given a Slack discussion transcript,
output a MADR-format ADR with:
- Decision drivers extracted from the discussion
- All options mentioned with pros/cons
- Status: Proposed
Do not invent options not discussed.
```

### 8) Linking from code
```ts
// See ADR-0007 for why Postgres + pgvector instead of pinecone
import { Pool } from 'pg';
```

## 매 결정 기준
| 상황 | ADR 작성 여부 |
|---|---|
| 매 reversible (1 file 내 결정) | 작성 X |
| 매 cross-team / cross-service impact | 작성 |
| 매 vendor / framework 선택 | 작성 |
| 매 reverse 시 매 1주 이상 cost | 작성 |
| 매 trivial styling | 작성 X (lint config 로) |

**기본값**: 매 "되돌리는 데 1주 이상 걸리면 ADR". 매 Nygard 5-field minimum, 매 큰 결정만 MADR.

## 🔗 Graph
- 부모: [[Architecture Documentation]]
- 응용: [[ATAM]] · [[RFC Process]] · [[C4 Model]]
- Adjacent: [[GitOps]]

## 🤖 LLM 활용
**언제**: 매 design discussion 의 transcript → ADR draft 자동 생성, 매 ADR audit (status 누락 등).
**언제 X**: 매 LLM 이 매 invent 한 driver/option 을 매 사실로 commit X. 매 human verifier 필요.

## ❌ 안티패턴
- **Wiki-only ADR**: 매 codebase 밖 → 매 stale. 매 repo 안에 두고 매 PR 로 review.
- **Mutable ADR**: 매 기존 ADR 을 edit. 매 새 ADR 로 supersede.
- **Decision-only**: 매 Context / Consequences 누락 → 매 6개월 후 매 누구도 이유 모름.
- **Too coarse**: 매 "Use Microservices" — 매 specific 으로 (어떤 service, 매 boundary 어떻게).
- **Too fine**: 매 매 PR 마다 ADR — 매 noise.

## 🧪 검증 / 중복
- Verified (Nygard 2011 blog, MADR spec adr.github.io, Thoughtworks Tech Radar).
- 신뢰도 A.
- 매 [[ADR_(Architecture_Decision_Records)|ADR_(Architecture_Decision_Record)]] 가 매 redirect 로 본 문서를 가리킴.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Nygard + MADR templates + adr-tools workflow |
