RFC에서 ADR로: 결정에 도달하고 이유를 유지하기

누구도 재구성할 수 없는 결정

새로운 기술 리더가 합리적인 질문을 던진다: 왜 모든 서비스가 그 큐를 통해 청구 시스템과 통신하는가? ADR이 있다 — ADR-014, 네 문장, 11개월 전에 작성되었다. 맥락: "신뢰할 수 있는 청구 통합이 필요했다." 결정: "큐를 사용하라." 결과: "약간의 지연이 추가된다." 기술적으로는 기록이다. 아무것도 답하지 않는다.

당신이 거기 있었으니 ADR-014이 말하지 않는 것을 알고 있습니다: 두 개의 Slack 채널과 격렬한 PR 스레드에서의 3주간의 논쟁; 그 이후로 한도가 높아진 이유로 패배한 동기식 API 옵션; 지금은 아무도 찾을 수 없는 벤치마크로 답변된 직원 엔지니어의 반대. 논쟁은 일어났습니다. 기록은 그 후 금요일에 한 사람이 기억을 바탕으로 작성되었습니다.

이것은 진정으로 좋은 관행의 문서화된 거의 보편적인 실패 모드입니다. AWS의 권장 지침과 Microsoft의 Well-Architected 문서 모두 ADR을 권장하며, 둘 다 고통을 언급합니다: 이를 최신 상태로 유지하는 데는 시간이 걸리고, 팀과 선택이 늘어남에 따라 관리가 복잡해집니다. 근본 원인은 구조적입니다: 논의와 기록이 서로 다른 장소에 존재하므로, 기록은 항상 손실이 있는 전사입니다. 해결책은 두 가지를 동일한 장소로 만드는 것입니다. 이 관행은 엔지니어링에 국한되지 않으며, ADR에 국한되지도 않습니다. Google은 설계 문서 — 문제, 제안된 접근 방식, 고려된 대안, 트레이드오프 — 를 요구하며, 이는 중요한 기술 작업이 시작되기 전에 작성되고 검토되어야 하며, 이는 회사의 Google의 소프트웨어 엔지니어링에서 설정된 관행입니다. 이는 ADR과 동일한 규율로, 한 단계 더 일찍 적용됩니다: ADR은 설계 문서가 주장한 선택을 기록합니다. 두 가지 모두 같은 이유로 같은 방식으로 실패하며, 두 가지 모두 같은 조치로 해결됩니다 — 기록이 존재하는 곳에서 논의를 진행하고, 나중에 하나를 다른 것으로 전사하는 것이 아니라. 아래의 모든 단계를 두 아티팩트를 모두 포함하는 것으로 읽으십시오.

왜 ADR이 썩는가

ADR 커뮤니티의 자료에서 한 문장이 전체 진단을 담고 있습니다: RFC는 일반적으로 합의에 도달하는 것에 관한 것이며, ADR은 도달한 합의를 기록합니다. 두 개의 산출물, 두 개의 순간 — 그리고 그 사이의 모든 것이 누수됩니다. "명백하게" 잘못된 대안은 기록되지 않습니다(명백하지 않게 될 때까지). 최종 디자인을 형성한 반대 의견은 닫힌 스레드의 PR 댓글로만 남아 있습니다. 맥락 섹션은 마지막에, 가장 형편없이, 게임에서 지는 사람에 의해 작성됩니다. 결정을 내려야 했던 회의는 요약만을 생산하고, 결정을 지속 가능하게 만드는 추론 — 전체 결정 품질 체인이 의존하는 것 — 은 정확히 전사에서 누락됩니다.

1단계–3단계: 제안, 맥락, 옵션

1. 1제안서를 근본 주장으로 명시하십시오 — 제안된 결정, 질문이 아님: "모든 청구 기록을 내구성 있는 큐를 통해 라우팅할 것입니다." 이 문장은 미래 ADR의 제목입니다. 체크포인트: 근본이 존재하며, 한 문장으로 제안자가 작성했습니다.
2. 2맥락을 개별적인 찬성 논거로. 결정을 필요로 하는 각 힘 — 신뢰성 요구, 청구 시스템 요금 한도, 감사 의무 — 는 뿌리 아래에서 각각의 주장을 형성합니다. 단일한 "맥락" 단락은 도전받을 수 없지만, 세 개의 개별 맥락 주장은 각각 질문, 확인 또는 반박될 수 있습니다. 체크포인트: ≥2 개의 맥락 논거, 각각 하나의 힘.
3. 3모든 옵션은 고유한 노드를 갖습니다. 큐, 동기 API, 배치 작업 — 형제 인수들, 각각의 장단점이 있습니다. 장단점은 부모에 상대적이므로, 옵션의 단점은 그 옵션에 달려 있으며, 결정에 달려 있지 않습니다. 거부할 것으로 예상되는 옵션도 포함하세요: 거부된 형제가 내년의 "왜 그냥…하지 않았을까"에 대한 답변이 됩니다. 체크포인트: 독자가 질문할 수 있는 모든 옵션이 존재합니다.

4–6단계: 기록을 남기는 RFC 라운드

이제 리뷰 라운드입니다 — 일반적으로 채팅, 댓글 및 복도에 흩어지는 부분입니다. 여기서는 세 가지 종류의 구조화된 교환으로 진행되며, 각 교환은 리뷰어와 옵션의 저자 간의 네 번의 대화로 구성됩니다:

7단계: 결정하기 — 그리고 평가가 아닌 것

의사결정자들은 옵션에 점수를 매깁니다: 각각에 레이블이 붙은 점수. 이 분포는 진정한 증거입니다 — 전화 통화 전에 방이 어떤 입장이었는지, 기록에 남아 있습니다. 하지만 점수는 결정이 아닙니다. 여전히 이름이 있는 사람이 결정을 내리며, 만약 통화가 분포와 반대 방향으로 진행된다면, 결정 노드에서 그 이유가 설명됩니다. (그 이름이 있는 사람이 누구여야 하는지, 그리고 논의 전에 역할을 어떻게 할당할 것인지에 대한 것은 자체적인 학문입니다 — 의사결정 권한 튜토리얼을 참조하세요.)

8–9단계: 작성할 필요가 없었던 ADR

여기 결론이 있습니다. 기록은 사후에 작성하는 문서가 아닙니다 — 선택된 옵션의 노드와 그에 이미 연결된 모든 것: 맥락 인수(Context), 거부된 형제 옵션(Options Considered), 완료된 체인(토론, 저자 포함), 평가(방의 상태), 그리고 그 근거가 있는 결정 인수(Decision)입니다. 아무것도 기록되지 않으므로, 기록 과정에서 잃어버리는 것도 없습니다.

1. 1당신이 수용하고 있는 결과를 기록하세요. 알려진 단점 — 추가 지연, 대기열의 운영 부담 — 선택된 옵션의 부작용으로 계속 존재하며, 결정자가 이를 인정합니다. 그것들을 적어두는 것이 선호가 아닌 결정을 만드는 것입니다. 체크포인트: 기록된 수용된 결과 ≥1.
2. 2조직에서 리포지토리 추적 ADR이 필요하다면 내보내세요. 많은 조직이 필요로 하며, 이는 올바른 접근입니다 — 코드 옆의 마크다운 ADR이 준수 아티팩트로 남습니다. 나무에서 네 개의 섹션 요약을 작성하세요 (5분, 금요일은 아님), 전체 논의를 위해 토론으로 다시 링크하세요. 체크포인트: 리포 ADR이 나무를 인용하고; 나무가 논리를 담고 있습니다.

동의하지 않지만, 공식적으로 약속합니다.

아마존이 유명하게 만든 패턴 — 반대하고 헌신하라 — 는 가독성 문제를 가지고 있다: 나중에 누가 어떻게 그 반대가 실제로 있었고, 들렸으며, 답변되었는지 알 수 있을까, 아니면 그냥 무시되었는지? 체인 메커니즘이 그에 대한 답을 제공한다. 네 번의 전체 턴을 거치고 합의 없이 완료된 리뷰 체인은 정확히 그 증거이다: 이의 제기가 이루어졌고, 답변되었으며, 압박을 받았고, 다시 답변되었으며, 기록에 남겨진 후 반대자가 헌신하기 전에 이루어졌다. 반대자는 들렸던 것으로 문서화되어 있으며 — 이것이 이후에 헌신하는 것이 단순히 순종하는 것이 아니라 합리적인 이유가 되는 것이다.

10단계: 삭제하지 않고 대체하기

결정의 시대. 동기식 옵션을 죽인 속도 제한이 높아지면, 올바른 조치는 대체하는 결정을 참조하는 새로운 결정입니다 — 무엇이 변경되었는지를 명시하는 ADR-014의 노드에 연결된 새로운 인수입니다. 이전 결정은 여전히 읽을 수 있으며, 그 이유는 새로운 결정이 무엇을 뒤집고 있는지를 아는 이유입니다.

명시적으로 관리해야 할 한 가지 솔직한 격차: 내장된 ADR 상태 필드가 없습니다. 제안됨 / 수용됨 / 대체됨은 주장의 일급 상태가 아닙니다 — 대체는 링크를 통해 모델링되며, 그 관습은 귀하가 유지해야 합니다. 제품이 이를 강제한다고 가정하기보다는 귀하 팀의 작업 합의서에 명시하십시오.

정직한 한계

• ✗이것은 귀하의 리포지토리에서 ADR을 대체하지 않습니다 귀하의 조직이 코드를 옆에 두고 버전 관리를 요구하는 경우. 요약을 내보내고 커밋하십시오; 나무를 사용하여 마크다운이 잘하지 못하는 부분 — 논쟁.
• ✗ADR 상태 필드가 없습니다. 제안/수락/대체는 제품이 강제하는 것이 아니라 귀하가 유지하는 연결 규칙입니다.
• ✗체인은 네 번의 회전입니다. 깊은 건축적 불일치는 호출이 필요할 것이며, 체인은 이전에 이미 시도된 것의 기록입니다.
• ✗평가는 단일 레이블 값이며, 가중치가 있는 다기준 점수가 아닙니다.
• ✗누구에게도 좋은 맥락을 쓰게 만들지 않습니다. 구조는 좋은 기록의 비용을 낮추지만, 판단을 제공하지는 않습니다.

실용적인 수업

• ✓하나의 RFC, 하나의 논의. 전체 분기의 아키텍처를 덮고 있는 메가 트리에 저항하세요 — 슈퍼세션 링크는 중첩보다 결정을 더 잘 연결합니다.
• ✓존재하는 것에서 씨앗을 뿌리세요. 결정이 많은 전사본이나 당신의 오래된 ADR 폴더를 추출하면 논쟁이 시작되는 데 도움이 됩니다 — 수입된 것으로 표시되어 실시간 주장이 구별될 수 있습니다.
• ✓리뷰어의 이름을 그들의 체인에 적어두고 거기에 두세요. 귀속은 책임입니다; 익명의 건축적 반대는 전설로 변합니다.
• ✓결과 섹션은 결정자의 것이며, 다른 누구의 것도 아닙니다. 수용한 사람이 작성한 수용된 단점은 리뷰어의 경고와는 다른 무게를 가집니다.

ADR-014, 대답하는 버전

새로운 기술 리더의 질문으로 돌아가 보겠습니다. 재구성된 버전에서 ADR-014는 노드입니다: 그 이유와 함께하는 큐 결정, 세 가지 맥락 힘(하나는 이제 오래되어 보입니다), 오래된 속도 제한을 명시하는 치명적인 이름을 가진 거부된 동기식 API 형제, 직원 엔지니어의 리뷰를 포함한 네 개의 완료된 리뷰 체인, 그리고 증거로 첨부된 벤치마크. 기술 리더는 10분 동안 읽고 속도 제한이 변경된 것을 보고 이전 노드에 연결된 대체 제안을 엽니다. 아무도 슬랙을 파지 않습니다. 그것이 전체 약속입니다: 체인들이 합의에 도달하고, 트리가 그것을 기록하며 — 그리고 그 기록은 당신이 질문할 것이라고 몰랐던 질문에 답합니다.