ADR(Architecture Decision Records)로 기술 의사결정 기록하기

ADR이 무엇인지, 왜 필요한지, 그리고 실제 프로젝트에서 어떻게 활용했는지를 정리합니다.

2026.03.30 ·

adr documentation architecture decision-record

ADR이란

ADR(Architecture Decision Record)은 소프트웨어 프로젝트에서 내린 기술적 의사결정을 구조화된 문서로 기록하는 것이다. 어떤 결정을 내렸는지뿐만 아니라, 왜 그런 결정을 내렸는지, 어떤 대안을 검토했는지, 그 결정의 결과로 무엇이 달라지는지를 함께 남긴다.

코드는 “무엇을”과 “어떻게”를 보여준다. 커밋 메시지와 PR은 “무엇을 변경했는지”를 보여준다. 하지만 “왜 이 방식을 선택했는지”는 어디에도 남지 않는다. ADR은 바로 이 “왜”를 기록하는 문서다.

코드       → 무엇을, 어떻게 (What, How)
커밋 로그   → 무엇을 변경했는지 (What changed)
PR 리뷰    → 변경에 대한 피드백 (Feedback)
ADR        → 왜 이렇게 결정했는지 (Why)

ADR의 기원

ADR의 개념은 2011년 Michael Nygard가 작성한 블로그 포스트 “Documenting Architecture Decisions”에서 시작되었다. Nygard는 “Release It!”의 저자이기도 하다.

그의 핵심 주장은 간단했다. “아키텍처 결정은 코드와 함께 버전 관리되어야 한다.” 별도의 위키나 컨플루언스가 아니라, 프로젝트 저장소 안에 마크다운 파일로 관리하자는 것이다.

이 아이디어는 이후 ThoughtWorks Technology Radar에서 “Adopt(채택)” 등급으로 추천되면서 널리 알려졌다. ThoughtWorks는 ADR을 “경량 아키텍처 의사결정 기록(Lightweight Architecture Decision Records)“이라고 소개하며, 팀의 의사결정 맥락을 보존하는 효과적인 방법으로 평가했다.

현재는 GitHub, Spotify, Amazon 등 대규모 조직부터 개인 프로젝트까지 폭넓게 사용되고 있다.

왜 ADR을 쓰는가

”왜 이렇게 했지?” 문제

6개월 전에 작성한 코드를 다시 보면 이런 의문이 생긴다.

“왜 React 대신 Astro를 선택했지?”
“왜 이 라이브러리를 쓰고 있지? 다른 건 없었나?”
“왜 이 구조로 폴더를 나눴지?”

코드만 봐서는 알 수 없다. Git blame으로 커밋을 찾아봐도 “프레임워크 변경”이라는 커밋 메시지만 있을 뿐, 검토한 대안과 결정 근거는 남아있지 않다.

ADR이 있으면 이 질문에 바로 답할 수 있다. 결정 당시의 맥락, 검토한 선택지, 최종 결정과 근거가 모두 기록되어 있기 때문이다.

온보딩 가속

새로운 팀원이 합류했을 때, ADR 폴더를 순서대로 읽으면 프로젝트의 기술적 결정 히스토리를 빠르게 파악할 수 있다. “왜 이렇게 되어있죠?”라는 질문에 “ADR-003 읽어보세요”로 답할 수 있다.

같은 논의의 반복 방지

ADR이 없으면 같은 주제에 대한 논의가 반복된다. “우리 왜 GSAP 안 쓰기로 했었지?”라는 질문이 매번 나오고, 매번 같은 논의를 처음부터 다시 해야 한다. ADR에 기록이 있으면 이전 결정의 맥락을 확인하고, 상황이 바뀌었는지만 판단하면 된다.

결정의 질 향상

ADR을 쓰려면 “배경 → 대안 검토 → 결정 → 근거”를 구조적으로 정리해야 한다. 이 과정 자체가 결정의 질을 높인다. 막연한 감으로 내린 결정과, 대안을 비교하고 근거를 명시한 결정은 다르다.

ADR의 기본 구조

Nygard가 제안한 원형 포맷은 다섯 가지 항목으로 구성된다.

Title (제목)

짧은 명사구로 작성한다. 번호를 앞에 붙여 순서를 표시한다.

ADR-001: PostgreSQL을 주 데이터베이스로 사용

Status (상태)

결정의 현재 상태를 나타낸다.

상태	의미
제안됨 (Proposed)	논의 중이며 아직 확정되지 않음
승인됨 (Accepted)	합의되어 적용 중인 결정
폐기됨 (Deprecated)	더 이상 유효하지 않으며, 새 ADR로 대체됨
대체됨 (Superseded)	다른 ADR에 의해 대체됨 (대체한 ADR 번호를 명시)

Context (배경)

이 결정이 필요한 이유를 설명한다. 프로젝트의 기술적, 비즈니스적 제약 조건을 포함한다.

Decision (결정)

최종 선택한 방향을 능동태로 명확하게 기술한다. “~를 사용한다”, “~방식을 채택한다” 형태로 작성한다.

Consequences (결과)

결정으로 인해 발생하는 긍정적, 부정적 결과를 모두 기록한다. 트레이드오프를 투명하게 드러내는 것이 핵심이다.

Nygard 원형 외에도 다양한 변형이 있다. MADR(Markdown Any Decision Records)은 “검토한 선택지(Considered Options)“와 “각 선택지의 장단점” 섹션을 추가한 확장 포맷이다. Y-Statements 형식은 한 문장으로 결정을 요약한다.

"[상황]의 맥락에서, [관심사]에 직면하여,
[결정]을 선택했고, [품질 속성]을 달성하며,
[트레이드오프]를 수용한다."

어떤 포맷이든 핵심은 같다. 맥락, 결정, 근거를 함께 기록하는 것.

실제 적용 사례

이 포트폴리오 프로젝트에서는 .claude/decisions/ 폴더에 ADR을 관리하고 있다. 현재까지 5개의 ADR을 작성했다.

ADR-001: Astro 버전 선택 (v5 vs v6)

프로젝트 시작 시점에 Astro 6가 릴리스된 지 9일밖에 되지 않은 상황이었다. 최신 버전을 바로 채택할지, 안정된 v5를 사용할지 결정이 필요했다.

배경: Node.js 20 LTS 환경에서 개발 중이었는데, Astro 6는 Node.js 22 이상을 필수로 요구했다. 릴리스 직후라 서드파티 플러그인 호환성도 미검증 상태였다.

결정: Astro 5를 사용하되, v6 마이그레이션을 위한 호환 전략 3가지를 적용했다.

Content Collections에서 glob() loader 사용 (v6 기본 패턴)
설정 파일을 src/content.config.ts 위치에 배치 (v6 권장 위치)
Tailwind는 @tailwindcss/vite 방식 사용 (v6에서 @astrojs/tailwind 제거됨)

이 ADR 덕분에 “왜 최신 버전을 안 쓰는지”에 대한 답이 명확하다. 그리고 마이그레이션 시점이 오면, 어떤 부분을 변경해야 하는지도 바로 알 수 있다.

ADR-002: 의존성 패키지 선정

프로젝트에 어떤 패키지를 설치할지, 왜 설치하지 않는지를 기록했다.

특히 설치하지 않은 패키지와 그 이유를 함께 기록한 것이 유용했다. “왜 Biome 안 쓰지?”라는 질문에 “.astro 파일 지원이 불완전해서”라고 바로 답할 수 있다. 상황이 바뀌어서 Biome의 Astro 지원이 완성되면, 이 ADR을 폐기하고 새 결정을 내리면 된다.

ADR-003: 컴포넌트 아키텍처 패턴

Atomic Design, Feature-Sliced Design, Colocation 패턴, 계층형+도메인 하이브리드 구조를 비교하고, 최종적으로 하이브리드 구조를 채택했다.

이 ADR에는 각 패턴의 장단점 비교표가 포함되어 있어, “왜 Atomic Design을 안 썼는지”가 명확하다. 5단계 분류가 개인 프로젝트에는 과도하고, Templates 계층이 Astro의 layouts/와 중복된다는 근거가 기록되어 있다.

ADR-004: UI 인터랙션 전략

“CSS + GSAP (최소한으로 적용)“이라는 기획 원칙을 구체적으로 어떻게 구현할지 결정했다. 어떤 인터랙션에 어떤 기술을 사용할지를 매핑 테이블로 정리했다.

인터랙션	구현 방식
페이지 전환	Astro ClientRouter
스크롤 등장	Intersection Observer + CSS
타임라인 드로잉	GSAP ScrollTrigger (이 한 곳만)
숫자 카운트업	Vanilla JS requestAnimationFrame
호버 효과	CSS transition

GSAP을 Work 페이지 타임라인 한 곳으로 제한한 결정과 그 근거(번들 크기 최소화)가 명시되어 있어, 이후 “이 부분도 GSAP으로 하면 안 되나?”라는 질문에 맥락을 제공한다.

ADR-005: Astro 스크립트 초기화 전략

PR 리뷰에서 발생한 기술적 논의를 ADR로 기록한 사례다. astro:page-load 이벤트만 사용할지, 직접 호출과 병행할지에 대한 결정이다.

이 ADR은 다른 것들에 비해 범위가 작지만, PR 리뷰에서 나온 기술적 합의를 영구적으로 보존한다는 점에서 가치가 있다. PR 코멘트는 시간이 지나면 찾기 어렵지만, ADR은 프로젝트 디렉토리에서 바로 접근할 수 있다.

Claude Code와 함께 ADR 관리하기

이 프로젝트에서는 Claude Code를 개발 파트너로 사용하고 있고, ADR도 Claude Code와 함께 작성한다. .claude/decisions/ 폴더에 ADR을 배치하면, Claude Code가 CLAUDE.md의 지침에 따라 ADR을 참조하고 새 결정이 필요할 때 작성을 제안한다.

워크플로우

1. 기술적 결정이 필요한 상황 발생
2. Claude Code와 논의하며 대안 검토
3. 결정 합의 후 ADR 문서 작성
4. .claude/decisions/ 폴더에 커밋

CLAUDE.md에 다음과 같은 규칙을 정의해두면, Claude Code가 ADR 작성이 필요한 상황을 인지하고 제안한다.

## 의사결정 기록 (ADR)

- 개발 중 기술적 의사결정이 필요한 경우, `.claude/decisions/` 폴더에 ADR 파일을 작성한다.
- 파일명 형식: `NNN-제목.md`
- 기존 결정을 변경할 경우, 기존 ADR의 상태를 '폐기됨'으로 변경하고 새 ADR을 작성한다.

이 방식의 장점은 의사결정 과정이 자연스럽게 문서화된다는 것이다. Claude Code와 대화하면서 대안을 비교하고, 그 결과를 ADR로 저장하면 별도의 문서화 작업이 필요 없다.

ADR 도입 팁

작게 시작한다

처음부터 모든 결정을 ADR로 기록하려 하면 부담만 커진다. 프로젝트에서 가장 자주 “왜?”라는 질문이 나오는 결정부터 기록하는 것이 좋다.

프레임워크 선택
주요 라이브러리 선택/미선택
아키텍처 패턴 결정
코딩 컨벤션 결정

일상적이고 되돌리기 쉬운 결정(변수명 규칙, import 정렬 순서 등)은 ADR 대신 lint 규칙이나 .editorconfig로 해결하는 것이 낫다.

짧게 쓴다

ADR은 논문이 아니다. Nygard도 1~2페이지를 권장했다. 결정의 맥락과 근거가 전달되면 충분하다. 너무 길면 아무도 읽지 않고, 쓰는 사람도 부담을 느껴 작성 자체를 미루게 된다.

불변성을 유지한다

한 번 승인된 ADR은 수정하지 않는다. 결정이 바뀌면 기존 ADR의 상태를 “폐기됨” 또는 “대체됨”으로 변경하고, 새 ADR을 작성한다. 이렇게 하면 결정의 변화 과정까지 추적할 수 있다.

”안 한 이유”도 기록한다

검토했지만 채택하지 않은 대안과 그 이유를 기록하는 것이 중요하다. 나중에 같은 대안이 다시 제안되었을 때, 이전에 왜 선택하지 않았는지 확인하고, 당시와 상황이 바뀌었는지만 판단하면 된다.

코드와 함께 둔다

ADR은 프로젝트 저장소 안에 마크다운 파일로 관리한다. 컨플루언스나 노션 같은 외부 도구에 두면 코드와 문서가 분리되어, 시간이 지날수록 동기화가 깨진다. 저장소에 함께 두면 PR 리뷰 시 ADR도 함께 검토할 수 있고, 브랜치별로 결정의 맥락이 함께 이동한다.

정리

항목	내용
ADR이란	기술적 의사결정의 배경, 대안, 결정, 근거를 기록하는 구조화된 문서
핵심 가치	코드에 담기지 않는 “왜?”를 보존하여, 미래의 나와 팀원이 결정의 맥락을 이해할 수 있게 함
기본 구조	Title → Status → Context → Decision → Consequences
도입 시점	프로젝트 초기에 시작하면 좋지만, 언제든 시작할 수 있음
관리 원칙	짧게 쓰고, 불변성을 유지하고, 코드와 함께 버전 관리

ADR의 본질은 의사결정의 맥락을 코드와 함께 보존하는 것이다. 코드 리뷰는 “이 코드가 올바른가?”를 검증하지만, ADR은 “이 결정이 합리적인가?”를 검증한다. 6개월 후에 코드를 다시 열었을 때, “왜 이렇게 했지?”라는 질문에 답할 수 있는 프로젝트와 없는 프로젝트는 유지보수 효율에서 큰 차이가 난다.

참고 자료

원본 및 공식 자료

Michael Nygard — Documenting Architecture Decisions — ADR 개념을 처음 제안한 2011년 블로그 포스트. ADR의 원형 포맷(Title, Status, Context, Decision, Consequences)이 정의되어 있다.
ADR GitHub Organization — ADR 관련 리소스, 템플릿, 도구를 모아둔 GitHub 페이지. ADR 생태계의 전체 그림을 파악하기 좋다.

템플릿 및 도구

Joel Parker Henderson — Architecture Decision Record — 다양한 ADR 템플릿과 실제 예시를 모아둔 저장소. Nygard 원형, MADR, Y-Statements 등 여러 포맷을 비교할 수 있다.
MADR (Markdown Any Decision Records) — Nygard 포맷을 확장하여 “검토한 선택지”와 “장단점 비교” 섹션을 추가한 템플릿. 대안 비교가 중요한 결정에 적합하다.
adr-tools (Nat Pryce) — ADR 파일을 CLI로 생성하고 관리하는 Bash 도구. adr new "제목" 명령으로 번호가 자동 부여된 ADR 파일을 생성한다.
Log4brains — ADR 마크다운 파일로부터 검색 가능한 정적 웹사이트를 생성하는 도구. ADR이 많아졌을 때 탐색성을 높여준다.