아키텍처 결정의 지속 가능한 기록: ADR을 활용한 설계 맥락 복원 및 팀 자산화

시스템이 오래될수록 팀은 “왜 이렇게 만들었지?”라는 질문을 더 자주 만납니다. 데이터베이스를 분리하지 않은 이유, 큐 대신 동기 호출을 택한 이유, 캐시의 일관성 창을 어디까지 허용한 이유는 코드만 읽어서는 알기 어렵습니다. 당시의 트래픽, 인력, 고객 약속, 마이그레이션 비용 같은 제약은 소스 파일 바깥에 있었기 때문입니다. 이 맥락이 사라지면 새 엔지니어는 과거 결정을 무능으로 오해하거나, 이미 검토된 대안을 다시 조사하는 데 시간을 씁니다.

아키텍처 결정 기록, 즉 ADR의 목적은 체계적이고 검증 가능한 역사책을 만드는 것이 아닙니다. 지금의 결론을 읽은 사람이 ‘당시 무엇이 문제였고, 어떤 선택지를 버렸으며, 언제 이 결정을 다시 열어야 하는지’를 짧게 파악하도록 돕는 것입니다. 문서가 길어질수록 읽히지 않고, 결론만 남으면 신뢰할 근거가 없습니다. 좋은 기록은 그 사이에서 다음 판단에 필요한 최소 맥락을 압축합니다.

결론만 적은 문서가 다음 세대의 시간을 빼앗는 이유

“PostgreSQL을 사용한다”, “이 API는 비동기로 처리한다” 같은 결론은 필요하지만 충분하지 않습니다. 이 문장만 남으면 다음 팀은 왜 다른 데이터베이스가 탈락했는지, 어떤 부하 조건에서 동기 처리가 위험해지는지 알 수 없습니다. 시간이 지나 요구사항이 달라졌을 때도 무엇을 다시 검토해야 할지 판단하기 어렵습니다. 결과적으로 문서는 있는데도 사람에게 물어보는 문화가 돌아옵니다.

기록에는 네 가지가 필요합니다. 첫째, 해결하려던 문제입니다. 둘째, 실제 제약입니다. 셋째, 선택한 안과 버린 안의 핵심 트레이드오프입니다. 넷째, 이 결정을 다시 열 신호입니다. 예를 들어 ‘트래픽이 특정 수준을 넘으면’, ‘규제 요구가 바뀌면’, ‘운영 인력이 늘어나면’처럼 검토 조건을 적어야 합니다. 이 조건은 예측이 아니라, 미래의 논의를 시작하는 안전장치입니다.

그렇다면 모든 기술 선택을 기록해야 할까요? 아닙니다. 팀의 행동이나 되돌림 비용을 바꾸는 선택만 남기면 됩니다. 라이브러리의 작은 옵션 하나보다 데이터 소유권, 장애 격리, 외부 계약, 비용 구조처럼 나중에 바꾸기 어려운 경계가 우선입니다.

‘회의록’이 아닌 ‘다음 행동을 정하는 문서’로 쓰는 법

ADR이 회의록이 되면 발언을 빠짐없이 옮기는 데 에너지를 쓰고, 읽는 사람은 결론을 찾지 못합니다. 반대로 승인 문서가 되면 반대 의견을 숨기게 됩니다. 실무에서 유용한 형식은 한 결정에 한 페이지 이하를 쓰고, 제목부터 선택지를 드러내는 것입니다. 예를 들어 ‘주문 생성은 동기 응답, 후속 알림은 이벤트로 분리한다’처럼 결론과 경계를 함께 제목에 넣습니다.

본문에는 결정 전의 모든 조사 결과가 아니라, 결정을 바꿀 수 있었던 근거만 남깁니다. 선택하지 않은 안도 한두 문장으로 남겨야 합니다. 그래야 후임자가 “그 방법은 왜 안 됐나”를 확인할 수 있습니다. 마지막에는 배포 뒤에 관찰할 지표와 재검토 날짜를 적습니다. 문서가 코드와 운영을 연결할 때만 기록은 살아 있습니다.

[문제] → [제약] → [선택한 안]
                   ├─ [버린 대안과 이유]
                   └─ [관찰 지표 / 재검토 신호]

▲ 기록은 과거를 정당화하는 벽이 아니라, 다른 팀원이 같은 판단에 접근하도록 돕는 다리다

기록을 늘렸는데도 속도가 느려진다면 무엇이 잘못됐을까?

문서가 병목이 되는 가장 흔한 이유는 완료 후에만 쓰기 때문입니다. 배포가 끝난 뒤 기억을 복원해 긴 문서를 작성하면, 기록은 야근과 승인 대기만 늘립니다. 더 나은 방법은 설계 검토나 풀 리퀘스트를 시작할 때 네 줄짜리 초안을 만들고, 배포 뒤 관찰 결과 한 줄을 추가하는 것입니다. 결정이 변하면 새 문서를 쓰기보다 이전 기록을 ‘대체됨’ 상태로 남겨 변경 관계를 연결합니다.

또 다른 위험은 ADR을 책임 회피의 방패로 쓰는 것입니다. 문서가 있다는 이유로 현재의 신호를 무시하면 기록은 팀을 고정시킵니다. 특히 비용, 성능, 고객 요구는 시간이 지날수록 달라집니다. 그래서 기록에는 언제든 반증될 수 있다는 전제가 필요합니다. 결정을 바꾸는 일은 과거를 부정하는 일이 아니라, 당시의 가정이 더 이상 맞지 않는다는 것을 팀이 함께 확인하는 일입니다.

결정 기록의 독자는 미래의 동료만이 아닙니다. 작성자 자신도 몇 달 뒤에는 당시의 논리와 제약을 잊습니다. 그래서 문장에는 ‘확실하다’보다 ‘이 조건에서는’이라는 범위를 남기는 편이 좋습니다. 예를 들어 현재 트래픽에서는 단일 데이터베이스가 운영 비용을 낮춘다는 결론을 적되, 읽기 부하가 증가하거나 지역 확장이 필요해질 때 어떤 신호를 확인할지 붙입니다. 이렇게 쓰면 문서는 선택을 고정하는 선언문이 아니라, 변화에 대응할 준비가 됩니다.

결정의 품질은 선택지 개수로 판단하지 않습니다. 팀이 실제로 통제할 수 있는 대안이었는지, 대안마다 무엇을 포기하는지, 실패했을 때 되돌리는 비용이 얼마인지가 더 중요합니다. 비교표를 만든다면 기능 목록보다 운영 질문을 먼저 둡니다. 장애가 났을 때 누가 깨우는가, 데이터가 어긋났을 때 어떤 복구가 가능한가, 비용이 늘 때 무엇을 줄일 수 있는가 같은 질문입니다. 이 질문에 답할 수 있다면 ADR은 기술 문서이면서 동시에 사업과 운영의 공용 언어가 됩니다.

특히 새로운 팀원이 합류할 때 기록은 온보딩 시간을 줄입니다. 모든 과거 회의를 보여 줄 필요 없이, 현재 서비스의 큰 경계와 그 경계가 생긴 이유를 몇 개의 ADR로 연결하면 됩니다. 신입 엔지니어는 ‘이 규칙을 지켜야 한다’는 명령보다 ‘이 규칙이 어떤 사고와 비용을 피하기 위해 생겼는지’를 이해할 수 있습니다. 이해한 규칙은 예외 상황에서도 더 안전하게 적용되지만, 이유를 모르는 규칙은 우회되거나 불필요하게 고집되기 쉽습니다.

기록을 고칠 권한도 분명해야 합니다. 누구나 제안하고 보완할 수 있어야 하지만, 현재 선택을 바꾸는 결정권자와 적용 시점은 명확해야 합니다. 그렇지 않으면 문서는 여러 의견이 뒤섞인 게시판이 되고, 코드는 다른 방향으로 움직입니다. 가장 단순한 운영법은 ADR마다 현재 상태를 제안·채택·대체·폐기 중 하나로 표시하고, 대체 문서 링크를 붙이는 것입니다. 이 관계만 유지해도 팀은 최신 결론과 과거의 맥락을 함께 찾아갈 수 있습니다.

결국 기록의 비용은 글자 수가 아니라 판단을 찾는 시간으로 계산해야 합니다. 같은 설계 논의를 반복하는 회의, 부재한 담당자를 기다리는 배포, 과거 이유를 몰라 안전한 변경을 포기하는 비용은 문서 작성 시간보다 훨씬 커질 수 있습니다. 짧고 정직한 ADR 하나는 그 비용을 한 번에 없애지는 못해도, 다음 질문이 어디서 시작해야 하는지를 알려 줍니다. 그것만으로도 팀의 설계 속도는 개인의 기억에서 벗어납니다.

처음에는 제목을 잘 쓰는 것부터 시작하면 됩니다. ‘캐시 도입’보다 ‘조회 지연을 줄이되 결제 잔액은 캐시하지 않는다’가 더 좋은 제목입니다. 제목만 읽어도 범위와 포기한 위험이 보이기 때문입니다. 이후에 근거와 관찰 신호를 보태면 기록은 자연스럽게 자랍니다. 형식을 지키기 위해 정보를 만들 필요는 없습니다. 실제로 선택을 바꾸는 증거만 남기는 절제가 기록의 신뢰도를 높입니다.

이 원칙은 개인의 커리어에도 남습니다. 복잡한 선택을 문제·대안·결과로 설명할 수 있는 엔지니어는 구현 능력뿐 아니라 조직의 판단 비용을 줄이는 사람으로 평가받습니다. 기록은 팀을 위한 장치이면서, 자신의 기술 리더십을 증명하는 가장 구체적인 흔적이 됩니다.

오늘의 결정을 내일의 팀이 읽을 수 있게 꼭, 꾸준히 남기세요.

팀 자산으로 만드는 3단계

첫 단계에서는 최근에 같은 질문이 반복된 설계 하나를 고릅니다. 그 결정의 문제, 제약, 대안, 재검토 조건을 한 페이지로 적고 링크를 코드와 이슈에 연결합니다. 둘째, 리뷰어가 결론을 승인하기 전에 버린 대안과 관찰 지표를 질문하도록 만듭니다. 이 과정은 설득을 위한 형식이 아니라, 숨은 가정을 드러내는 안전장치입니다. 셋째, 분기마다 오래된 기록 몇 개를 열어 현재 조건과 비교합니다. 유지·대체·폐기 중 하나를 선택하면 기록은 쌓여도 박제가 되지 않습니다.

좋은 아키텍처는 한 번의 뛰어난 선택으로 완성되지 않습니다. 시간이 지나도 팀이 선택의 이유를 읽고, 새로운 증거로 안전하게 결정을 갱신할 수 있을 때 유지됩니다. ADR은 글을 잘 쓰는 사람의 산출물이 아닙니다. 개인의 기억에 묶여 있던 판단을 팀의 재사용 가능한 자산으로 옮기는 가장 작은 운영 장치입니다.

참고 자료

• Architecture Decision Records (ADR) Technical Blueprint
• Google Engineering Practices: Writing Useful Technical Documentation
• Michael Nygard: Documenting Architecture Decisions