결정 기록 문서: ADR과 RFC는 왜 나중의 개발자를 살리는가

큰 설계문서는 자주 낡는다. 처음에는 열심히 쓰지만 코드가 바뀌고 일정이 밀리면 업데이트가 멈춘다. 시간이 지나면 남는 것은 최신 코드와 오래된 문서 사이의 불신이다. 같은 단어를 쓰더라도 제품 문맥이 다르면 답이 갈렸다. 그 갈림길을 숨기지 않는 쪽으로 썼다.

ADR이 커진 문제

참고: [Michael Nygard, Documenting Architecture Decisions](https://www.cognitect. 좋은 RFC는 찬성표를 모으는 문서가 아니다. 논쟁을 좁히는 문서다. 예를 들면 이렇게 좁힐 수 있다. ADR은 Architecture Decision Record다. 구조, 비기능 특성, 의존성, 인터페이스, 구축 기법에 영향을 주는 중요한 결정을 짧게 남긴다. 보통 Status, Context, Decision, Consequences를 적는다. 이 정도만 있어도 회의가 달라진다. “이 기능 좋다/싫다”가 아니라 어떤 위험을 먼저 볼지 이야기하게 된다. 특히 결정에서는 재현 조건을 같이 적어야 의미가 있었다.

처음에는 결정을 머리에만 뒀다

• 문제: 현재 public desk 요청 상태가 이메일과 DM으로 흩어진다.
• 제안: 상태 변경을 앱 내부 request detail에 먼저 모은다.
• 대안: 이메일 알림을 먼저 붙이거나 관리자 메모만 추가할 수도 있다.
• 위험: 사용자가 상태 페이지를 다시 방문하지 않을 수 있다.
• 검증: 상태 상세 페이지 진입률과 반복 문의 감소를 본다. ADR이나 RFC를 쓰다 보면 “우리가 왜 맞았는지”를 증명하고 싶어진다. 그러면 문서는 방어문이 된다. 좋은 결정 기록은 더 건조해야 한다. 모든 결정을 ADR로 남길 필요는 없다. 작은 결정은 Decision Log로 충분하다. 날짜, 결정, 이유, 영향만 남겨도 나중에 도움이 된다.
• 날짜: 2026-07-07
• 결정: 설계문서 공부 노트는 하나의 장문이 아니라 6편 시리즈로 나눈다.
• 이유: 한 글에 PRD, SRS, SDD, ADR, API Spec, Runbook을 모두 넣으면 읽기 흐름이 깨진다.
• 영향: 지도 글은 짧게 유지하고, 세부 문서군은 project archive에서 따로 읽게 한다. Michael Nygard의 ADR 글은 큰 문서가 거의 읽히지 않고 유지되지 않는 문제를 지적한다. 작은 모듈형 문서가 업데이트될 가능성이 더 높다는 것이다. 결정이 뒤집히면 삭제하지 않고 superseded로 남긴다. 그 결정이 한때 왜 맞았는지를 아는 것도 중요하기 때문이다.

나중 개발자를 살리는 게 선명해진 순간

결정 기록 문서의 목적은 코드 변경을 막는 것이 아니다. 오히려 안전하게 바꿀 수 있게 하는 것이다. 어떤 선택이 임시였는지, 어떤 선택이 제품의 핵심 경계였는지를 알면 바꿔도 되는 것과 건드리면 위험한 것을 나눌 수 있다. 이 다섯 가지가 있으면 충분하다. 미래의 개발자가 필요한 것은 과거의 자신감이 아니라 당시의 조건이다. RFC는 request for comments다. 팀 안에서 아직 확정되지 않은 설계 제안이나 큰 변경을 토론하기 위한 문서로 쓰이는 경우가 많다. ADR이 “결정된 이유”에 가깝다면 RFC는 “결정하기 전의 제안과 검토”에 가깝다. 이 문서는 긴 설명이 아니다. 하지만 미래의 개발자가 PostgreSQL로 바꾸려 할 때 중요한 질문을 준다. 지금도 초기 트래픽인가? 운영 단순성이 여전히 더 중요한가? 동시 쓰기 문제가 실제로 생겼는가? - 상태: Accepted

• 맥락: 초기 트래픽은 낮고 배포 단순성이 중요하다. 운영자는 한 명이고, 백업과 복구 절차를 빠르게 이해해야 한다.
• 결정: 첫 버전은 PostgreSQL 대신 SQLite를 사용한다.
• 결과: 운영과 배포는 단순해진다. 동시 쓰기와 수평 확장은 나중에 다시 판단해야 한다. - 당시 제약은 무엇이었나
• 어떤 선택을 했나
• 어떤 대안을 버렸나
• 그 결과 어떤 비용을 감수했나
• 언제 다시 봐야 하나 결정를 설명할 때 서버/클라이언트/사용자 중 누구 문장으로 말하는지 먼저 고르면 논쟁이 줄었다.

결정 기록 경계 나누기

그래서 결정 기록이 필요하다. ADR, RFC, Decision Log는 큰 설계문서를 대체하는 것이 아니라, 나중의 개발자가 “왜 이렇게 했지?”라고 물을 때 시작점을 남기는 작은 문서다. 참고: Michael Nygard, Documenting Architecture Decisions 특히 결정에서는 재현 조건을 같이 적어야 의미가 있었다. 좋은 RFC는 찬성표를 모으는 문서가 아니다. 논쟁을 좁히는 문서다. 예를 들면 이렇게 좁힐 수 있다. ADR은 Architecture Decision Record다. 구조, 비기능 특성, 의존성, 인터페이스, 구축 기법에 영향을 주는 중요한 결정을 짧게 남긴다. 보통 Status, Context, Decision, Consequences를 적는다. 특히 결정에서는 재현 조건을 같이 적어야 의미가 있었다.

구현과 운영에 남긴 조건

Michael Nygard의 ADR 글은 큰 문서가 거의 읽히지 않고 유지되지 않는 문제를 지적한다. 작은 모듈형 문서가 업데이트될 가능성이 더 높다는 것이다. 결정이 뒤집히면 삭제하지 않고 superseded로 남긴다. 그 결정이 한때 왜 맞았는지를 아는 것도 중요하기 때문이다. 결정 기록 문서의 목적은 코드 변경을 막는 것이 아니다. 오히려 안전하게 바꿀 수 있게 하는 것이다. 어떤 선택이 임시였는지, 어떤 선택이 제품의 핵심 경계였는지를 알면 바꿔도 되는 것과 건드리면 위험한 것을 나눌 수 있다. 이 다섯 가지가 있으면 충분하다. 미래의 개발자가 필요한 것은 과거의 자신감이 아니라 당시의 조건이다. RFC는 request for comments다. 팀 안에서 아직 확정되지 않은 설계 제안이나 큰 변경을 토론하기 위한 문서로 쓰이는 경우가 많다. ADR이 “결정된 이유”에 가깝다면 RFC는 “결정하기 전의 제안과 검토”에 가깝다. 이 문서는 긴 설명이 아니다. 하지만 미래의 개발자가 PostgreSQL로 바꾸려 할 때 중요한 질문을 준다. 지금도 초기 트래픽인가? 운영 단순성이 여전히 더 중요한가? 동시 쓰기 문제가 실제로 생겼는가? - 상태: Accepted

• 맥락: 초기 트래픽은 낮고 배포 단순성이 중요하다. 운영자는 한 명이고, 백업과 복구 절차를 빠르게 이해해야 한다.
• 결정: 첫 버전은 PostgreSQL 대신 SQLite를 사용한다.
• 결과: 운영과 배포는 단순해진다. 동시 쓰기와 수평 확장은 나중에 다시 판단해야 한다. 특히 결정에서는 재현 조건을 같이 적어야 의미가 있었다.

마치며

• 당시 제약은 무엇이었나
• 어떤 선택을 했나
• 어떤 대안을 버렸나
• 그 결과 어떤 비용을 감수했나
• 언제 다시 봐야 하나 그래서 결정 기록이 필요하다. ADR, RFC, Decision Log는 큰 설계문서를 대체하는 것이 아니라, 나중의 개발자가 “왜 이렇게 했지?”라고 물을 때 시작점을 남기는 작은 문서다. 참고: [Michael Nygard, Documenting Architecture Decisions](https://www.cognitect. 좋은 RFC는 찬성표를 모으는 문서가 아니다. 논쟁을 좁히는 문서다. 예를 들면 이렇게 좁힐 수 있다.