문서가 코드를 따라가지 못할 때
문서가 낡아서 팀이 손해보기 전에 쓰는 갱신 전략 회고
사고는 항상 문서 밖에서 났다
올해 초 배포 자동화 스크립트를 바꿨다. 환경 변수 이름을 APP_ENV에서 RUNTIME_ENV로 통일하는 작업이었다. 코드 변경은 PR 하나로 끝났는데, 런북은 아무도 안 건드렸다. 3주 뒤 신입 팀원이 런북대로 배포하다가 환경 변수 오류로 스테이징 전체를 날렸다. 장애 시간은 40분. 원인 파악에 20분을 더 썼다.
막상 원인 추적해보면 코드가 아니라 문서였다. 코드는 진실을 말하고 있었는데 문서는 3주 전 과거를 말하고 있었던 것.
”나중에 문서 업데이트” 는 실행이 0%다
PR 설명 맨 아래 “TODO: 런북 업데이트”를 적어두는 관행이 있었다. 솔직히 말하면 그 TODO 중에 실제로 이행된 것은 내 경험상 10%도 안 됐다. 이유는 단순하다.
- 코드가 merge 되는 순간 심리적으로 그 작업은 끝난 것처럼 느껴진다. 문서 갱신은 별도의 에너지를 다시 소비해야 하는 독립 태스크가 되어버린다. 그리고 독립 태스크는 급한 게 생기면 항상 밀린다.
- GitHub에서 TODO 코멘트를 추적하는 기능은 있지만 아무도 weekly로 그걸 확인하지 않았다. 결국 TODO 목록이 쌓이는 속도가 소화 속도를 항상 이겼다.
이 문제를 인식하고 나서 바꾼 것이 하나 있다. PR 템플릿에 “문서 갱신 체크박스”를 넣되, 체크 안 하면 리뷰어가 approve 못 하게 했다. 강제성이 생기니까 달랐다. 갱신율이 PR 기준으로 체감상 60~70%까지 올랐다. 여전히 100%는 아니지만, 0에 가까웠던 것과는 다른 세상이다.
문서 주인을 코드 주인이 가져가야 한다
이전에는 문서 폴더가 따로 있었다. /docs 안에 마크다운 파일들이 모여 있었고, 관리 주체가 명확하지 않았다. 누군가 “팀 공용 자산”이라고 부르는 순간 그건 아무도 안 고치는 자산이 된다.
바꾼 방식은 간단했다. 서비스별 런북을 코드 레포 안에 같이 넣었다. service-a/docs/runbook.md처럼. 그러면 해당 서비스 코드를 바꾸는 사람이 자연스럽게 같은 레포에서 문서도 보게 된다. 눈앞에 있으면 고칠 확률이 오른다. 멀리 있으면 안 고친다.
운영팀 누가 받고 누가 백업인지도 runbook.md 첫 두 줄에 박아뒀다. 새벽 2시 알림에 사람들이 헤매는 시간을 줄이는 게 목적이었다. 실제로 지난 분기 온콜 에스컬레이션 시간이 평균 12분에서 4분으로 줄었다. 문서 한 줄이 낸 차이다.
변경 규모별로 문서 대응 수위가 달라야 한다
모든 코드 변경이 런북 전면 재작성을 요구하지는 않는다. 그걸 구분 안 하면 오히려 관성이 생긴다. “어차피 많이 바꿔야 하니까 나중에”가 되기 쉽다.
- 환경 변수 이름 변경, 엔드포인트 URL 변경처럼 “운영 중 참조 빈도가 높은 값”이 바뀔 때는 당일 바로 갱신을 원칙으로 했다. 이게 방치되면 앞서 말한 40분 장애가 생긴다.
- 아키텍처 변경이나 새 서비스 추가처럼 맥락이 크게 달라지는 경우는 PR merge 후 3영업일 안에 별도 문서 작업 티켓을 만들고 그 티켓이 sprint에 들어가게 했다. “나중에”가 아니라 일감으로 만드는 게 핵심이다.
- 리팩터링처럼 외부 동작이 바뀌지 않을 때는 문서 갱신을 강제하지 않았다. 이걸 모두 같은 규칙으로 묶으면 불필요한 오버헤드가 생긴다.
구분 자체가 처음엔 모호했다. 팀 내에서 “이 변경이 운영 중 참조 가능한가?”라는 질문을 PR 리뷰 체크리스트에 넣었다. 그게 판단 기준이 됐다.
LLM 으로 초안 생성, 사람이 검증
2026년 기준으로 내가 실제로 써보고 있는 방식이다. diff를 Claude에 던지고 “이 변경을 반영해서 다음 런북 섹션을 고쳐줘”라고 하면 초안이 나온다. 처음엔 반신반의했는데, 막상 해보니 완성도가 낮더라도 “빈 문서 앞에서 시작해야 하는 부담”을 제거하는 효과가 컸다.
단, 검증은 반드시 사람이 한다. LLM이 환경 변수 이름은 맞게 고쳤는데 배포 순서를 틀리게 서술한 적이 있었다. 그걸 그냥 올렸다면 런북이 더 위험해지는 것이었다. 초안 생성과 사실 검증을 분리하는 습관이 중요하다.
또 하나. 문서 갱신에 LLM을 쓰기 시작하면서 역설적으로 원본 문서 품질이 올라갔다. 모호하게 쓰인 런북은 LLM도 모호한 초안을 뱉는다. 그걸 보고 “아, 원본이 이렇게 불명확했구나”를 깨닫고 고치게 되는 루프가 생겼다.
다음 한 가지
다음 글에서 한 줄 더: PR 템플릿 체크박스 강제화 이후 갱신율이 실제로 어떻게 유지됐는지, 분기가 지나도 같은 숫자인지 적어두기로.
🛒 이 글과 어울리는 추천 상품
위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.