아키텍처 결정 기록 (ADR)
AI 에이전트가 코드베이스의 과거 설계 결정, 검토한 대안, 트레이드오프를 이해하도록 ADR을 구조화하고 유지하는 실무 방법과 팀 운영 규칙을 정리합니다.
핵심 요약
- 코드가 설명하지 못하는 "왜 그렇게 결정했는가"를 ADR에 기록하면 AI가 맥락에 맞는 제안을 합니다.
- frontmatter의
status(accepted/deprecated/superseded)와date만 보고도 AI가 유효한 결정인지 빠르게 가려냅니다. - 검토한 대안과 기각 이유를 남겨두면 AI가 이미 버린 대안을 다시 꺼내지 않습니다.
- MADR 포맷으로 컨텍스트·결정·결과·대안을 구조화하고
docs/adr/에NNNN-제목.md로 저장합니다. - 관련 코드에
// See ADR-0003주석을 달아 결정과 구현을 연결합니다.
코드는 무엇을 구현했는지는 보여주지만, 왜 그렇게 결정했는지는 알려주지 않습니다. 그 빈자리를 ADR(Architecture Decision Record)이 채웁니다. AI 에이전트가 코드베이스의 맥락을 이해하려면 꼭 필요한 문서입니다.
왜 ADR이 AI 시대에 중요한가
AI 에이전트가 리팩토링이나 기능 추가를 할 때 과거 결정의 이유를 모르면 이렇게 됩니다.
- 이미 검토하고 기각한 대안을 다시 제안합니다
- 의도적인 설계를 "문제"로 보고 바꾸려 듭니다
- 기술 부채와 의도한 트레이드오프를 구별하지 못합니다
ADR이 있으면 AI는 "이 구조가 왜 이런지" 이해하고 맥락에 맞는 제안을 합니다.
구조화된 ADR 포맷
MADR(Markdown Any Decision Records) 기반
---
status: accepted | deprecated | superseded
date: 2026-03-20
decision-makers: [이름들]
---
# [번호]. [결정 제목]
## 상태
[Accepted / Deprecated / Superseded by ADR-XXX]
## 컨텍스트
[이 결정이 필요해진 배경과 제약조건]
## 결정
[내린 결정과 그 이유]
## 결과
[이 결정의 긍정적/부정적 영향]
## 검토한 대안
### 대안 1: [이름]
- 장점: ...
- 단점: ...
- 기각 이유: ...frontmatter가 핵심
ADR의 frontmatter(status, date)가 있어야 AI가 유효한 결정인지 빠르게 판단합니다.
deprecated나 superseded 상태의 ADR은 참고만 하고 따르지 않습니다.
Before/After
Before — Confluence 위키에 산재된 결정:
[2024-01-15 회의록]
...중략...
DB는 PostgreSQL로 가기로 했음.
MongoDB도 고려했는데 트랜잭션 때문에 안 됨.After — 코드 옆의 구조화된 ADR:
---
status: accepted
date: 2024-01-15
---
# 3. PostgreSQL을 기본 데이터베이스로 선택
## 컨텍스트
결제 시스템에서 ACID 트랜잭션이 필수적이며,
복잡한 조인 쿼리가 빈번하게 발생한다.
## 결정
PostgreSQL을 기본 데이터베이스로 사용한다.
## 결과
- 트랜잭션 안정성 확보
- 복잡한 쿼리 성능 우수
- NoSQL 대비 스키마 변경 비용 높음 (마이그레이션 필요)
## 검토한 대안
### MongoDB
- 장점: 스키마 유연성, 빠른 초기 개발
- 단점: 멀티 문서 트랜잭션 성능 불안정
- 기각 이유: 결제 시스템의 ACID 요구사항 미충족ADR 관리 전략
| 항목 | 권장 |
|---|---|
| 저장 위치 | docs/decisions/ 또는 docs/adr/ |
| 파일명 | NNNN-제목.md (예: 0003-use-postgresql.md) |
| 상태 관리 | frontmatter의 status 필드로 |
| 연결 | 관련 코드에 // See ADR-0003 주석 |
| 검색 | 코드 리뷰 시 관련 ADR 링크 첨부 |
템플릿
---
status: proposed
date: [YYYY-MM-DD]
decision-makers: [이름]
---
# [번호]. [결정 제목]
## 상태
Proposed
## 컨텍스트
[배경, 제약조건, 동기]
## 결정
[내린 결정]
이유:
- [이유 1]
- [이유 2]
## 결과
긍정적:
- [영향 1]
부정적:
- [트레이드오프 1]
## 검토한 대안
### [대안 이름]
- 장점: ...
- 단점: ...
- 기각 이유: ...AI가 실패하는 패턴
| 실수 | AI가 실패하는 이유 | 수정 방법 |
|---|---|---|
| ADR 없이 코드만 제공 | AI가 "왜 이렇게 했는지" 모르고 리팩토링 제안 | 주요 결정마다 ADR 작성 |
| status 필드 없음 | AI가 폐기된 결정을 현행으로 착각 | frontmatter에 status 필수 |
| 대안과 기각 이유 생략 | AI가 이미 검토된 대안을 다시 제안 | 검토한 대안을 반드시 기록 |
AI 프롬프트 예시
다음 아키텍처 결정에 대한 ADR을 작성해줘.
결정: [결정 내용]
배경: [왜 이 결정이 필요했는지]
검토한 대안: [대안 목록]
MADR 포맷으로 작성하고, frontmatter에 status와 date를 포함해줘.
각 대안의 장단점과 기각 이유를 구체적으로 적어줘.체크리스트
| 항목 | 확인 |
|---|---|
| ADR에 frontmatter(status, date)가 있는가 | ☐ |
| 컨텍스트가 "왜 필요했는지" 설명하는가 | ☐ |
| 검토한 대안과 기각 이유가 있는가 | ☐ |
| 결과(트레이드오프)가 명시되어 있는가 | ☐ |
| 관련 코드에 ADR 참조 주석이 있는가 | ☐ |
| deprecated된 ADR의 status가 갱신되었는가 | ☐ |