문서가 코드를 따라가지 못할 때
문서가 코드보다 느린 건 기술 문제가 아니다. 구조 문제다.
언제 터지나
배포 직후가 아니다. 보통 두세 달 뒤, 새 사람이 온보딩하거나 장애 대응 중에 터진다. 문서 읽고 따라갔는데 동작이 다르다. 이미 긴장한 상황에서 신뢰까지 깎인다.
우리 팀도 올해 초 이걸 제대로 겪었다. 인프라 교체를 하면서 내부 API endpoint 가 바뀌었는데, README 의 예시 curl 은 6개월 전 주소를 가리키고 있었다. 당시 작업자는 분명히 알고 있었다 — 그냥 고칠 타이밍이 없었던 것이다. 문서는 코드가 바뀌는 순간이 아니라, 코드 리뷰가 끝나는 순간에 잊힌다.
패턴은 대개 이렇다:
- 기능 변경 → PR 올라감 → 리뷰 통과 → 머지
- 문서 갱신은 “다음 PR에” → 그 PR은 없다
- 3개월 후 누군가 삽질
억지로 프로세스 만들면 안 되는 이유
문서 갱신 체크리스트를 PR 템플릿에 넣어봤다. 처음 2주는 작동했다. 그 뒤부터는 “해당 없음” 체크가 디폴트가 됐다. 사람은 마찰을 줄이는 방향으로 움직인다. 체크박스는 마찰처럼 보이지만 사실은 알리바이가 된다.
CI 에서 docs lint 를 돌리는 것도 해봤다. 링크 깨짐은 잡을 수 있다. 내용이 낡은 건 못 잡는다. POST /v1/users 가 POST /v2/users 로 바뀌었을 때, 링크는 여전히 살아있다. 그냥 틀린 내용이 살아있는 것이다.
그래서 지금은 전략 자체를 바꿨다. 문서를 “항상 최신으로” 유지하려는 목표를 버렸다. 대신 두 가지만:
1. 문서를 코드에 가깝게 붙여놓는다
별도 노션 페이지나 위키에 두면 코드 변경과 물리적으로 분리된다. 대신 해당 서비스 레포 안에 docs/ 폴더로 두면, 최소한 같은 PR 안에서 함께 보인다. 강제는 못 하지만 같은 화면에 있으면 눈에 띈다.
docs/api.md 를 src/routes/ 옆에 두는 것만으로도 체감이 다르다. PR diff 에서 라우트 파일이 바뀌면 옆에 api.md 가 안 바뀐 게 보인다. 암묵적 리마인더다.
2. 문서에 날짜가 아니라 “마지막으로 검증한 버전” 을 박는다
<!-- verified: v2.3.1, 2026-03 -->이게 있으면 두 가지가 생긴다. 독자가 “이 문서가 내 버전이랑 맞나” 판단할 수 있다. 그리고 작성자 스스로 언제 마지막으로 봤는지 기억한다. 날짜 없는 문서는 “영원히 맞는 것” 처럼 보인다. 버전이 박히면 유통기한이 생긴다.
손댈 수 없으면 썩었다고 표시라도
모든 문서를 갱신할 여력은 없다. 현실적으로 오래된 문서는 방치된다. 그러면 두 번째 전략: 썩었다는 사실을 명시한다.
> ⚠️ 이 문서는 v1 기준입니다. 현재 운영 중인 v2와 다를 수 있습니다.
> 정확한 동작은 코드를 확인하세요: `src/auth/README.md`이게 없으면 독자는 맞는 줄 알고 따라간다. 이게 있으면 최소한 의심하고 찾아본다. 완벽한 문서보다 “이건 믿지 마라” 한 줄이 나을 때가 있다.
막상 해보면 팀에서 저항이 거의 없다. “문서 갱신해라” 는 부담이지만, “낡은 문서에 경고 달아라” 는 솔직한 행위라 받아들이기 쉽다. 죄책감 대신 투명성이다.
한 가지 더. 장애 대응 중에 문서 틀렸다는 걸 발견하면, 그 자리에서 바로 고친다. 대응 끝나고 나중에 고치겠다는 건 대부분 안 고친다. 15분짜리 hotfix PR 에 docs: fix outdated endpoint 커밋 하나 같이 넣는 게 낫다. 타이밍이 맞을 때 붙잡는 것이다.
다음 한 가지
다음 배포 때 바뀌는 파일 옆에 docs/ 안 건드렸는지 PR description 에 직접 한 줄 쓴다 — 체크박스 말고, 문장으로.
🛒 이 글과 어울리는 추천 상품
위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.