🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

마틴 파울러는 ADR을 제품이나 생태계에 중요한 단일 아키텍처 결정을 짧게 기록해, 결정의 맥락·근거·영향을 남기고 이후 변경은 새 기록으로 연결하는 실천이라고 설명한다.

📌 핵심 요약

• Architecture Decision Record(ADR)는 제품이나 생태계에 관련된 하나의 결정을 짧게 포착하고 설명하는 문서로, 결정 자체와 그 배경, 중요한 파급효과를 담는다.
• ADR은 훗날 사람들이 시스템이 왜 현재와 같은 모습이 되었는지 이해하게 해 주는 기록이며, 작성 과정 자체가 특히 여러 사람이 함께 사고를 정리하고 관점을 드러내는 데 도움을 준다.
• ADR은 중요한 내용을 앞에 두고 세부 사항을 뒤로 미루는 역피라미드 방식으로 쓰며, 보통 코드 저장소의 doc/adr 같은 위치에 마크다운 등 가벼운 형식으로 보관하는 것이 권장된다.
• 각 ADR은 별도 파일로 만들고 단조 증가 번호와 결정 내용을 드러내는 이름을 붙이며, proposed, accepted, superseded 같은 상태를 통해 논의 중인지, 유효한지, 대체되었는지를 명확히 한다.
• 좋은 ADR은 결정뿐 아니라 문제, 고려한 절충, 진지하게 검토한 대안과 장단점, 결과, 확신 수준, 재검토 조건을 짧게 담아야 하며, 소프트웨어 아키텍처를 넘어 다른 의사결정 기록에도 응용될 수 있다.

🧩 주요 포인트

1. Architecture Decision Record(ADR)는 제품이나 생태계에 관련된 하나의 결정을 짧게 포착하고 설명하는 문서로, 결정 자체와 그 배경, 중요한 파급효과를 담는다.
2. ADR은 훗날 사람들이 시스템이 왜 현재와 같은 모습이 되었는지 이해하게 해 주는 기록이며, 작성 과정 자체가 특히 여러 사람이 함께 사고를 정리하고 관점을 드러내는 데 도움을 준다.
3. ADR은 중요한 내용을 앞에 두고 세부 사항을 뒤로 미루는 역피라미드 방식으로 쓰며, 보통 코드 저장소의 doc/adr 같은 위치에 마크다운 등 가벼운 형식으로 보관하는 것이 권장된다.
4. 각 ADR은 별도 파일로 만들고 단조 증가 번호와 결정 내용을 드러내는 이름을 붙이며, proposed, accepted, superseded 같은 상태를 통해 논의 중인지, 유효한지, 대체되었는지를 명확히 한다.
5. 좋은 ADR은 결정뿐 아니라 문제, 고려한 절충, 진지하게 검토한 대안과 장단점, 결과, 확신 수준, 재검토 조건을 짧게 담아야 하며, 소프트웨어 아키텍처를 넘어 다른 의사결정 기록에도 응용될 수 있다.

🧠 상세 정리

1. ADR의 정의와 기본 원칙

ADR은 Architecture Decision Record의 약자로, 제품이나 더 넓은 생태계에 중요한 단일 결정을 기록하고 설명하는 짧은 문서다. 문서는 몇 쪽 이내로 짧아야 하며, 결정 내용과 그 결정을 내리게 된 맥락, 그리고 중요한 결과나 파급효과를 포함해야 한다. 핵심은 방대한 설계 문서가 아니라 특정 결정 하나를 명료하게 남기는 것이다. 결정이 나중에 바뀌더라도 기존 ADR을 고쳐 쓰는 방식이 아니라, 그것을 대체하는 새 ADR에 연결해 의사결정의 흐름을 보존한다.

2. 기록 이상의 가치: 사고 정리와 합의 형성

파울러는 ADR 작성의 목적을 두 가지로 설명한다. 첫째, ADR은 몇 달 또는 몇 년 뒤 사람들이 시스템이 왜 그렇게 만들어졌는지 이해할 수 있게 하는 결정의 기록이다. 둘째, 그리고 더 중요할 수 있는 점은 ADR을 쓰는 행위 자체가 사고를 명료하게 만든다는 것이다. 특히 여러 사람이 함께 일할 때 문서를 작성하면 서로 다른 관점이 드러나고, 그 차이가 논의되며, 가능하다면 해결되는 과정이 생긴다. 따라서 ADR은 결과 문서이면서 동시에 협업을 촉진하는 도구다.

3. 작성 방식과 저장 위치

ADR은 뉴스 기사에서 흔히 쓰는 역피라미드 방식처럼 가장 중요한 내용을 앞에 두고 세부 정보는 뒤로 보내는 구성이 권장된다. 일반적으로 해당 코드베이스의 소스 저장소 안에 ADR을 두며, 위치로는 doc/adr 같은 디렉터리가 자주 사용된다. 이렇게 하면 코드베이스에서 일하는 사람들이 쉽게 접근할 수 있고, 마크다운 같은 가벼운 마크업 언어를 사용하면 코드처럼 읽고 비교하기도 쉽다. 필요하다면 빌드 작업을 통해 제품 팀 웹사이트에 게시할 수도 있다. 다만 단일 코드베이스를 넘어서는 생태계 수준의 ADR에는 제품 저장소 보관 방식이 맞지 않을 수 있고, 비개발자가 git 기반 문서 작업을 어렵게 느낄 수도 있다.

4. 파일 구성과 상태 관리

각 ADR은 독립된 파일이어야 하며, 파일명에는 단조 증가하는 번호와 결정을 드러내는 이름을 포함하는 것이 좋다. 예를 들어 0001-HTMX-for-active-web-pages처럼 작성하면 디렉터리 목록만 보아도 어떤 결정들이 있었는지 읽기 쉬워진다. ADR에는 상태가 필요하며, 논의 중이면 proposed, 팀이 수용해 현재 유효하면 accepted, 중대하게 수정되거나 다른 결정으로 대체되면 superseded로 표시한다. accepted 상태의 ADR은 다시 열어 수정하지 않고, 변경이 필요하면 대체 ADR을 만들고 링크한다. 이 방식은 어떤 결정이 언제부터 언제까지 작업을 지배했는지 명확한 기록으로 남긴다.

5. 근거, 대안, 결과, 확신 수준

ADR은 결정만 담는 문서가 아니라 그 결정에 이른 간단한 근거도 함께 담아야 한다. 여기에는 어떤 문제가 이 결정을 필요하게 했는지, 어떤 절충을 고려했는지, 그리고 진지하게 검토한 대안들의 장단점이 포함된다. 파울러는 패턴을 작성할 때 말하는 forces의 개념처럼, 결정에 작용한 힘과 제약을 생각하는 방식이 유용하다고 설명한다. 또한 모든 결정에는 결과가 있으므로, 그것이 근거에서 자연스럽게 드러나지 않는다면 명시적인 섹션으로 적는 것이 좋다. 불확실성 아래 내려지는 결정이 많기 때문에 확신 수준과, 어떤 제품 맥락의 변화가 재평가를 촉발해야 하는지도 기록할 수 있다.

6. Advice Process와 더 넓은 활용

ADR은 Advice Process에서 중심적인 역할을 할 수 있다. 이 경우 ADR은 단지 결정을 기록하는 문서가 아니라, 전문성을 끌어내고 정렬을 만드는 작성 행위 자체로 활용된다. ADR을 만들며 수집한 조언도 포함할 수 있지만, 문서를 짧게 유지하기 위해 ADR에는 요약만 담고 전체 조언 기록은 별도로 두는 편이 나을 수 있다. 파울러가 강조하는 가장 중요한 원칙은 간결함이며, 보통 한 페이지 정도로 짧고 핵심에 집중해야 한다. 지원 자료가 있다면 본문에 길게 넣기보다 링크하는 것이 좋다. ADR은 소프트웨어 아키텍처의 의사결정 기록 형식이지만, 짧은 결정 기록이라는 더 넓은 개념은 다른 맥락에서도 유용한 역사적 기록이 될 수 있다.

🧾 핵심 주장 / 시사점

• ADR의 핵심은 완벽한 설계 문서를 만드는 것이 아니라, 특정 시점의 결정과 그 이유를 짧고 추적 가능한 형태로 남기는 데 있다.
• 기존 ADR을 수정하지 않고 대체 ADR로 연결하는 규칙은 의사결정의 변경 이력과 적용 기간을 보존하는 데 중요하다.
• ADR 작성 과정은 문서화 이상의 협업 효과를 가지며, 서로 다른 관점을 드러내고 논의하게 만들어 팀의 정렬을 돕는다.

✅ 액션 아이템

• 중요한 아키텍처 결정 하나씩을 ADR로 단일 기록하고 맥락·근거·파급효과를 짧게 남겨 향후 변경 흐름과 연결한다.
• ADR은 역피라미드 형식으로 핵심을 앞에 두고, markdown 등 가벼운 형식의 별도 파일로 doc/adr에 보존한다.
• 좋은 ADR에는 문제 정의, 절충·대안의 장단점, 결과, 확신 수준, 재검토 조건을 넣어 팀 관점 정합성과 추적 가능성을 높인다.

❓ 열린 질문

• 제품이나 생태계에 '중요한 단일 결정'인지 판단할 기준은 무엇으로 둘 것인가?
• 단조 증가 번호와 결정 요약 제목을 어떤 규칙으로 조합해 ADR 파일명 충돌을 예방할 것인가?
• 제안(proposed)에서 채택(accepted)·대체(superseded) 상태로 넘어가는 재검토 조건은 어떤 트리거로 잡을 것인가?