1.6 결정 기록

개요와 동기

결정 기록(decision record)은 중요한 결정을 그 맥락과 결과와 함께 담은 문서입니다. 가장 잘 알려진 형태는 아키텍처 결정 기록(ADR)으로, 아키텍처상 중요한 선택 하나와 그것이 이루어진 이유, 그로부터 따라오는 결과를 기록하는, 가급적 불변인 짧은 메모입니다. 프로젝트의 기록 전체는 결정 로그(ADL)이며, 이를 유지하는 규율은 아키텍처 지식 관리(AKM)의 일부입니다. 이 장은 1.5장의 의사결정과 거버넌스 관행 위에 서서, 결정 기록을 대규모로 쓰고, 보관하고, 유지하는 방법에 초점을 맞춥니다.

동기는 단순하지만 어렵게 배우면 고통스럽습니다. 오래 사는 어떤 시스템에서든 가장 비싼 질문은 몇 달이나 몇 년 뒤에 그 자리에 없었던 사람들이 던지는 “도대체 왜 이렇게 만들었지?”입니다. 코드는 시스템이 무엇을 하는지 보여 줍니다. 테스트는 그것이 동작함을 보여 줍니다. 그러나 어느 쪽도 검토하고 기각한 대안들 대신 왜 이 길을 택했는지는 담지 못합니다. 결정 기록이 없으면 그 이유는 인력 교체와 함께 증발합니다. 팀은 이미 정리된 문제를 다시 따지고, 좋은 결정을 나쁜 이유로 뒤집거나, 두려움 때문에 나쁜 결정을 유지합니다. 결정 기록은 이유를 보존하는, 미래에게 보내는 값싼 편지입니다.

큰 팀에서 이것은 기억 보조만큼이나 조율 도구입니다. 기업에서는 수십 개 팀이 서로 겹치는 선택을 합니다. 공유된 결정 로그는 한 팀이 어렵게 얻은 이유를 재사용 가능한 자산으로 바꾸고, 갈라지고 호환되지 않는 결정을 막습니다. 정부와 규제 환경에서 결정 기록은 거의 의무입니다. 감사자, 감독 기관, 후임 계약자 모두 아키텍처상 중요한 요구사항과 그에 대해 내려진 선택을 잇는 추적 가능한 근거가 필요합니다. 잘 유지된 결정 로그는 보증하고 감사할 수 있는 시스템과 그럴 수 없는 시스템의 차이를 가르는 경우가 많습니다.

핵심 원칙

무엇만이 아니라 왜를 기록하십시오. 맥락과 기각된 대안이 핵심입니다.
기록 하나에 결정 하나. 각 기록을 구체적이고 자기완결적으로 유지하십시오.
작고 가벼운 것이 포괄적이지만 쓰이지 않는 것을 이깁니다. 존재하는 한 쪽짜리 기록이 쓰이지 않는 보고서보다 낫습니다.
모든 것에 시각을 찍으십시오. 비용, 제약, 벤더는 변합니다. 각 주장에 날짜를 쓰십시오.
현실적으로 살아 있는 로그를 선호하십시오. 불변성이 이상이지만, 실제로는 날짜가 붙은 메모로 수정하십시오.
약어보다 말. “ADR”보다 “결정”이라고 부르면 더 많은 기여를 부릅니다.
결정을 찾을 수 있고, 가능하면 테스트할 수 있게 만드십시오. 올바른 순간에 올바른 기록을 드러내고, 피트니스 함수로 보증하십시오.

권장 사항

핵심 구조를 담는다

좋은 결정 기록에는 몇 가지 핵심 섹션이 있습니다. 새로 발명하기보다 알려진 템플릿을 조정하십시오.

제목: 짧은 현재 시제 명령형 구절(“원장에 PostgreSQL을 사용한다”).
상태: 제안됨, 승인됨, 대체됨, 사용 중단됨.
맥락: 이 결정을 필요하게 만드는 상황, 힘, 사업 우선순위, 제약. 다루는 아키텍처상 중요한 요구사항을 포함합니다.
결정: 내린 선택을 평이하게 서술합니다.
결과: 무엇이 더 쉬워지고 무엇이 더 어려워지는지, 촉발되는 후속 결정, 감수한 위험.

인기 있는 템플릿으로는 Michael Nygard의 것(단순하고 널리 채택됨), Tyree와 Akerman의 것(가중치를 둔 대안이 있는 더 정교한 형태), MADR(Markdown Any Decision Records, 선택지와 그 장단점에 강함), Y-문장(한 문장의 구조화된 형태)이 있습니다. 기록이 비교될 수 있도록 조직마다 하나로 표준화하십시오. 복사해서 쓸 템플릿은 12.3장을 참조하십시오.

구체적이고, 날짜가 있고, 거의 불변인 기록을 쓴다

각 기록이 정확히 하나의 결정을 다루게 하십시오. 개별 주장에 시각을 찍으십시오. 특히 가격, 확장 수치, 벤더 기능, 라이선스 조건처럼 변하는 것에 그렇게 하십시오. 이론상 기록은 불변이어야 합니다. 결정이 바뀌면 이전 것을 대체하는 새 기록을 써서 이력을 보존합니다. 실제로는 많은 팀이 살아 있는 문서 방식이 더 잘 작동함을 발견합니다. 기존 기록에 날짜 스탬프와 결정 이후에 도착한 정보라는 메모를 붙여 새 정보를 삽입하는 것입니다. 둘 다 정당합니다. 불변 방식은 감사 추적에 더 강하고, 살아 있는 방식은 일상의 팀 지식에 더 좋습니다. 의도적으로 선택하고 일관되게 유지하십시오.

일이 있는 곳에 기록을 보관한다

결정 기록을 코드와 함께 버전 관리에 두십시오. 결정당 하나씩의 마크다운 파일을 담은 decisions/(또는 adr/) 디렉터리이며, 소문자에 대시로 구분한 명령형 동사구로 이름을 짓습니다(choose-database.md, format-timestamps.md). 이렇게 하면 이력, 리뷰, 차이 비교를 공짜로 얻고, 이유를 그것이 설명하는 대상 옆에 둘 수 있습니다. 팀이 위키, Google Docs, Jira식 트래커를 선호하면 그것을 쓰십시오. 도구는 습관보다 훨씬 덜 중요합니다. adr-tools 같은 가벼운 명령줄 도구가 기록의 뼈대를 만들고 색인을 붙일 수 있습니다.

“결정”이라고 부르고, 아키텍처 너머로 넓힌다

많은 팀에서 얻은 실용적 통찰이 있습니다. 이름이 중요합니다. 일부 개발자와 관리자는 “아키텍처”라는 단어에 거부감을 느끼고, “기록”은 사후의 서류 작업처럼 느껴질 수 있습니다. 디렉터리 이름을 단순히 “decisions”로 바꾸면 스위치가 켜지는 경우가 많습니다. 팀은 벤더 선택, 계획 결정, 일정 결정, 데이터와 컴플라이언스 결정을 모두 같은 템플릿으로 기록하기 시작합니다. 사람들은 약어보다 말에서 더 빨리 배우고, 프레임이 “필수 서식을 제출하라”가 아니라 “미래의 동료가 생각하도록 도우라”일 때 더 많이 기여합니다.

수명주기와 거버넌스를 정의한다

결정 기록이 확장되려면 주변 프로세스에 합의하십시오(여기서 1.5장의 거버넌스가 실천과 만납니다).

누가 제기할 수 있고, 무엇이 그것을 정당화하는가: 보통 아는 기여자라면 누구나 할 수 있습니다. 미래의 개발자가 왜를 필요로 할 때 기록을 제기하고, 위험이 낮거나 자기완결적이거나 이미 문서화된 선택은 건너뜁니다.
수명주기: 시작 → 조사 → 평가 → 구현 → 유지 → 종료 같은 단순한 흐름과 단계 간 이동을 위한 수용 기준(문제가 명료화됨, 대안이 검토됨, 트레이드오프가 문서화됨, 이해관계자와 협의함).
역할: 제안자, 조사자, 검토자, 승인자, 그리고 기록을 주기적으로(최소 연 1회) 검토하고 결국의 종료를 이끄는 책임 유지자.
거버넌스: 합의, 갈등, 에스컬레이션, 거부권이 어떻게 작동하는지와 컴플라이언스 제약. 행동 우선 및 이견이 있어도 헌신(disagree-and-commit) 같은 원칙에 의존하고, 더 무거운 프로세스는 되돌릴 수 없고 영향 범위가 큰(“일방향 문”) 결정에 남겨 두십시오.

결정을 테스트 가능하고 찾을 수 있게 만든다

결정 기록은 결정을 문서화하고, 피트니스 함수(fitness function)는 그것을 보증합니다. 지속적 통합(CI)에서 실행되어 결정이 여전히 성립하는지 검증하는 자동 검사입니다(“모든 상태 변경은 이벤트를 발행해야 한다”, “어떤 모듈도 이 경계를 넘어 임포트할 수 없다”를 ArchUnit 같은 도구로). 이는 거버넌스를 주기적인 수동 검토에서 지속적이고 확장 가능한 시행으로 바꾸며, 규제와 감사 목표(3.1, 4.6, 8.5장)에 특히 가치가 있습니다. 그다음 올바른 기록을 올바른 순간에 드러내십시오. 개발자가 그 기록이 다스리는 코드를 건드릴 때 관련 결정을 풀 리퀘스트에 붙여 주는 도구가, 사람들이 문서 폴더를 읽기를 바라는 것보다 낫습니다.

장단점

선택	장점	단점
가벼운 ADR (Nygard/MADR)	쓰기 빠르고 실제로 쓰임. 낮은 의식	위험이 크고 논쟁적인 결정에는 엄밀함이 부족
무거운 템플릿 (Tyree-Akerman)	가중치를 둔 대안. 크고 비싼 선택에 강함	느림. 일상적 기록을 막을 수 있음
불변 + 대체	깔끔한 감사 추적. 이력 보존	기록이 늘어남. 독자가 사슬을 따라가야 함
살아 있는 문서 (날짜 있는 수정)	단일 현재 진실의 원천. 유지하기 쉬움	감사 측면이 약함. 조용한 수정의 위험
저장소 내 마크다운	버전 관리, 검토 가능, 코드 옆에 있음	비개발자에게 덜 친화적
위키 / 문서 도구	모든 역할이 접근 가능	이력과 검토가 약함. 코드와 어긋남

핵심 긴장은 엄밀함 대 채택입니다. 아무도 쓰지 않는 가장 엄밀한 시스템은 아무것도 기록하지 않습니다. 모두가 쓰는 가장 가벼운 시스템은 가치가 복리로 불어납니다. 가볍게를 기본으로 하고, 더 무거운 프로세스는 비싸고 되돌리기 어려운 소수의 결정에 남겨 두십시오.

팀과 논의할 질문

아무도 열지 않는 폴더에 놓여 있는 대신, 개발자가 그 기록이 다스리는 코드를 건드리는 순간 올바른 결정 기록이 그에게 닿으려면 어떻게 해야 합니까? 쓰기 전용 로그는 행동을 전혀 바꾸지 못하는 이유를 기록하며, 이는 결정 기록이 실패하는 가장 흔한 방식입니다. 존재하지만 중요할 때 아무도 읽지 않습니다. 상충하는 고려는 노력입니다. 기록을 자동으로 드러내는 일(누군가 다스려지는 코드를 편집할 때 풀 리퀘스트에 붙이는 것)은 위키나 문서 폴더에는 필요 없는 도구 투자가 들기 때문입니다. 최근에 누군가 이미 정리된 문제를 뒤집거나 다시 따졌을 때, 관련 기록이 그 순간에 찾을 수 있었는지 묻혀 있었는지 증거를 논의에 가져오십시오. 수십 개 팀을 운영하는 큰 조직에서 찾을 수 있음은 한 팀이 어렵게 얻은 이유를 사적인 기록 보관소가 아니라 재사용 가능한 자산으로 바꾸는 요소입니다. 기록을 코드 옆 버전 관리에 보관하고 풀 리퀘스트 흐름에 연결해, 일이 일어나는 곳에 기록이 나타나게 할지 결정하십시오.
각 기록의 책임 유지자는 누구이며, 무엇이 로그를 자신 있는 오정보로 퇴화하지 않게 막습니까? 결정 로그의 위험한 실패 양상은 빈 폴더가 아니라, 비용과 벤더 기능과 제약이 몇 년 전 조용히 낡아 버린 기록으로 가득 찬 폴더입니다. 모든 기록에는 주기적으로(최소 연 1회) 검토하고 대체나 종료를 이끄는 책임 있는 소유자가 필요합니다. 그렇지 않으면 로그는 사람들이 선택적으로 인용하고 거의 믿지 않는 민간 전승으로 썩습니다. 증거를 가져오십시오. 날짜가 없는 기록이 몇 개인지, 이후 바뀐 벤더나 가격을 서술하는 기록이 몇 개인지, 각각이 마지막으로 검토된 때가 언제인지입니다. 정부와 규제 환경에서는 이것이 더 날카롭습니다. 불변이고 대체된 사슬이 바로 감사자와 후임 계약자가 추적 가능한 근거로 의존하는 것이기 때문입니다. 수명주기를 명시적으로 정하고, 변하는 개별 주장에 시각을 찍고, 유지자를 지정하여 로그가 묘지가 아닌 살아 있는 자산으로 남게 하십시오.
모든 팀에 걸쳐 하나의 템플릿으로 표준화해야 합니까, 그리고 가장 위험이 큰 결정에는 실제로 얼마나 엄밀함이 필요합니까? 비교 가능성은 실질적 이점입니다. 모든 팀이 같은 형태(Nygard, MADR 등)를 쓰면 새 팀은 한 달의 논쟁 대신 오후 한나절에 이전 기록 셋을 찾아 이유를 채택할 수 있습니다. 핵심 긴장은 엄밀함 대 채택입니다. 아무도 쓰지 않는 가장 무거운 템플릿은 아무것도 기록하지 않고, 모두가 쓰는 가장 가벼운 것은 가치가 복리로 불어나기 때문입니다. 증거를 가져오십시오. 기록이 실제로 쓰이고 있습니까, 그리고 별개로, 크고 논쟁적이며 비싼 결정이 가벼운 형식이 대안 저울질을 건너뛰어 분석이 부족하지는 않았습니까? 팀 간에 겹치는 선택을 조율하는 기업에서 공유 템플릿과 검색 가능한 색인은 갈라지고 호환되지 않는 결정을 막습니다. 일반적인 경우에는 가볍게를 기본으로 하고, 어떤 일방향 문 결정이 가중치를 둔 대안이 있는 더 무거운 형식을 받을 자격이 있는지 미리 합의하십시오.
무엇이 결정 기록을 제기하는 것을 정당화하며, 어떤 선택에 기록이 필요 없다고 말할 권한은 누구에게 있습니까? 기준을 너무 높게 잡으면 중대한 선택 뒤의 이유가 증발하고, 너무 낮게 잡으면 로그가 사람들이 정말 필요로 하는 기록을 묻어 버리는 잡다한 것으로 채워집니다. 큰 조직에서 불분명한 기준은 각 팀이 자기 기준을 즉흥으로 만든다는 뜻이며, 그러면 커버리지가 고르지 않게 되고 기록이 없다는 것이 중요하지 않은 결정이라는 신호임을 아무도 믿을 수 없습니다. 증거를 논의에 가져오십시오. 기록되었지만 그럴 필요가 없었던 최근 결정 몇 개와, 기록되지 않아 나중에 재발견 비용을 치른 고통스러운 결정들입니다. 평이한 시험에 합의하십시오. 예컨대 미래의 개발자가 왜를 필요로 할 때 기록하고, 위험이 낮거나 자기완결적이거나 이미 문서화된 선택은 건너뜁니다. 규제와 정부 환경에서는 계산이 달라집니다. 감사 의무가 팀이 쓸 가치가 있다고 판단하는지와 상관없이 아키텍처상 중요한 모든 요구사항에 기록을 요구할 수 있으므로, 어떤 결정이 협상 불가인지 미리 이름을 붙이십시오.
여러분의 기록은 결정의 순간에 포착된 진짜 추론입니까, 아니면 의무를 충족하려고 나중에 쓴 서류 작업입니까? 티켓을 닫으려고 사후에 만든 기록은 선택된 안을 세탁하고 실제로 저울질한 대안을 조용히 빠뜨리는 경향이 있는데, 이것이 바로 미래의 독자가 가장 필요로 하는 정보입니다. 상충하는 압력은 실제입니다. 결정 전이나 도중에 왜를 쓰는 것은 출시하는 것보다 느리게 느껴지고, 기각된 길을 글로 인정하려면 일부 팀에게는 없는 심리적 안전이 필요합니다. 최근 기록 표본을 테이블에 가져와, 맥락과 기각된 대안이 진짜 숙고로 읽히는지 사후에 끼워 맞춘 정당화로 읽히는지 솔직하게 물어보십시오. 큰 팀에서 공허한 기록은 없는 것보다 나쁩니다. 로그를 신뢰할 수 없다고 사람들에게 가르치기 때문입니다. 기업과 정부 감사에서 이 구분은 날카롭습니다. 감독 기관과 후임 계약자는 정말로 검토된 것을 반영하는 근거에 의존하고, 연극으로 읽히는 기록은 로그가 제공하려는 보증을 훼손합니다.
주기적인 수동 검토가 위반을 잡아내리라 믿는 대신, 가장 위험이 큰 결정 중 어떤 것을 자동화된 피트니스 함수로 보증할 수 있습니까? 결정 기록은 선택을 문서화하지만, 수십 명의 개발자가 수년에 걸쳐 코드를 건드리면서 그 선택이 조용히 침식되는 것을 막는 것은 지속적 통합에서 실행되는 자동 검사뿐입니다. 트레이드오프는 투자입니다. (ArchUnit 같은 도구로) 피트니스 함수를 쓰고 유지하는 데는 엔지니어링 시간이 들고, 많은 결정, 특히 프로세스나 벤더 선택은 기계적으로 테스트할 수 없기 때문입니다. 증거를 가져오십시오. 어떤 경계 결정(모듈 의존성, 이벤트 발행, 데이터 접근 규칙)이 조용히 위반되었고 리뷰나 프로덕션에서 늦게야 잡혔습니까? 여러 팀을 운영하는 기업에서 피트니스 함수는 거버넌스를 중앙 병목에서 모두를 늦추지 않고 확장되는 지속적 시행으로 바꿉니다. 규제와 정부 맥락에서 자동화된 상시 검사는 검토에 찍힌 서명보다 훨씬 강한 감사 증거입니다. 누군가 한때 승인했다는 사실이 아니라 결정이 오늘도 성립함을 증명하기 때문입니다.

분야별 관점

스타트업. 습관만 남기고 나머지는 다 버리십시오. 메인 저장소의 decisions/ 폴더와, 미래의 내가 의문을 가질 판단을 할 때마다 쓰는 두 섹션(맥락과 선택)짜리 메모입니다. 수명주기, 역할, 승인자는 완전히 건너뛰십시오. 지속할 수 없는 프로세스는 포기하게 될 프로세스이기 때문입니다. 첫 번째 채용자가 시스템이 왜 이렇게 만들어졌는지 묻지 않게 해 주는 기록 하나만으로 이미 이 관행 전체의 값을 합니다.

소기업. 전담 아키텍트도 시간도 없으니, 전용 도구를 사지 말고 팀이 이미 일하는 곳, 즉 위키, 공유 문서, 저장소 어디든 기록을 두십시오. 도구보다 습관이 훨씬 중요하니 장벽을 낮추십시오. 디렉터리 이름을 adr이 아니라 decisions로 하고, 벤더와 자체 개발 대 구매 선택도 기술적 선택과 같은 숨에 담으십시오. 외부 계약자에게 의존할 때, 벤더나 플랫폼을 고른 이유를 날짜와 함께 짧게 적은 기록은 나중에 아무도 설명할 수 없는 선택에 묶이는 일에 대한 값싼 보험입니다.

대기업. 일은 많은 팀에 걸친 조율입니다. 하나의 템플릿으로 표준화하고, 검색 가능한 팀 간 색인을 공개하고, 핵심 경계 결정을 피트니스 함수로 뒷받침하여 위반이 리뷰를 기다리지 않고 빌드를 실패시키게 하십시오. 각 기록에 검토 주기를 가진 책임 유지자를 지정하여 로그가 민간 전승으로 퇴화하지 않고 살아 있는 자산으로 남게 하십시오. 잘하면, 한 팀의 어려운 선택에 대한 이유가 다음 팀이 다시 따지는 대신 오후 한나절에 채택하는 자산이 됩니다.

정부. 조달 규칙, 투명성, 공적 책임성이 결정 기록을 거의 의무로 만듭니다. 아키텍처상 중요한 모든 요구사항에 대해 선택을 그것이 충족하는 권한이나 컴플라이언스 통제와 연결하는 불변이고 대체된 기록을 요구하여, 감독 기관이 재구성이 아니라 추적 가능한 근거를 찾게 하십시오. 공공 시스템은 다년, 다벤더의 수명에 걸쳐 있으므로, 잘 유지된 로그는 후임 계약자가 시스템이 왜 이런 모양인지 이해하고 이미 정리된 사안을 다시 따지지 않고 일을 이어 가게 하는 경우가 많습니다.

사례

스타트업. 다섯 명짜리 스타트업이 메인 저장소에 평범한 decisions/ 폴더를 추가하고, 누군가 미래의 자신이 의문을 가질 판단을 할 때마다 두 섹션(맥락과 선택)짜리 메모를 씁니다. 수명주기도, 역할도, 승인자도 없습니다. 코드 옆에 왜를 쓰는 습관뿐입니다. 여섯 달 뒤 첫 채용자가 합류했을 때 그녀는 폴더 전체를 한 시간 만에 읽고 “왜 이렇게 만들어졌지?”라고 묻기를 멈춥니다. 이 가벼운 로그는 항목당 몇 분이 들고, 팀이 커지기 훨씬 전부터 물리는 재발견 세금을 면하게 해 줍니다.

대기업. 30개 엔지니어링 팀을 가진 소매업체가 각 저장소에 MADR 형식 기록과 검색 가능한 중앙 색인으로 표준화합니다. 새 팀이 ”모노레포 대 멀티레포” 문제에 직면했을 때, 맥락과 결과가 있는 이전 기록 셋을 찾아 한 달의 논쟁 대신 오후 한나절에 이유를 채택합니다. 핵심 경계 결정(서비스 소유권, 데이터 접근 규칙)은 ArchUnit 피트니스 함수로 뒷받침되어, 위반이 리뷰에서 잡히길 기다리지 않고 빌드를 실패시킵니다. 이것이 중앙 병목 없이 확장되는 거버넌스입니다.

정부. 급여 시스템을 현대화하는 한 기관은 아키텍처상 중요한 모든 요구사항에 ADR을 요구하고, 각각이 결정을 그것이 충족하는 권한이나 컴플라이언스 통제(접근성, 데이터 거주, 감사 가능성)와 연결하게 합니다. 기록은 불변이고 대체되어, 감독 검토를 만족하는 추적 가능한 로그를 만듭니다. 결정적으로, 후임 계약자가 시스템이 왜 이런 모양인지 이해하게 하여, 공공 프로그램에 전형적인 다년, 다벤더의 수명에 걸쳐 연속성을 보존합니다(4.6, 10.4장).

비즈니스 사례: 동기, ROI, TCO

결정 기록은 쓰는 데 몇 분, 검토하는 데 몇 분이 더 듭니다. 수익은 피한 재결정 비용과 피한 잘못된 뒤집기 비용이며, 둘 다 오래 사는 시스템에서 크고 반복됩니다. 팀이 이미 정리된 문제를 다시 따지거나, 그 뒤의 제약을 아무도 기억하지 못해 건전한 선택을 뒤집을 때마다, 시니어 엔지니어의 시간과 종종 인시던트로 대가를 치릅니다. 결정 로그는 그 반복되는 세금을 일회성 쓰기로 바꿉니다.

총소유비용 측면에서 결정 기록은 유지할 수 있는 문서 중 지렛대 효과가 가장 큰 것에 속합니다. 인력 교체에 가장 민감한 단 하나의 자산, 즉 근거를 겨냥하기 때문입니다. 온보딩이 빨라집니다(신규 입사자는 코드만이 아니라 왜를 읽습니다). 현대화가 더 안전해집니다(3.6장: 본질적 결정과 부수적 결정을 구분할 수 있습니다). 감사가 더 쌉니다(증거가 이미 존재합니다). 유지하지 않는 비용은 어떤 대시보드에도 보이지 않으며, 모든 퇴사와 함께 조용히 복리로 불어납니다. 리더십을 설득하려면 최근의 비싼 재발견이나 인시던트를 일으킨 뒤집힌 결정을 지목하고, 해법을 제도화하는 데 거의 비용이 들지 않음을 짚으십시오.

안티패턴과 함정

왜 없이 무엇만 기록: 맥락과 기각된 대안, 즉 핵심을 빠뜨리는 것.
사후 서류 작업: 생각하려는 것이 아니라 의무를 충족하려고 쓴 기록. 공허하게 읽히고 아무도 신뢰하지 않습니다.
여러 결정을 담은 거대 문서: 아무도 탐색하거나 깔끔하게 대체할 수 없는 거대한 한 페이지.
날짜 없는 주장: 한때 사실이었던 비용과 제약이 영원한 것처럼 제시됨.
조용한 수정: 날짜 있는 메모 없이 결정의 이력을 바꿔 감사 추적을 파괴하는 것.
쓰기 전용 로그: 만들어졌지만 관련된 순간에 드러나지 않아 행동에 영향을 주지 못하는 기록.
약어 문지기: “ADR”과 “아키텍처”를 고집해 기여를 낙담시키는 것.
수명주기 없음: 검토, 대체, 종료 없이 오정보로 퇴화하는 기록.

성숙도 모델

1단계(시작): 결정이 사람들의 머릿속, 채팅 스레드, 커밋 메시지에 삽니다. 포착은 반응적이고 그때그때이며, 근거는 인력 교체와 함께 일상적으로 사라집니다.
2단계(발전): 일부 팀이 누군가 기억할 때마다 다양한 형식과 템플릿으로 기록을 유지합니다. 관행은 팀마다 일관되지 않고, 공유 로그, 명명, 프로세스가 없습니다.
3단계(표준화): 단일 템플릿, 저장소 내 보관, 정의된 수명주기와 거버넌스(제기/건너뛰기 기준, 역할, 검토 주기)가 문서화되어 조직 전체에서 일관되게 적용됩니다. 기록은 조용히 수정되지 않고 검토되고 대체됩니다.
4단계(관리): 결정 로그가 기준선에 대해 측정됩니다. 커버리지(아키텍처상 중요한 결정 중 기록이 있는 비율), 신선도(주기 안에 검토된 기록의 비율과 날짜 없거나 낡은 주장의 수), 찾을 수 있음(관련 기록이 다스려지는 코드를 바꾼 개발자에게 실제로 닿은 빈도). 책임 유지자가 이 지표에 따라 행동하여, 일화가 아닌 증거에 근거해 낡은 기록을 대체하고 커버리지 격차를 메웁니다.
5단계(오케스트레이션): 검색 가능한 팀 간 결정 로그가 일상 업무에 통합됩니다. 관련 기록이 그것이 다스리는 변경에 자동으로 드러나고, 핵심 결정은 지속적 통합의 피트니스 함수로 보증되며, 로그는 살아 있는 자산으로서 온보딩, 현대화, 감사에 공급됩니다. 조직은 시스템과 제약이 바뀜에 따라 기록을 종료하고, 대체하고, 범위를 다시 정하면서 관행 자체를 지속적으로 개선하고, 결정의 포트폴리오가 커짐에 따라 엄밀함을 투자하는 곳을 재균형합니다.

논의를 위한 아이디어

아무도 원래의 이유를 기억하지 못해 팀이 마지막으로 뒤집거나 다시 따진 결정은 무엇이었습니까?
adr/ 디렉터리를 decisions/로 이름을 바꾸면 누가 기여하고 무엇이 기록되는지가 달라질까요?
중요한 결정 중 오늘 자동화된 피트니스 함수로 보증할 수 있는 것은 무엇입니까?
불변 후 대체인가, 살아 있는 문서인가. 감사 의무와 문화에 어느 쪽이 맞으며 그 이유는 무엇입니까?
신규 입사자(또는 후임 계약자)는 현재 시스템이 왜 이런 모양인지 어떻게 알아내겠습니까?
팀에서 결정 기록을 제기하는 것을 정당화하는 것은 무엇이며, 제기하지 않는 것을 정당화하는 것은 무엇입니까?

핵심 요점

결정 기록은 하나의 중요한 결정을 맥락과 결과와 함께 담습니다. 무엇만이 아니라 왜입니다.
기록을 구체적이고, 시각이 찍히고, 가볍게 유지하십시오. 하나의 템플릿(Nygard, MADR 등)으로 표준화하십시오.
코드 옆 버전 관리에 보관하십시오. 기여를 넓히기 위해 “decisions”라고 부르는 것을 고려하십시오.
수명주기와 거버넌스(제기/건너뛰기 기준, 역할, 검토 주기)를 정의하고, 무거운 프로세스는 일방향 문 결정에 남겨 두십시오.
변경의 순간에 결정을 찾을 수 있게 하고, 가능하면 피트니스 함수로 테스트할 수 있게 하십시오.
ROI는 피한 재발견 비용과 잘못된 뒤집기 비용이며, TCO 논거는 인력 교체, 현대화, 감사가 가장 중요한 곳에서 가장 강합니다. 1.5장(의사결정과 거버넌스)과 3.1장(아키텍처의 기본)을 참조하십시오.

참고 문헌과 더 읽을거리

Michael Nygard, “Documenting Architecture Decisions” (2011): the foundational lightweight ADR.
MADR: Markdown Any Decision Records project (adr.github.io/madr).
Jeff Tyree and Art Akerman, “Architecture Decisions: Demystifying Architecture” (IEEE Software, 2005).
Olaf Zimmermann, “Y-Statements” and “Architectural Decision Making” (ozimmer.ch).
Joel Parker Henderson, Architecture Decision Record (ADR): templates, examples, and teamwork guidance (github.com/joelparkerhenderson/architecture-decision-record).
ThoughtWorks Technology Radar: “Lightweight Architecture Decision Records.”
Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage, Building Evolutionary Architectures (fitness functions).
AWS Prescriptive Guidance, “ADR process”; Red Hat, “Why you should use ADRs.”
Wikipedia, “Architectural decision” and “Architecturally significant requirements.”