한 명이 빠졌을 때를 대비한 문서화 룰

세 명이 돌아가며 모든 걸 책임지는 구조에서는 한 명이 빠지는 순간 정보의 공백이 생각보다 크다. 휴가 한 번, 갑작스러운 개인 사정 하루, 면접 반나절 — 아무리 작아도 그 자리에 있던 맥락이 통째로 사라진다. 우리는 이 문제를 처음에는 슬랙 스레드와 노션 페이지로 해결하려 했지만, 곧 한계를 깨달았다.

왜 기존 방식이 실패했나

노션에 정리해두어도 어디 있는지 모르면 없는 것과 같다. 슬랙 스레드는 2주만 지나도 검색이 번거롭고, 본인 외에는 어떤 결정이 어떤 이유로 내려졌는지 알기가 어렵다. 더 큰 문제는 “일단 해결되면 기록하려고 했는데 바빠서 못 했다”는 패턴이 반복된다는 것이었다. 문서화를 별도의 작업으로 정의하는 한, 항상 우선순위에서 밀린다.

그래서 우리는 방향을 바꿨다. 문서화를 작업의 결과물이 아니라 작업 과정에 녹아드는 것으로 바꾸기로 했다.

우리가 정착시킨 세 가지 룰

첫 번째는 ADR(Architecture Decision Record) 한 줄 원칙이다. 무언가를 고르거나 바꿀 때, 그 이유를 한 줄이라도 git 커밋 메시지나 PR 설명에 적는다. 완벽한 ADR 형식을 강요하지 않는다. “왜 Redis를 선택했는가”가 세 줄 짜리 주석으로라도 코드 근처에 남아있으면, 석 달 뒤 다른 사람이 바꾸려 할 때 최소한의 맥락이 생긴다.

두 번째는 “내가 없으면 어떻게 되나” 체크리스트다. 각자 분기에 한 번, 자신이 맡은 시스템 중에서 “내가 사라졌을 때 나머지 두 사람이 혼자 해결할 수 있는가”를 따져본다. 해결이 어렵다고 판단되는 항목은 짧은 런북(runbook) 형태로 남긴다. 분기에 한 번이라는 주기는 부담 없이 유지할 수 있는 수준이다.

세 번째는 온콜 노트의 생활화다. 장애나 이슈가 생기면 해결하는 과정에서 텍스트 파일이든 슬랙이든 무조건 타임라인을 남긴다. “00:30 재시작 시도, 00:35 쿼리 락 발견, 00:50 인덱스 추가 후 정상” 같은 식이다. 해결 후에는 그 내용을 그대로 위키에 붙여넣고 태그만 달아둔다. 가공하지 않아도 된다.

실제로 바뀐 것

이 세 가지를 도입한 이후 팀 내에서 “이거 누가 만든 거야?”, “왜 이렇게 되어 있지?” 같은 질문이 눈에 띄게 줄었다. 여전히 구멍은 있지만, 한 명이 이틀 정도 자리를 비워도 나머지 둘이 대부분의 작업을 이어갈 수 있게 됐다. 특히 인프라 관련 작업에서 효과가 컸다. 서버 설정이나 배포 절차는 머릿속에 담아두기 쉬운 만큼 공유가 잘 안 되는 영역이었는데, 온콜 노트를 통해 자연스럽게 쌓이기 시작했다.

완벽한 문서화를 목표로 하지 않는다. 대신 최소한의 흔적을 남기는 습관을 만드는 것이 목표다. 세 명이 돌아가는 팀에서는 그 정도면 충분하다.

— by slecs