# ADR-{번호}: {결정 제목}

## 상태 (Status)
...

당신은 시니어 소프트웨어 아키텍트입니다. 다음 템플릿을 사용하여
ADR (Architecture Decision Record)을 생성하세요.

...

마이그레이션을 위한 ADR을 생성하세요.

FROM: {현재 솔루션, 버전, 운영 환경 적용 기간}
...

기술 선택을 위한 ADR을 생성하세요.

TASK: {선택된 기술이 해결하는 문제}
...

## 예시: 실제 프로젝트를 위한 ADR

한 팀이 여행 앱 API를 위한 캐싱 전략(caching strategy)을 선택하고 있습니다. 위 프롬프트를 사용하여 AI가 생성한 결과는 다음과 같습니다:

구체성에 주목하세요. "성능을 향상시킨다" 또는 "부하를 줄인다"와 같은 모호한 문구는 없습니다. 대신 숫자를 사용합니다: 800ms에서 15-25ms로 단축, 속도 제한(rate limit) 소비 40% 감소, 월 $5 비용 발생. 모든 항목은 6개월 후에도 검증 가능합니다.

## Git 히스토리 및 PR 설명을 통한 ADR 생성

AI는 기존의 산출물(artifacts)로부터 아키텍처 결정(architectural decisions)을 추출할 수 있습니다. 이는 "3개월 전에 결정을 내렸는데 문서화하는 것을 잊어버렸다"는 문제를 해결해 줍니다.

사후 생성을 위한 프롬프트:

Claude Code의 경우, 이 프로세스를 다음과 같이 자동화할 수 있습니다:

## 자동화: CI/CD 파이프라인의 일부로서의 ADR

수동 ADR 생성도 작동하지만 규율(discipline)이 필요합니다. CI 자동화는 인간의 요소를 제거합니다.

### GitHub Action: ADR 확인하기

이 워크플로(workflow)는 차단하기보다는 경고를 주는 방식입니다. ADR 요구 사항을 통해 PR을 차단하는 것은 도입을 저해하는 마찰(friction)을 만듭니다.

### 저장소 내 ADR 파일 구조

앞에 0을 붙인 세 자리 숫자 번호 매기기를 사용합니다. 파일은 시간 순서대로 배치합니다. 파일 하나당 결정 하나를 원칙으로 합니다.

### 새 ADR 생성을 위한 스크립트

사용법: `./scripts/new-adr.sh "REST에서 GraphQL로 전환"`.

## AI 에이전트를 위한 컨텍스트 엔지니어링(context engineering)과 ADR 통합

ADR은 AI 코딩을 위한 컨텍스트 (context)로서 추가적인 가치를 얻습니다. AI 에이전트 (Claude Code, Cursor, Copilot)가 코드베이스와 함께 작업할 때, ADR은 코드 자체에는 존재하지 않는 아키텍처 컨텍스트 (architectural context)를 제공합니다.

프로젝트의 CLAUDE.md에 ADR을 추가하기:

AI 에이전트는 코드를 생성할 때 이러한 결정 사항을 존중합니다. 알림을 위해 REST 호출을 제안하는 대신, ADR-005에 해당 결정이 기록되어 있으므로 이벤트 버스 (event bus)를 사용합니다. AI를 위한 컨텍스트 구조화에 대한 자세한 내용은 다음을 참조하세요: [Context Engineering Guide](https://dev.to/blog/context-engineering-guide/).

## ADR 작성 시 흔히 발생하는 실수

**너무 추상적인 컨텍스트 (Context).** "성능을 개선해야 했습니다"는 쓸모가 없습니다. "p95 기준 API 응답 시간이 2.3초로 증가했습니다; SLA는 500ms 미만을 요구합니다"는 유용합니다.

**대안 (Alternatives) 누락.** 대안 섹션이 없으면 ADR은 의도적인 선택이라기보다 사후 정당화 (post-hoc justification)처럼 보입니다. 설령 대안이 하나(아무것도 하지 않음)뿐이었더라도, 그것을 기록할 가치가 있습니다.

**너무 넓은 범위 (Scope).** ADR은 하나의 결정을 포착합니다. "마이크로서비스 (microservices)로의 전환"은 하나의 결정이 아닙니다. 그것은 열 개의 결정입니다. 각 서비스, 각 계약 (contract), 각 통신 메커니즘은 각각의 ADR을 가질 자격이 있습니다.

**오래된 상태 (Stale Status).** 아주 오래전에 다른 결정으로 대체되었음에도 `Accepted` 상태로 남아 있는 ADR은 독자를 오도합니다. 상태를 `Superseded by ADR-{N}`으로 업데이트하는 데는 몇 초밖에 걸리지 않으며, 다른 사람들의 시간을 몇 시간이나 아껴줍니다.

**ADR을 문서화 (documentation)와 혼동하는 것.** ADR은 시스템이 어떻게 작동하는지를 설명하지 않습니다. 시스템이 왜 그런 방식으로 작동하는지를 설명합니다. 어떻게 작동하는지는 [SOP 및 운영 문서 (SOPs and operational documentation)](https://dev.to/blog/sop-generator-ai-documentation/)의 역할입니다.

## 지표: ADR 관행의 효과 측정

ADR이 팀에 도움이 되고 있는지 보여주는 네 가지 지표:

| 지표 (Metric) | 측정 방법 (How to measure) | 목표 (Target) |
| --- | --- | --- |
| ADR 커버리지 (ADR coverage) | 월간 ADR 수 / 월간 아키텍처 PR 수 | > 70% |
| ... | | |

ADR 커버리지가 50% 미만이라는 것은 프로세스가 정착되지 않았음을 의미합니다. ADR 생성 소요 시간 (Time-to-ADR)이 1주일 이상 걸린다는 것은 맥락 (context)이 소실되고 있으며, 기록이 허구적인 재구성 (fictional reconstruction)이 되고 있음을 의미합니다.

## 체크리스트: 팀에 ADR 도입하기

1. `docs/adr/` 디렉토리와 템플릿 생성
2. 이미 내려진 결정들에 대해 3~5개의 ADR 작성 (AI의 도움을 받아 소급 적용)
3. 빠른 생성을 위한 `new-adr.sh` 스크립트 추가
4. 차단(block)이 아닌 소프트 경고(soft warning)를 주는 GitHub Action 설정
5. AI 에이전트를 위해 주요 ADR을 CLAUDE.md / .cursorrules에 포함
6. 코드를 리뷰하듯 ADR을 리뷰: PR을 통해서
7. 분기별로 모든 ADR을 검토하고 상태 업데이트

처음 세 단계는 AI와 함께라면 30분이면 충분합니다. 나머지는 2~3번의 스프린트 (sprint)를 거치며 형성되는 습관입니다.

_아키텍처 결정 기록 (architecture decision records)이나 엔지니어링 프로세스에 도움이 필요하신가요? 저는 스타트업이 AI 제품을 구축하고 프로세스를 자동화하도록 돕습니다 — [belov.works](https://belov.works)._

## FAQ

### ADR을 코드처럼 풀 리퀘스트 (pull requests)를 통해 리뷰해야 하나요?

네, 이것이 가장 효과적인 접근 방식입니다. PR을 통해 ADR을 리뷰하면 아키텍처 기록의 감사 가능성 (auditable)을 유지할 수 있고, 팀원들이 결정이 확정되기 전에 이의를 제기하거나 개선할 수 있으며, 코드 변경과 그 근거 (rationale) 사이의 자연스러운 연결 고리를 만들어 줍니다. 또한 리뷰 프로세스는 이견을 조기에 드러냅니다. PR에서 논쟁 중인 ADR이, 구현 6개월 후에 발견된 논란이 있는 결정보다 훨씬 낫습니다.

### ADR의 적절한 세분화 수준 (granularity)은 어느 정도인가요 — 서비스당 하나인가요, 아니면 중요한 선택마다 하나인가요?

서비스나 프로젝트당 하나가 아니라, 하나의 원자적 결정 (atomic decision) 당 하나의 ADR을 작성해야 합니다. 캐싱을 위해 Redis를 선택하는 것과, 관리형 제공업체로 구체적으로 Upstash를 선택하는 것은 두 개의 별개 ADR입니다. "마이크로서비스로의 전환"은 하나의 ADR이 아닙니다. 최소한 서비스 경계당 하나, 통신 프로토콜을 위한 하나, 그리고 배포 전략을 위한 하나가 필요합니다. 지나치게 광범위한 ADR은 정밀도를 잃고, 지나치게 좁은 ADR은 소음이 됩니다.

### 팀이 인수되거나 코드베이스를 상속받을 때 ADR은 어떻게 처리해야 하나요?

상속받은 ADR은 검증되지 않은 가설 (unverified hypotheses)로 취급하십시오. 문맥 파악을 위해 읽되, 시스템의 현재 상태와 대조하여 각 ADR을 감사 (audit)해야 합니다. 어떤 결정은 오래되어 쓸모없게 되었을 것이고 (라이브러리가 지원 중단되었거나, 부하 가정이 변경된 경우 등), 어떤 결정은 여전히 유효할 것입니다. 가장 빠른 방법은 하루 동안 진행하는 "ADR 감사 스프린트 (ADR audit sprint)"입니다. 모든 ADR을 읽고, 상태 (Status) 필드를 업데이트하며, 문맥이 바뀐 부분에는 짧은 노트를 추가하십시오. 이러한 투자는 개발 첫 달에 보상으로 돌아옵니다.