ADR(Architecture Decision Record) 입문 ── 소규모 개발에서 '왜 이런 설계로 했는가'를 남기는 최소한의 방법

“왜 여기서 파일 연계를 하는 거죠? 그냥 DB를 보면 되지 않나요?” ── 인수받은 시스템의 코드를 연 개발자는 거의 반드시 이런 종류의 의문에 부딪힙니다. 그리고 대부분의 경우, 답을 아는 사람은 이미 프로젝트에 없습니다.

이유는 분명 있었을 것입니다. 상대 시스템의 DB에 직접 접속할 허가가 나지 않았을 수도 있고, 당시 납기 안에서는 그 방식만이 안전했을 수도 있습니다. 그러나 그 이유가 남아 있지 않으면, 후임자는 “건드려도 되는지 알 수 없는 코드” 앞에서 손을 멈추거나, 반대로 이유째 부숴버리게 됩니다.

이 블로그에서는 수탁 개발을 진행하는 방법을 「Windows 앱 외주·수탁 개발을 의뢰하기 전에 정리해야 할 것」에서, 계약의 틀을 「IPA ‘모델 거래·계약서’로 배우는 준위임과 도급의 구분」에서 해설해 왔습니다. 이 글은 그다음, “만든 후 몇 년을 버티게 하는” 것을 위한 이야기입니다. 설계 판단의 이유를 최소한의 수고로 남기는 방법, ADR(Architecture Decision Record)을 소규모 수탁 개발·사내 개발을 상정하여 해설합니다.

1. 먼저 결론

• 망라적인 설계서보다 먼저 “결정의 기록”을 남겨야 합니다. 유지보수에서 정말로 곤란한 것은 “무엇을 하고 있는가”가 아니라 “왜 그렇게 했는가”를 알 수 없다는 점이기 때문입니다.
• ADR은 하나의 결정을 “제목/상태/컨텍스트/결정/결과”의 정형으로 1개 파일에 쓰는 경량 형식입니다. Michael Nygard가 2011년에 제안했으며, 1건당 1~2페이지 이내가 원칙입니다.¹
• 두는 위치는 코드와 같은 리포지토리(예: docs/adr/0001-title.md)입니다. Wiki나 공유 폴더가 아니라 코드와 함께 버전 관리하고, 코드 리뷰와 함께 봅니다.¹²
• 결정은 덮어쓰지 않습니다. 방침을 바꿀 때는 새로운 ADR을 추가하고, 기존 ADR의 상태를 Superseded(대체됨)로 바꾸어 서로 참조합니다. ADR은 추기 전용 로그입니다.²
• 무엇이든 쓰는 것이 아니라, “나중에 바꾸기 어렵다” “여러 타당한 선택지가 있었다” “제약이 결정적이었다”는 결정만을 씁니다. 명명 규칙이나 포매터 설정은 대상이 아닙니다.²
• 필자의 체감으로는 1건당 15~30분에 쓸 수 있는 분량으로 억제하는 것이 지속의 조건입니다. 무거운 템플릿은 처음 3건에서 멈춥니다.
• 수탁 개발에서 ADR은 발주 측과 공유할 수 있는 산출물이 됩니다. 검수 시 설명 자료, 담당자 교체·벤더 교체 시 인수인계 자료로 그대로 기능합니다.

본문의 각주가 가리키는 1차 정보는 3가지입니다. ADR의 원형을 제시한 Michael Nygard의 원전¹, 운용상의 원칙(추기 전용, 대상의 압축, 버전 관리 하에 두는 것)을 정리한 Microsoft Learn의 Well-Architected Framework 가이드², 템플릿과 도구를 정리한 커뮤니티 사이트 adr.github.io³입니다. 이후의 각주 번호는 이 중 하나를 가리킵니다.

2. “왜 이렇게 되어 있는지 알 수 없다”는 문제

2.1 코드는 What을 말하지만 Why는 말하지 않는다

코드를 읽으면 “무엇을 하고 있는가”는 (시간을 들이면) 알 수 있습니다. 알 수 없는 것은 다음과 같은 “왜”입니다.

• 왜 DB는 SQL Server가 아니라 SQLite인가
• 왜 다른 시스템과의 연계가 Web API가 아니라 CSV 파일 전달인가
• 왜 이 장표만 Excel을 실행해서 인쇄하고 있는가
• 왜 .NET Framework 그대로이고, 현행 .NET으로 올리지 않았는가

이런 결정에는 당시의 예산·납기·고객 측 제약·기존 자산과의 균형 같은 코드 밖에 있는 이유가 반드시 있습니다. 주석에 쓰기에는 너무 크고, 설계서에 쓰기에는 “결정의 경위”가 어울리지 않습니다. 결과적으로 이유는 어디에도 남지 않습니다.

2.2 결정의 보관 장소는, 몇 년이면 사라지는 것뿐

그렇다면 실제로 설계 판단의 이유는 지금 어디에 있을까요? 흔한 보관 장소를 비교해 보겠습니다.

Microsoft의 아키텍트 가이드에서도 기록되지 않은 결정은 잊히고, 같은 논의의 재연이나 당초 의도에 반하는 변경을 초래한다고 명확히 지적하고 있습니다.²

2.3 수탁 개발에서는 계약의 끊김이 기억의 끊김이 된다

자사 개발이라면 “그 사람에게 물어보면 안다”가 한동안 통용되지만, 수탁 개발에서는 담당자의 이동·퇴사에 더해 벤더 교체가 있습니다. 개발한 벤더와 유지보수하는 벤더가 달라지는 순간, 구두와 채팅에 있던 “왜”는 완전히 사라집니다.

계약 관점에서 보아도, 개발과 유지보수가 별도 계약·별도 공정이 되는 것은 흔한 일입니다(이 구조는 「IPA ‘모델 거래·계약서’ 해설 글」에서 다루었습니다). 또한 「준위임 계약의 올바른 업무 방식」에서 정리한 대로, 준위임에서는 수탁 측이 자율적으로 업무를 진행하기 때문에 무엇을 어떻게 판단했는지를 발주 측에 보여줄 수 있는 기록이 신뢰의 뒷받침이 됩니다. ADR은 이 두 가지 모두에 효과가 있습니다.

3. ADR이란 무엇인가

3.1 Nygard의 제안 ── 5가지 요소와 2페이지 상한

ADR은 Michael Nygard가 2011년 블로그 글 “Documenting Architecture Decisions”에서 제안한 형식입니다.¹ 요점은 다음과 같습니다.

• 하나의 결정에 하나의 파일. 일련번호를 붙이고, 번호는 재사용하지 않음
• 파일은 Markdown 등 경량 형식으로, 프로젝트 리포지토리 내에 둠
• 구성은 제목/상태/컨텍스트/결정/결과(Consequences)의 5요소
• 상태는 제안중(proposed) → 승인됨(accepted)으로 진행하고, 뒤집을 때는 폐기(deprecated)나 대체됨(superseded)으로 함. 과거 기록은 지우지 않음
• 전체 1~2페이지 이내. 미래의 개발자가 대화하듯 읽을 수 있도록, 완결된 글로 씀

상태의 움직임만 도식화하면, ADR이 “추기 전용 로그”라는 것을 알기 쉬워집니다.

stateDiagram-v2
    [*] --> proposed: ADR을 기안한다
    proposed --> accepted: 리뷰에서 승인한다
    accepted --> deprecated: 결정 자체가 불필요해졌다
    accepted --> superseded: 새로운 ADR이 대체했다
    deprecated --> [*]
    superseded --> [*]

어느 화살표든, 다시 쓰는 것은 상태 줄뿐입니다. 컨텍스트와 결정 본문에는 손을 대지 않습니다. accepted에서 superseded로 옮길 때 기존 ADR에 추가하는 것은 새 ADR에 대한 참조 1줄뿐입니다. 과거 상태가 덮어써지지 않고 남기 때문에 “언제·왜 방침이 바뀌었는가”를 나중에 추적할 수 있습니다.

“아키텍처”라는 이름이 붙어 있지만 대규모 시스템 전용 기법은 아닙니다. 오히려 전임 아키텍트도 문서화 담당자도 없는 소규모 개발에서야말로 이 “최소한의 정형”이 효과를 냅니다. 참고로 ADR의 템플릿과 도구는 커뮤니티 사이트(adr.github.io)에 체계적으로 정리되어 있어, “아키텍처상 중요한 결정을, 근거와 트레이드오프와 함께 기록한다”는 사고방식의 입구로 참고할 수 있습니다.³

3.2 Markdown 템플릿

필자가 소규모 프로젝트에서 사용하고 있는, Nygard 형식 그대로의 최소 템플릿입니다.

# ADR-NNNN: (결정 내용을 짧은 한 문장으로)

## 상태

제안중 | 승인됨 | 폐기 | 대체됨(→ ADR-MMMM)

## 컨텍스트

왜 이 결정이 필요해졌는가. 기술적·업무적 전제,
제약(예산·납기·기존 자산·고객 환경), 검토한 선택지를,
당시 상황을 모르는 독자도 알 수 있게 쓴다.

## 결정

"~한다"라고 능동태로 단언한다. 1~3문장.

## 결과

이 결정으로 좋아지는 점·나빠지는 점(트레이드오프)을 모두 쓴다.
앞으로 이 결정을 재검토할 계기가 될 조건이 있으면 쓴다.

상태 칸은 상태만 써도 무방하지만, 승인됨 (2026-07-17)처럼 상태를 바꾼 날짜를 함께 적는 방식을 권장합니다. 7장의 실례도 이 형태로 되어 있습니다. 추기 전용 로그로 사용하는 이상, “언제 승인되었는가” “언제 대체되었는가”는 본문과 마찬가지로 중요한 정보이기 때문입니다. 대체됨으로 바꿀 때는 대체됨 (2026-08-20) ── ADR-0007이 대체함처럼 날짜와 대체 대상을 한 줄에 넣습니다. 프로젝트 내에서 어느 쪽으로 쓸지 통일해 두세요.

포인트는 “결과”에 나쁜 점도 쓴다는 것입니다. 트레이드오프가 없는 결정은 기록할 가치가 거의 없습니다. Microsoft의 가이드에서도 결정의 결과를 의도적으로든 우발적으로든 숨기지 않을 것, 근거 없는 기록은 시간이 지나면서 가치를 잃는다는 점을 강조하고 있습니다.²

4. ADR에 무엇을 쓰고, 쓰지 않는가

ADR이 지속되지 않는 가장 큰 원인은 “무엇이든 쓰려고 하는 것”입니다. Microsoft의 가이드에서는 기록하는 것을 시스템 구조나 중요한 품질 특성에 영향을 미치는 것, 되돌리기 어려운 것으로 한정하고 있습니다.² 이를 일상의 판단에 적용하면 다음 표가 됩니다.

판단이 애매할 때의 기준은 하나, “1년 후에 이 코드를 본 사람(자기 자신을 포함)이 ‘왜?’라고 묻고 싶어질까”입니다. 묻고 싶어질 것 같으면 쓰고, 코드나 설정을 보면 자명하다면 쓰지 않습니다.

또 하나의 함정은, 쓸 범위를 “문서 종류”로 생각해버리는 것입니다. 다음과 같이 역할 분담을 정해두면 헷갈리지 않습니다.

5. 소규모 수탁에서의 운용

5.1 디렉터리와 파일명

리포지토리 바로 아래에 docs/adr/를 만들고, 일련번호+짧은 슬러그로 둡니다. 슬러그(slug)란 내용을 짧게 나타낸 영문 소문자와 하이픈만으로 된 문자열입니다(use-sqlite-for-local-storage 같은 형태). 파일명이나 URL의 일부로 쓰이기 때문에, 공백·일본어·기호를 피하고 기계적으로 다룰 수 있는 형태로 해둔다는 약속입니다.

docs/
  adr/
    0001-record-architecture-decisions.md
    0002-use-sqlite-for-local-storage.md
    0003-excel-report-via-com-automation.md
    0007-excel-report-via-openxml-library.md

이 예에서 0004~0006이 빠져 있는 것은, 그 번호들이 다른 결정(인증 방식이나 로그 설계 등)에 쓰이고 있기 때문입니다. 0007은 0003의 방식을 대체한 결정이지만, 번호를 채우거나 0003을 재사용하지는 않습니다. 일련번호는 결정이 일어난 순서대로 늘어나기만 하는 것으로, 결번이 있는 것이 정상 상태입니다.

첫 번째 1건은 “ADR을 사용하기로 했다”는 ADR 자신으로 하는 것이 정석입니다. 이렇게 하면 후임자는 docs/adr/를 보기만 하면 운용 규칙까지 이해할 수 있습니다.

5.2 언제 쓰고, 누가 리뷰하는가

• 쓰는 시점은 “결정한 직후”입니다. 설계 검토를 마무리하며 회의의 결론을 그날 안에 ADR로 만듭니다. 뒤에서 다루지만, 모아서 나중에 쓰는 것은 실패합니다.
• 코드 리뷰에 ADR을 포함시킵니다. 방식과 관련된 변경의 풀 리퀘스트에 ADR 추가·갱신이 포함되어 있는지를 보는, 그것뿐입니다. ADR 전용 승인 회의는 필요 없으며, 리뷰의 일부로 삼는 것이 소규모 팀의 현실적인 해법입니다. ADR을 버전 관리 하에 두는 것은 Microsoft의 가이드에서도 권장하고 있습니다.²
• 결정을 뒤집을 때는 새로운 ADR을 쓰고, 기존 ADR의 상태를 Superseded로 바꾸어 서로 참조합니다. 본문은 다시 쓰지 않습니다. 승인된 기록을 편집하지 않고 대체의 연쇄로 이력을 유지하는 것 ── 이것이 ADR을 “추기 전용 로그”로 다룬다는 의미입니다.²

5.3 발주 측과 공유하는 산출물로서의 ADR

수탁 개발에서는 ADR을 납품물의 일부로 발주 측과 공유할 것을 권합니다. 효과는 3가지입니다.

1. 검수·설명 자료가 됩니다. “왜 이런 구성인가”를 말로 설명하는 대신 ADR을 보여주면 됩니다. 제약(예산·납기·환경)이 결정적이었던 결정은 발주 측 자신이 당사자이므로, 기록이 있으면 이후의 인식 차이를 막을 수 있습니다.
2. 벤더 교체에 대한 보험이 됩니다. 발주 측 입장에서는 다음 벤더에게 넘길 수 있는 “판단의 이력”이 있는지 여부에 따라 인수인계 비용과 리스크가 크게 달라집니다. 발주 전 정리에 대해서는 「Windows 앱의 수탁 개발 가이드」에서 쓴 대로지만, 납품 후에 남는 문서로 무엇을 받을지를 계약 시점에 정해둘 때 ADR은 비용 대비 효과가 가장 높은 부류입니다.
3. 준위임의 보고와 궁합이 좋습니다. 준위임 계약에서는 업무 수행 보고가 요구되는데, 설계 단계의 보고에 ADR을 그대로 사용할 수 있습니다.

5.4 걸리는 시간의 현실감

필자의 경험으로는, 템플릿에 따라 1건 쓰는 데 15~30분입니다. 결정의 빈도는 소규모 프로젝트라면 월 몇 건 정도이므로, 월 1~2시간의 투자로 “왜”가 전부 남습니다. 몇 년 후의 조사·재검토·인수인계에서 사라지는 시간과 비교하면, 수지가 맞지 않는 현장은 거의 없습니다.

6. 흔한 실패

특히 “나중에 모아서 쓴다”는 기존 시스템에 도중부터 ADR을 도입할 때 빠지기 쉬운 함정입니다. 과거의 결정을 모두 복원하려 하지 말고, 알고 있는 주요 결정만 소급해서 몇 건 쓰고, 나머지는 오늘 이후의 결정부터 쌓아가는 것이 현실적입니다. 기존(브라운필드) 시스템이라도 파악하고 있는 과거의 결정이 있다면 소급해서 기록할 가치는 있습니다.²

7. ADR의 실례

소규모 Windows 업무 앱에서 흔히 나오는 소재로, 실제 ADR 전문 형태를 2건 보여드립니다(내용은 일반화한 예시입니다).

첫 번째는 기술 선정의 정석인 데이터베이스 결정입니다.

# ADR-0002: 업무 데이터의 저장소는 SQLite로 한다

## 상태

승인됨 (2026-07-17)

## 컨텍스트

본 시스템은 1개 거점의 재고 관리 데스크톱 앱이다. 사용자는 2~3명이지만,
운용상으로는 사무실 주 담당 PC 1대에 설치하고 교대로 사용한다(동시 이용은 1명).
고객사 내부에 DB 서버를 운용할 수 있는 담당자가 없고, 서버기 도입 예산도 없다.
데이터양은 10년 운용해도 수백 MB 정도로 예상된다.
선택지로 SQL Server Express / SQLite / Access 파일(.accdb)을 검토했다.
SQL Server Express는 서버 구축과 Windows Update 후의 동작 확인을
지속적으로 수행할 수 있는 체제가 고객 측에 없어 보류했다. Access는
동시 갱신 시의 손상 위험과 향후 이전 가능성을 고려해 보류했다.

## 결정

데이터 저장에는 SQLite를 채택한다. DB 파일은 공유 폴더에 두지 않고
주 담당 PC의 로컬에 둔다. 백업은 매일 VACUUM INTO로
스냅숏을 생성하여 NAS에 저장한다(가동 중인 원본 파일 복사는
WAL 파일의 미반영분 누락이나 쓰기 경합으로 손상된 백업이 되므로 불가).

## 결과

- 좋은 점: DB 서버 구축·유지보수가 불필요. 백업도 SQL 한 문장으로 끝난다
- 좋은 점: 앱 배포 시 런타임을 동봉할 수 있어 설치가 단순해진다
- 나쁜 점: 쓰기가 DB 단위 잠금이 되므로 다거점·다인원으로는 확장할 수 없다
- 나쁜 점: 나중에 서버 DB로 옮길 경우 데이터 이전과 연결 계층 개수가 필요하다
- 여러 PC에서의 동시 이용이 필요해진 시점에 이 결정을 재검토한다(그 경우 서버 DB 또는 API 경유 구성이 된다)

이 예에 나오는 SQLite 고유 용어만 보충합니다. VACUUM INTO는 가동 중인 데이터베이스의 논리적 내용을 그대로 다른 파일로 써내는 SQL 문으로, SQLite 공식 문서에서도 “가동 중인 데이터베이스의 백업을 만드는, 백업 API의 대안”으로 자리매김되어 있습니다.⁴ WAL(Write-Ahead Logging)은 갱신 내용을 일단 본체와는 별도의 -wal 파일에 쓴 다음 반영하는 저널 방식입니다. 이 방식일 때 가동 중에 본체 .db 파일만 OS의 파일 복사로 반출하면, -wal 쪽에 있는 미반영 갱신이 빠져 어중간한 백업이 됩니다. ADR-0002의 “결정”이 굳이 백업 방법까지 적고 있는 것은, 이 함정이 결정과 불가분이기 때문입니다.

두 번째는 한 번 내린 결정을 뒤집는 예입니다. Superseded 사용법도 함께 살펴보십시오.

# ADR-0007: 장표의 Excel 출력은 COM 연계가 아니라 라이브러리 생성으로 한다

## 상태

승인됨 (2026-07-17) ── ADR-0003(COM 오토메이션 채택)을 대체함

## 컨텍스트

납품서와 월간 집계를 Excel 파일로 출력하는 요건이 있다.
당초에는 ADR-0003대로 Excel의 COM 오토메이션으로 구현했지만,
무인 실행하는 야간 배치에서 Excel 프로세스가 잔류하여 처리가 멈추는
현상이 반복적으로 발생했고, 실행용 PC에 Office 라이선스가 필요한 점도
단말 갱신 때마다 문제가 되었다.
선택지로 COM 연계 지속(프로세스 감시 추가) /
Open XML 형식을 직접 생성하는 라이브러리로의 전환 /
장표의 PDF화(사양 변경)를 검토했다. PDF화는 거래처가
Excel에서의 추가 기입을 전제로 하고 있어 불가했다.

## 결정

장표는 .xlsx를 라이브러리로 직접 생성하는 방식으로 전환한다.
Excel 본체에는 의존하지 않는다. 서식은 템플릿 .xlsx로
리포지토리에 포함시키고, 셀 삽입으로 생성한다.

## 결과

- 좋은 점: 실행 환경에 Excel이 불필요해져 무인 실행이 안정된다
- 좋은 점: 프로세스 잔류 문제가 구조적으로 사라진다
- 나쁜 점: Excel의 모든 기능을 쓸 수 없어 기존 장표 일부 서식은 단순화가 필요하다
- 나쁜 점: 기존 장표의 템플릿화에 개수 공수가 든다
- ADR-0003은 Superseded로 하고 본 ADR에 대한 참조를 붙였다

이 2건을 읽는 것만으로 “이 시스템은 왜 서버 DB가 없는가” “왜 장표 코드에 Excel 실행의 흔적이 있는가” 같은, 인수인계 시 반드시 나오는 의문에 답할 수 있다는 것을 알 수 있을 것입니다. 합쳐도 1,500자 정도이며, 쓰는 데 1시간이 걸리지 않습니다.

8. 정리

• 유지보수·인수인계에서 사라져 곤란한 것은 What이 아니라 Why입니다. 기록되지 않은 결정은 잊히고, 논의의 재연과 의도에 반하는 변경을 초래합니다.²
• ADR은 1결정=1파일, 5요소, 1~2페이지 이내의 경량 기록 형식입니다. Nygard의 원형 그대로 소규모 개발에 바로 쓸 수 있습니다.¹
• 쓰는 것은 “바꾸기 어렵다” “선택지가 있었다” “제약이 결정적이었다”는 결정뿐입니다. 규약이나 포맷은 자동화에 맡기고 ADR의 대상으로 삼지 않습니다.²
• 두는 곳은 docs/adr/, 리뷰는 풀 리퀘스트와 함께. 결정은 덮어쓰지 않고 Superseded로 대체하여 이력을 불변으로 유지합니다.¹²
• 수탁 개발에서 ADR은 검수 설명 자료·벤더 교체 시 인수인계 자료로서 발주 측에도 가치 있는 납품물이 됩니다.
• 1건 15~30분. 먼저 다음 설계 판단부터 1건 써보는 것, 기존 시스템이라면 알고 있는 주요 결정을 몇 건만 소급해서 쓰는 것부터 시작하십시오.

관련 글

• 수탁 개발·운용 보수의 계약은 어떻게 맺어야 하는가 ── IPA 「모델 거래·계약서」에서 배우는 준위임과 도급의 구분
• 위장 도급이 되지 않기 위한 준위임 계약의 올바른 업무 방식 ── 계약서의 이름이 아니라 「지휘명령」으로 정해진다
• Windows 앱 외주·수탁 개발을 의뢰하기 전에 정리해야 할 것
• 매뉴얼 제작에서 먼저 맞춰야 할 Word의 기본 - 나쁜 패턴과 베스트 프랙티스를 나란히 정리

관련 상담 영역

합동회사 코무라소프트에서는 설계 리뷰 안에서의 ADR 도입 지원, 기존 시스템의 설계 판단 정리와 문서화, 인수인계·벤더 교체를 대비한 유지보수 체제 구축을 다루고 있습니다.

• 기술 상담·설계 리뷰
• Windows 앱 개발
• 기존 Windows 소프트웨어의 개수·유지보수
• 문의하기

참고 링크

관련 기사

같은 태그를 공유하는 최신 기사입니다. 더 가까운 주제로 지식을 넓힐 수 있습니다.

관련 토픽

이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.

이 주제와 연결되는 서비스

이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.

자주 묻는 질문

이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.

ADR(Architecture Decision Record)이란 무엇인가요?

소프트웨어 구조에 관한 하나의 결정을, '제목/상태/컨텍스트/결정/결과'라는 짧은 정형으로 1개 파일에 기록하는 문서입니다. Michael Nygard가 2011년에 제안한 경량 형식으로, 1건당 1~2페이지 이내로 정리하고 코드와 같은 리포지토리에 Markdown으로 커밋하는 것이 기본입니다. 망라적인 설계서와 달리 '왜 그 선택을 했는가'와 '버린 선택지'를 남기는 데 특화되어 있습니다.

ADR에는 무엇을 쓰고, 무엇을 쓰지 않아도 되나요?

써야 하는 것은 나중에 바꾸기 어려운 결정(데이터베이스나 통신 방식 선정, 외부 연계 형식 등), 여러 타당한 선택지 중에서 고른 결정, 예산·납기·기존 자산 같은 제약이 결정적이었던 결정입니다. 반대로 명명 규칙이나 포매터 설정처럼 도구나 규약으로 기계적으로 통일할 수 있는 것, 변경이 쉬워서 코드를 읽으면 충분한 것은 쓸 필요가 없습니다. 판단이 애매할 때는 '1년 후의 내가 왜?라고 묻고 싶어질까'를 기준으로 삼습니다.

결정을 바꾸고 싶어지면 과거의 ADR을 다시 써도 되나요?

다시 쓰지 않고, 새로운 ADR을 추가해서 대체합니다. 기존 ADR은 상태를 Superseded(대체됨)로 바꾸고 새 ADR에 대한 참조를 붙이되, 본문은 그대로 남깁니다. Microsoft의 가이드에서도 ADR은 추기 전용 로그로 다루고 승인된 기록을 나중에 편집하지 않는 것을 권장합니다. 이렇게 하면 '언제·왜 방침이 바뀌었는가'라는 이력 자체가 인수인계 자료가 됩니다.

설계서가 있으면 ADR은 필요 없지 않나요?

역할이 다릅니다. 설계서는 '현재 어떤 구조인가(What)'를 보여주지만, '왜 그 구조를 선택했고 무엇을 버렸는가(Why)'는 보통 남지 않습니다. 또한 망라적인 설계서는 갱신이 멈추기 쉬워 수년 후에는 코드와 어긋나는 경우가 많습니다. ADR은 결정할 때마다 수백 자를 추가하는 것뿐이라 갱신이 멈추기 어렵고, 설계서가 낡아도 '판단의 이유'만은 살아남습니다. 소규모 개발에서는 상세 설계서를 얇게 하고 ADR을 병용하는 구성이 현실적입니다.

저자 프로필

기사 저자의 프로필 페이지입니다.

Go Komura

합동회사 코무라소프트 대표

Windows 소프트웨어 개발, 기술 상담, 장애 조사를 중심으로 재현이 어려운 장애 조사와 기존 자산이 남아 있는 프로젝트에 강점이 있습니다.