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

「왜 여기는 파일 연계인가요. 그냥 DB를 보면 되지 않나요」── 넘겨받은 시스템의 코드를 연 개발자는 거의 반드시 이런 의문에 부딪칩니다. 그리고 대부분, 답을 아는 사람은 이미 프로젝트에 없습니다.

이유는 있었을 것입니다. 상대 시스템의 DB에 직접 접속할 허가가 나지 않았을 수도 있고, 당시 납기 안에서는 그 방식만이 안전했을 수도 있습니다. 그러나 그 이유가 남아 있지 않으면, 후임은 「건드려도 되는지 알 수 없는 코드」 앞에서 손을 멈추거나, 반대로 이유까지 함께 부숩니다.

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

1. 먼저 결론

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

본문 각주가 가리키는 1차 정보는 세 가지입니다. ADR의 원형을 보인 Michael Nygard의 원전¹, 운용 원칙(추가 전용, 대상을 좁힐 것, 버전 관리 아래에 둘 것)을 정리한 Microsoft Learn의 Well-Architected Framework 가이드², 템플릿과 도구를 모은 커뮤니티 사이트 adr.github.io³입니다. 이후 각주 번호는 이 가운데 하나를 가리킵니다.

그림의 실선은 항상 성립하는 관계, 점선은 조건이 붙는 관계입니다(성립 조건은 상세 페이지의 관계별 설명에 적혀 있습니다). 관계 전체 목록(총 15건, 근거와 확신도 포함)과 주요 개념의 정의는 지식 맵 상세 페이지에 정리되어 있습니다(일본어). 데이터: JSON-LD / Turtle

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의 제안 ── 다섯 요소와 2페이지 상한

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

• 결정 하나당 파일 하나. 일련번호를 매기고, 번호는 재사용하지 않는다
• 파일은 Markdown 같은 가벼운 형식으로, 프로젝트 리포지토리 안에 둔다
• 구성은 제목/상태/컨텍스트/결정/결과(Consequences) 다섯 요소
• 상태는 제안 중(proposed)→승인됨(accepted)으로 나아가고, 뒤집을 때는 폐기(deprecated)나 대체됨(superseded)으로 한다. 옛 기록은 지우지 않는다
• 전체 1~2페이지 이내. 나중에 올 개발자와 대화하듯 읽을 수 있는, 완결된 문장으로 쓴다

상태의 움직임만 그림으로 보면, ADR이 「추가 전용 로그」라는 점이 잘 드러납니다.

stateDiagram-v2
    [*] --> proposed: ADR을 올린다
    proposed --> accepted: 리뷰에서 승인한다
    accepted --> deprecated: 결정 자체가 필요 없어졌다
    accepted --> superseded: 새 ADR이 대체했다
    deprecated --> [*]
    superseded --> [*]

어느 화살표든, 고치는 것은 상태 줄뿐입니다. 컨텍스트와 결정 본문에는 손을 대지 않습니다. accepted에서 superseded로 옮길 때 옛 ADR에 더하는 것은, 새 ADR을 가리키는 참조 한 줄뿐입니다. 과거 상태가 덮어씌워지지 않고 남으므로, 「언제·왜 방침이 바뀌었는가」를 나중에 따라갈 수 있습니다.

「아키텍처」라는 말이 붙지만, 대규모 시스템 전용 기법이 아닙니다. 오히려 전임 아키텍트도 문서화 담당자도 없는 소규모 개발에서야말로 이 「최소 양식」이 효과를 냅니다. 참고로 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을 재사용하지는 않습니다. 일련번호는 결정이 일어난 순서대로 늘어날 뿐이며, 결번이 있는 것이 보통입니다.

첫 한 건은 「ADR을 쓰기로 했다」는 ADR 자신으로 두는 것이 정석입니다. 그러면 후임은 docs/adr/만 보면 운용 규칙까지 이해합니다.

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

• 쓰는 시점은 「정한 직후」입니다. 설계 검토의 마무리로, 회의 결론을 그날 안에 ADR로 만듭니다. 뒤에서 말하지만, 모아서 나중에 쓰면 실패합니다.
• 코드 리뷰에 ADR을 넣습니다. 방식과 관련된 변경의 풀 리퀘스트에 ADR 추가·갱신이 들어 있는지만 봅니다. ADR 전용 승인 회의는 필요 없고, 리뷰의 일부로 두는 것이 소규모 팀의 현실적인 해법입니다. ADR을 버전 관리 아래에 두는 것은 Microsoft 가이드에서도 권합니다.²
• 결정을 뒤집을 때는 새 ADR을 쓰고, 옛 ADR의 상태를 Superseded로 바꿔 서로 참조합니다. 본문은 고치지 않습니다. 승인된 기록을 편집하지 않고, 대체의 연쇄로 이력을 남긴다──이것이 ADR을 「추가 전용 로그」로 다룬다는 뜻입니다.²

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

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

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

5.4 걸리는 시간의 현실감

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

6. 흔한 실패

특히 「나중에 모아서 쓴다」는, 이미 있는 시스템에 도중에 ADR을 넣을 때 빠지기 쉽습니다. 과거 결정을 모두 복원하려 하지 말고, 알고 있는 주요 결정만 거슬러 몇 건 쓰고, 나머지는 오늘 이후 결정부터 쌓는 쪽이 현실적입니다. 기존(브라운필드) 시스템이라도, 파악한 과거 결정이 있으면 거슬러 기록할 가치는 있습니다.²

7. ADR의 실제 예

소규모 Windows 업무 앱에서 흔한 소재로, 실제 ADR 전문 형태를 두 편 보입니다(내용은 일반화한 예입니다).

첫 편은 기술 선정의 정석인 데이터베이스 결정입니다.

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

## 상태

승인됨 (2026-07-17)

## 컨텍스트

본 시스템은 단일 거점의 재고 관리 데스크톱 앱이다. 이용자는 2~3명이지만,
운용상으로는 사무실 주 담당 PC 한 대에 설치하고 교대로 쓴다(동시 이용은 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에 대한 참조를 붙였다

이 두 편만 읽어도, 「이 시스템은 왜 서버 DB가 없는가」「왜 장표 코드에 Excel을 띄운 흔적이 있는가」처럼 인수인계 때 반드시 나오는 의문에 답할 수 있음을 알 수 있습니다. 합쳐도 1,500자 정도이며, 쓰는 데 1시간이 걸리지 않습니다.

8. 정리

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

관련 글

• 수탁 개발·운용 보수의 계약은 어떻게 맺어야 하는가 - IPA 「모델 거래·계약서」에서 배우는 준위임과 도급의 구분
• 위장 도급이 되지 않기 위한 준위임 계약의 올바른 일하는 방식
• Windows 앱 외주·수탁 개발을 의뢰하기 전에 정리해야 할 것
• Word 매뉴얼 작성의 기본 - 나쁜 예와 개선책

관련 상담 영역

합동회사 코무라소프트에서는, 설계 리뷰 안에서의 ADR 도입 지원, 기존 시스템의 설계 판단 정리와 문서화, 인수인계·벤더 교체를 염두에 둔 유지보수 체제 만들기를 다룹니다.

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

참고 링크

관련 기사

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

관련 토픽

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

이 주제와 연결되는 서비스

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

자주 묻는 질문

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

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

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

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

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

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

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

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

역할이 다릅니다. 설계서는 '지금 어떤 구조인가(What)'를 보여 주지만, '왜 그 구조를 골랐고 무엇을 버렸는가(Why)'는 보통 남지 않습니다. 또한 모든 것을 담은 설계서는 갱신이 멈추기 쉬워, 몇 년 뒤에는 코드와 어긋나기 쉽습니다. ADR은 결정할 때마다 수백 자를 덧붙일 뿐이므로 갱신이 멈추기 어렵고, 설계서가 낡아도 '판단의 이유'만은 살아남습니다. 소규모 개발에서는 상세 설계서를 얇게 하고 ADR을 함께 쓰는 구성이 현실적입니다.

저자 프로필

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

Go Komura

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

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