Architecture Decision Records는 기술적 선택의 이유를 기록합니다. 이 완벽 가이드에서는 ADR 형식, 템플릿, 모범 사례, 도구, 그리고 ADR을 팀 워크플로에 통합하여 의사결정이 사라지지 않도록 하는 방법을 다룹니다.

Architecture Decision Records (ADR): 완벽 가이드

모든 소프트웨어 시스템은 수백 가지 의사결정에 의해 형성됩니다. MongoDB 대신 PostgreSQL. GraphQL 대신 REST. 마이크로서비스 대신 모놀리스. Request-response 대신 Event-driven. 각 선택은 이후의 선택을 제약하며, 이들이 모여 아키텍처를 정의합니다.

문제는 의사결정이 보이지 않는다는 것입니다. 코드는 무엇을 만들었는지 보여주지만, 왜 그렇게 만들었는지는 보여주지 않습니다. PostgreSQL을 선택한 지 6개월이 지나면, 팀이 DynamoDB를 검토했는지, 성능 요구사항이 무엇이었는지, 왜 eventual consistency가 수용 불가능했는지 아무도 기억하지 못합니다. 결정은 코드에 녹아 있지만, 그 이유는 사라집니다.

Architecture Decision Records (ADR)는 각각의 중요한 의사결정을 짧고 구조화된 문서로 기록하여 이 문제를 해결합니다. ADR은 소프트웨어 엔지니어링에서 가장 레버리지가 높은 문서화 관행 중 하나로, 도입이 쉽고 유지 비용이 낮으며, 필요할 때 매우 큰 가치를 발휘합니다.

이 가이드는 기초부터 고급 실천까지 모든 것을 다룹니다: ADR이 무엇인지, 어떻게 작성하는지, 오늘 바로 적용할 수 있는 템플릿, 흔한 실수, 그리고 최신 도구와 함께 ADR을 워크플로에 통합하는 방법입니다.

Architecture Decision Record란?

Architecture Decision Record는 단일 아키텍처 의사결정을 기록하는 짧은 문서입니다. _단일_과 _짧은_이 핵심입니다:

단일: 하나의 ADR, 하나의 결정. "주문 서비스에 PostgreSQL 사용"은 하나의 ADR입니다. "전체 데이터베이스 전략 수립"은 설계 문서이지 ADR이 아닙니다.
짧은: ADR은 한 페이지에 들어가야 합니다. 더 길다면, 여러 결정을 문서화하고 있거나 구현 세부사항을 너무 많이 포함하고 있을 가능성이 높습니다.

이 개념은 Michael Nygard가 2011년 블로그 포스트에서 대중화했습니다. 이후 ADR은 스타트업부터 정부 기관까지 다양한 조직에서 채택되었습니다. 영국 Government Digital Service, Spotify 및 수많은 엔지니어링 팀이 ADR을 표준 관행으로 사용하고 있습니다.

ADR이 기록하는 것

모든 ADR은 네 가지 근본적인 질문에 답합니다:

맥락은 무엇이었는가? 어떤 상황이나 문제가 이 결정을 촉발했는가?
무엇을 결정했는가? 우리가 내린 구체적인 아키텍처 선택은 무엇인가?
어떤 대안을 검토했는가? 고려한 다른 옵션은 무엇이었는가?
결과는 무엇인가? 이 결정에 따르는 트레이드오프, 리스크, 영향은 무엇인가?

이것이 전부입니다. 네 가지 질문. 잘 작성된 ADR은 한 페이지 이내로 네 가지 모두에 답할 수 있습니다.

ADR이 아닌 것

설계 문서가 아닙니다. ADR은 무엇이 어떻게 구현되었는지를 설명하지 않습니다. 특정 접근 방식이 왜 선택되었는지를 설명합니다.
RFC가 아닙니다. RFC(Request for Comments)는 논의를 위한 제안입니다. ADR은 결론 난 결정을 문서화합니다(ADR이 제안으로 시작하여 수락 상태로 전환될 수 있지만).
회의록이 아닙니다. ADR은 그 결과를 기록하지, 그에 이르는 논의를 기록하지 않습니다.
포괄적인 문서가 아닙니다. ADR은 아키텍처 다이어그램, API 스펙, 런북을 보완합니다. 이를 대체하지 않습니다.

표준 ADR 템플릿

여러 ADR 템플릿이 존재하지만, 대부분 같은 핵심 구조의 변형입니다. 다음은 완결성과 간결함의 균형을 맞춘 실용적인 템플릿입니다:

# ADR-NNNN: [결정을 설명하는 짧은 제목]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Date

[YYYY-MM-DD]

## Context

[상황을 설명합니다. 어떤 문제를 해결하려고 하는가? 어떤 제약이
존재하는가? 어떤 요인들이 작용하고 있는가? 구체적으로 작성합니다 --
관련된 곳에 숫자, 마감일, 팀 역량, 기술적 요구사항을 포함합니다.]

## Decision

[결정을 명확하고 간결하게 기술합니다. 능동태를 사용합니다:
"X를 사용할 것이다"가 적절하며, "X를 고려해야 한다"는 적절하지 않습니다.]

## Alternatives Considered

### [대안 1]
- 장점: ...
- 단점: ...
- 기각 사유: ...

### [대안 2]
- 장점: ...
- 단점: ...
- 기각 사유: ...

## Consequences

### 긍정적
- [무엇이 더 쉬워지거나 좋아지는가]

### 부정적
- [무엇이 더 어려워지거나 나빠지는가]

### 리스크
- [무엇이 잘못될 수 있는가]

## Related Decisions

- [관련 ADR 링크]

각 섹션 세부 설명

Status는 결정의 생애주기를 추적합니다. 일반적인 흐름은 Proposed -> Accepted입니다. 상황이 변하면 ADR은 Deprecated되거나 새로운 ADR에 의해 Superseded됩니다. 중요한 점은, ADR을 절대 삭제하지 말아야 한다는 것입니다 -- 기각된 결정도 가치가 있습니다. 이미 평가된 옵션을 미래 팀이 다시 검토하는 것을 방지하기 때문입니다.

Date는 결정이 내려진 시점을 기록합니다. 이는 시간적 맥락을 제공합니다: "2024년에 규모가 X였을 때 이 기술을 선택했다. 이제 규모가 10배가 되었으니 재검토해야 한다."

Context는 가장 중요한 섹션입니다. 잘 작성된 Context 섹션은, 상황이 이후 변했더라도 미래 독자가 이 결정이 당시에 왜 합리적이었는지 이해할 수 있을 만큼의 정보를 제공합니다. 구체적인 숫자("하루 5만 건의 주문 처리"), 제약 조건("PCI-DSS 준수 필수"), 팀 요소("3명의 엔지니어가 PostgreSQL 경험 보유, MongoDB 경험자 없음")를 포함하세요.

Decision은 모호하지 않아야 합니다. "주문 서비스의 주요 데이터 저장소로 PostgreSQL 16을 사용할 것이다"가 좋습니다. "관계형 데이터베이스를 고려해봐야 할 것 같다"는 ADR이 아닙니다 -- 이는 제안에 불과합니다.

Alternatives Considered는 장기적으로 가장 많은 시간을 절약하는 섹션입니다. 신규 엔지니어가 "왜 MongoDB를 사용하지 않았나요?"라고 물으면, 답이 바로 여기 있습니다. 1년 후 팀이 결정을 재검토할 때, 무엇을 평가했고 왜 기각했는지 확인할 수 있습니다. 이 섹션이 없으면, 팀은 같은 논쟁을 끝없이 반복하게 됩니다.

Consequences는 지적 정직함에 관한 것입니다. 모든 결정에는 트레이드오프가 있습니다. 단점을 인정하면 신뢰가 쌓이고, 미래 팀이 결정을 재검토해야 할 상황을 이해하는 데 도움이 됩니다.

완전한 ADR 예시

다음은 템플릿을 실제로 보여주는 현실적인 ADR입니다:

# ADR-0023: 서비스 간 통신에 Apache Kafka 사용

## Status

Accepted

## Date

2025-11-15

## Context

지난 1년간 플랫폼이 3개 마이크로서비스에서 12개로 성장했습니다.
현재 서비스들은 HTTP REST 호출을 통해 동기적으로 통신합니다. 이로
인해 여러 문제가 발생합니다:

- 연쇄 장애: 재고 서비스가 다운되면, 재고 확인이 eventual하게
  처리될 수 있음에도 주문 서비스가 주문을 처리할 수 없습니다.
- 강한 결합: 서비스들이 서로의 API 계약과 엔드포인트를 알아야 합니다.
- 성능 병목: 일부 작업이 4-5개의 동기 호출 체인을 발생시켜
  지연 시간이 누적됩니다.

현재 하루 약 10만 건의 이벤트를 처리합니다. 12개월 내에 50만 건으로
성장할 것으로 예상합니다. 팀은 8명의 백엔드 엔지니어로 구성되며,
그 중 2명이 Kafka 경험을 보유하고 있습니다.

## Decision

비동기 서비스 간 통신의 주요 메커니즘으로 Apache Kafka를 채택할
것입니다. 호출자가 즉각적인 결과를 필요로 하는 Request/Response
패턴(예: 인증 검사)에는 동기 HTTP를 유지합니다.

운영 오버헤드를 최소화하기 위해 관리형 Kafka 제공자인 Confluent
Cloud를 사용할 것입니다.

## Alternatives Considered

### RabbitMQ
- 장점: 운영이 더 간단하고 학습 곡선이 낮으며, 여러 메시징 패턴
  (pub/sub, point-to-point, routing)을 지원합니다.
- 단점: 도입 예정인 Event Sourcing 패턴에 덜 적합합니다.
  Replay/rewind 기능이 약합니다. Event-driven 아키텍처에서
  커뮤니티 동력이 Kafka 쪽으로 이동했습니다.
- 기각 사유: 감사 및 디버깅을 위한 이벤트 재생이 필요할 것으로
  예상됩니다. Kafka의 로그 기반 아키텍처가 더 적합합니다.

### AWS SQS + SNS
- 장점: 완전 관리형으로 유지보수할 인프라가 없고, AWS와의
  긴밀한 통합이 가능합니다.
- 단점: AWS 벤더 종속이 발생합니다. 메시지 순서 보장이 제한적입니다.
  내장 스트림 처리가 없습니다(Kinesis 또는 Lambda 필요).
  예상 볼륨에서 메시지당 비용이 더 높습니다.
- 기각 사유: AWS 종속을 심화시키지 않으려 하며, 금융 이벤트에
  대한 순서 보장 메시지 전달이 필요합니다.

### 기존 동기 HTTP 유지 (circuit breaker 적용)
- 장점: 새로운 인프라 불필요. 팀이 이미 익숙함. Circuit breaker로
  연쇄 장애를 해결할 수 있음.
- 단점: 강한 결합 문제를 해결하지 못합니다. 호출 체인 전반에 걸쳐
  지연 시간이 여전히 누적됩니다. Circuit breaker는 근본적인 결합
  문제에 대한 임시방편일 뿐입니다.
- 기각 사유: 근본 원인이 아닌 증상만 해결합니다.

## Consequences

### 긍정적
- 서비스가 분리됩니다: 생산자가 소비자를 알 필요가 없습니다.
- 비동기 워크플로에서 연쇄 장애가 제거됩니다.
- 이벤트 재생으로 강력한 디버깅 및 감사 기능이 가능합니다.
- 향후 서비스의 Event Sourcing 패턴을 위한 기반이 됩니다.

### 부정적
- 운영 복잡성이 증가합니다(Kafka 클러스터, Schema Registry,
  컨슈머 그룹 관리). Confluent Cloud 사용으로 완화합니다.
- 팀이 Kafka 개념과 패턴에 대한 교육이 필요합니다.
- 비동기 플로우에서 Eventual consistency가 Strong consistency를
  대체합니다. 일부 워크플로를 재설계해야 합니다.
- 분산 비동기 플로우 디버깅이 동기 HTTP 호출 추적보다 어렵습니다.
  분산 추적이 필요합니다(ADR-0024 참조).

### 리스크
- 메시지 볼륨이 Confluent Cloud 가격 등급을 초과하면 비용이
  크게 증가할 수 있습니다. 모니터링 및 알림 설정이 필요합니다.
- 서비스 간 스키마 변경에 규율이 필요합니다. Schema Registry와
  함께 Avro 도입을 계획합니다.

## Related Decisions

- ADR-0024: 분산 추적을 위한 OpenTelemetry 도입
- ADR-0018: 서비스 간 통신 계약 (이 ADR에 의해 대체됨)

이 ADR은 약 400단어입니다. 작성에 약 20분이 걸렸습니다. 앞으로 몇 년간 수 시간의 회의를 절약해줄 것입니다.

ADR을 언제 작성해야 하는가

모든 기술적 선택에 ADR이 필요한 것은 아닙니다. 두 JSON 라이브러리 중 하나를 선택하는 것에는 ADR이 필요 없습니다. 하지만 반드시 ADR을 작성해야 하는 결정들이 있습니다.

ADR을 작성해야 하는 경우:

시스템 구조에 영향을 미치는 결정. 서비스 간 통신 방식, 데이터 저장 위치, 컴포넌트 구성 방식을 변경하는 모든 것.
되돌리기 비용이 큰 결정. 데이터베이스, 메시징 시스템, 배포 플랫폼 선택. 이 결정을 되돌리는 데 한 스프린트 이상 걸린다면, 왜 그렇게 결정했는지 문서화하세요.
여러 가능한 옵션이 존재하는 경우. 선택이 명확하면 ADR이 필요 없습니다. 세 가지 옵션 사이에서 고민했다면, 그 이유를 기록하세요.
팀 경계를 넘는 결정. 다른 팀에 영향을 미치는 아키텍처 선택은 문서화하여 그들이 근거를 이해할 수 있도록 해야 합니다.
미래의 자신이 의문을 가질 수 있는 선택. 누군가(미래의 자신 포함)가 "왜 이렇게 했지?"라고 물을 가능성이 조금이라도 있다면, 지금 기록하세요.

ADR을 생략해도 되는 경우:

확립된 팀 표준을 따르는 선택 (예: "백엔드 서비스에는 항상 Go를 사용한다"는 각 서비스마다 새 ADR이 필요 없음)
쉽게 되돌릴 수 있는 결정 (변수명 변경, 코드 포매터 선택)
순수하게 형식적인 결정 (코드 스타일, 네이밍 컨벤션 -- 이것들은 스타일 가이드에 넣어야 함)

ADR 생애주기와 거버넌스

생애주기

ADR에는 자연스러운 생애주기가 있습니다:

Draft/Proposed: 누군가 내려야 할 결정을 식별하고 ADR 초안을 작성합니다. 팀이 논의합니다.
Accepted: 팀이 결정에 동의합니다. ADR 상태가 Accepted로 변경됩니다.
Active: 결정이 효력을 발휘합니다. ADR이 참조 문서 역할을 합니다.
Superseded: 새로운 결정이 이전 것을 대체합니다. 이전 ADR은 "Superseded by ADR-XXXX" 상태가 됩니다. 새 ADR은 이전 것을 참조합니다.
Deprecated: 결정이 더 이상 유효하지 않습니다 (해당 시스템이 폐기된 경우 등).

중요한 점: ADR을 절대 삭제하지 마세요. Deprecated되거나 Superseded된 것도 가치가 있습니다. 아키텍처 발전의 타임라인을 구성하기 때문입니다.

번호 체계

순차 번호를 사용합니다: ADR-0001, ADR-0002 등. 번호는 시간 순서를 제공하며 대화에서 ADR을 쉽게 참조할 수 있게 합니다: "ADR-42에서 결정한 바와 같이."

일부 팀은 날짜 기반 번호 체계(ADR-2026-03-27-kafka)를 사용하지만, 순차 번호가 더 간단하고 널리 사용됩니다.

검토 주기

분기별로 ADR을 검토하는 리마인더를 설정하세요:

더 이상 유효하지 않은 수락된 결정이 있는가?
가정을 무효화하는 제약 조건이 변경되었는가?
팀이 비공식적으로 내린 결정 중 기록해야 할 것이 있는가?

이 검토는 ADR의 부패를 방지하고 컬렉션을 최신 상태로 유지합니다.

ADR 저장 위치

추천 순서대로 가장 일반적인 접근 방식을 소개합니다:

코드 저장소

저장소 내 docs/adr/ 또는 docs/decisions/에 ADR을 저장합니다. 이것이 가장 인기 있는 접근 방식이며, 그럴 만한 이유가 있습니다:

ADR이 설명하는 코드와 함께 버전 관리됩니다
Pull request와 코드 리뷰에서 볼 수 있습니다
아무도 방문하지 않는 위키에서 고아가 될 수 없습니다
grep이나 검색으로 찾을 수 있습니다

규칙: ADR당 하나의 마크다운 파일, 번호와 슬러그로 명명:

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

전용 아키텍처 도구

Archyl과 같은 도구는 추가 기능과 함께 내장 ADR 관리를 제공합니다:

ADR을 C4 모델 요소(컨테이너, 컴포넌트, 관계)에 직접 연결
모든 프로젝트에 걸쳐 ADR 검색 및 필터
ADR 상태 및 생애주기 추적
ADR을 결정을 시행하는 적합성 규칙에 연결

아키텍처 도구의 핵심 장점은 맥락입니다. 개발자가 C4 다이어그램에서 PostgreSQL 컨테이너를 볼 때, PostgreSQL이 왜 선택되었는지 설명하는 ADR을 클릭하여 볼 수 있습니다. 결정과 아키텍처가 연결되어 있고, 분리되어 있지 않습니다.

위키 (권장하지 않음)

위키(Confluence, Notion 등)는 ADR이 잊혀지는 곳입니다. 코드와 분리되어 있고, 찾기 어려우며, 거의 유지보수되지 않습니다. 위키를 사용해야 한다면, 최소한 코드 저장소에서 ADR을 상호 참조하세요.

ADR을 워크플로에 통합하기

ADR을 Pull Request의 일부로 만들기

중요한 아키텍처 변경의 경우, Pull request의 일부로 ADR을 요구하세요. PR 템플릿에 섹션을 추가합니다:

## Architecture Impact

- [ ] 아키텍처 변경 없음
- [ ] ADR 생성/업데이트 완료: [링크]

이렇게 하면 ADR 작성이 일상화되고, 맥락이 흐려지기 전 결정이 내려지는 시점에 문서화가 이루어집니다.

아키텍처 리뷰에서 ADR 활용하기

아키텍처 리뷰나 설계 논의에서 기존 ADR을 참조하세요. "재설계하기 전에 ADR-15에서 왜 이 접근 방식을 선택했는지 확인해봅시다." 이렇게 하면 ADR에 가시성이 부여되고, 결정을 문서화하는 습관이 강화됩니다.

ADR을 아키텍처 다이어그램에 연결하기

ADR이 C4 모델의 특정 요소에 연결되면 진정한 위력을 발휘합니다. 탐색 가능한 지식 그래프를 만들어냅니다:

Container 다이어그램에서 Kafka 컨테이너 클릭 -> Kafka가 왜 선택되었는지 설명하는 ADR-0023 확인
PostgreSQL 데이터베이스 클릭 -> 데이터베이스 선택을 설명하는 ADR-0001 확인
API Gateway 클릭 -> 커스텀 라우팅 대신 Kong이 왜 선택되었는지 설명하는 ADR-0012 확인

Archyl에서는 ADR을 모든 C4 요소 -- 시스템, 컨테이너, 컴포넌트, 관계 -- 에 연결할 수 있습니다. 이 연결은 아키텍처 의사결정이 떠다니는 문서가 아니라, 영향을 미치는 아키텍처의 특정 부분에 고정되어 있음을 의미합니다.

자동화할 수 있는 것은 자동화하기

여러 도구가 ADR 관리의 마찰을 줄여줄 수 있습니다:

adr-tools (Nat Pryce 제작): 저장소에서 ADR을 생성하고 관리하는 명령줄 도구. adr new "Use Kafka for messaging" 실행으로 템플릿에서 새 ADR을 생성합니다.
Log4brains: ADR 마크다운 파일에서 검색 가능하고 탐색할 수 있는 웹사이트를 생성합니다.
Archyl: C4 요소 연결, 상태 추적, 프로젝트 간 검색과 함께 ADR을 관리합니다.

고급 ADR 실천법

Lightweight ADR (LADR)

일부 팀은 표준 템플릿도 너무 무겁다고 느낍니다. Lightweight ADR은 세 문장으로 구성됩니다:

[상황]의 맥락에서,
[목표]를 달성하기 위해
[결정]을 내렸으며,
[트레이드오프]를 수용합니다.

예시:

서비스 다운타임을 견디는 서비스 간 통신이 필요한 맥락에서,
서비스 분리와 이벤트 재생 기능을 달성하기 위해
Confluent Cloud를 통한 Apache Kafka를 사용하기로 결정했으며,
운영 복잡성 증가와 eventual consistency를 수용합니다.

이 형식은 문서화할 만큼 중요하지만 전체 ADR이 필요하지는 않은 결정에 적합합니다.

의사결정 로그

의사결정 로그는 모든 ADR을 시간 순서로 한 줄 요약과 함께 나열하는 단일 문서입니다. 인덱스 역할을 합니다:

#	날짜	결정	상태
23	2025-11-15	서비스 간 통신에 Kafka 사용	Accepted
24	2025-11-20	분산 추적에 OpenTelemetry 도입	Accepted
25	2025-12-01	내부 API를 REST에서 gRPC로 마이그레이션	Proposed

개별 ADR 파일을 열지 않고도 모든 결정에 대한 빠른 개요를 제공합니다.

비기술적 결정을 위한 ADR

ADR은 기술 선택에만 한정되지 않습니다. 팀은 다음과 같은 용도로도 사용합니다:

프로세스 결정: "보안 중요 코드에 페어 프로그래밍을 시행할 것이다"
조직적 결정: "플랫폼 팀이 모든 인프라 컨테이너를 담당한다"
벤더 결정: "자체 구축 대신 모니터링에 Datadog을 사용할 것이다"

결정이 중요하고 되돌리기 비용이 큰 경우, 엄밀히 "아키텍처적"인지 여부와 관계없이 ADR이 적절합니다.

흔한 실수

사후에 ADR 작성

ADR을 작성하기 가장 좋은 시점은 의사결정 과정 중입니다. 몇 주 후에 작성하면 뉘앙스, 검토했던 대안, 당시 존재했던 제약 조건을 잊게 됩니다. ADR 작성을 의사결정 과정의 일부로 만드세요, 후속 작업이 아니라.

너무 길게 작성

ADR이 한 페이지를 초과하면, 여러 결정을 문서화하고 있거나(분리하세요) 구현 세부사항을 포함하고 있을(설계 문서에 넣으세요) 가능성이 높습니다. 간결함의 규율이 명확성을 강제합니다.

기각된 대안을 문서화하지 않기

"Alternatives Considered" 섹션은 장기적으로 ADR에서 가장 가치 있는 부분입니다. 이것이 없으면, 미래 엔지니어들이 이미 평가되고 기각된 대안을 모른 채 같은 대안을 제안할 것입니다. 선택하지 않은 것과 그 이유를 항상 설명하세요.

실천을 포기하기

하나 두 개의 ADR은 큰 가치를 제공하지 않습니다. 2년에 걸쳐 축적된 50개의 ADR은 매우 귀중한 지식 기반이 됩니다. 바쁠 때 ADR 작성을 중단하고 싶은 유혹이 강합니다. 저항하세요. ADR 작성에 투자하는 15분이 나중에 몇 시간의 회의를 절약합니다.

상태를 검토하거나 업데이트하지 않기

결정의 절반이 오래된 ADR 컬렉션은 오해를 불러일으킵니다. 분기별 검토를 예약하세요. Superseded된 결정을 표시하세요. 컬렉션의 신뢰성을 유지하세요.

AI 시대에 ADR이 더 중요한 이유

AI 에이전트가 소프트웨어 개발의 적극적인 참여자가 되면서, ADR은 새로운 중요성을 갖게 됩니다. 코드를 작성하는 AI 에이전트는 ADR을 읽고 다음을 이해할 수 있습니다:

특정 기술이 선택된 이유(그리고 계속 사용해야 하는 이유)
어떤 대안이 기각되었는지(그리고 다시 제안하면 안 되는 이유)
어떤 제약이 존재하는지(규정 준수 요구사항, 성능 임계값)
어떤 트레이드오프가 수용되었는지(eventual consistency, 벤더 종속)

Archyl의 MCP 서버를 통해, Claude Code와 같은 AI 에이전트는 아키텍처 제안을 하기 전에 ADR에 접근할 수 있습니다. PostgreSQL을 사용하기로 한 이유가 이미 문서화된 서비스에 MongoDB를 제안하는 대신, 에이전트는 기존 결정을 존중합니다 -- 또는 결정을 재검토해야 한다고 생각할 때 명시적으로 표시합니다.

이로써 ADR은 인간을 위한 문서일 뿐만 아니라, AI를 위한 가드레일이 됩니다.

오늘 시작하기

팀에서 아직 ADR을 사용하지 않고 있다면, 다음 세 단계로 시작하세요:

최근 결정 하나를 선택하세요. 지난 한 달간 팀이 논의한 아키텍처 선택을 생각해보세요. 위의 템플릿을 사용하여 ADR을 작성하세요. 15-20분이면 됩니다.
저장소에 저장하세요. docs/adr/ 디렉토리를 만들고 파일을 추가하세요. 팀이 볼 수 있도록 다음 Pull request에 포함하세요.
습관으로 만드세요. PR 템플릿에 "Architecture Impact" 체크박스를 추가하세요. 다음 아키텍처 미팅에서 ADR을 논의하세요. 팀이 가치를 인식하면 실천에 탄력이 붙습니다.

누군가 "왜 그렇게 했지?"라고 물을 때 -- 그리고 반드시 물을 것입니다 -- 답을 준비해두세요.

아키텍처 문서화에 대해 더 알아보기: C4 Model이란? | ADR 모범 사례 | AI 기반 아키텍처 발견. 또는 Archyl 무료 체험으로 C4 모델에 직접 연결된 ADR을 관리하세요.

Architecture Decision Records (ADR): 완벽 가이드 - Archyl Blog