낡은 지침 문서를 정산해서 팀 신뢰 되찾기
목차
팀이 자라면서 문서는 자동으로 낡는다. 새 기술 스택이 들어오고, 배포 흐름이 바뀌고, 팀원이 늘어도 가이드는 그 자리에 남아있다가 언젠가 "이거 아직 유효한 거 맞나?" 같은 의심을 사게 된다. 이번에 CLAUDE.md 를 정산하면서 그 느낌을 강하게 받았다.
이전에 쌓인 여러 프로젝트 진행 방식, 구버전 도구 설정, 실제로는 바뀐 git 흐름까지 문서에 고스란히 남아 있었다. 팀원이 그걸 읽고 따라 하면? 최선의 경우 비효율적인 재작업, 최악의 경우 배포 실수까지 이어질 수 있다. 결국 신뢰도 떨어진다. "문서를 믿고 따랐는데 안 됐어요"라는 말은 기술 리더한테는 가장 아프다.
왜 문서 정산이 팀 규모 문제인가
팀이 1-2명일 땐 입으로 전달되던 것들이 5명 이상이 되면 문서화의 질이 직결된다. 신입이 올 때마다 "아, 이건 문서엔 이렇게 나와 있지만 실제론 저렇게 하세요"라는 예외 설명을 반복한다는 건, 그만큼 우리가 문서를 제대로 관리 못 하고 있다는 신호다. 그래서 이번 작업의 핵심은 두 가지였다.
첫째, 현실 대조. 서버 배포 도구의 버전이 올랐는데 가이드는 여전히 구버전 기준. 클론 동기화 절차가 3단계로 줄었는데 문서는 5단계. 이런 것들을 하나하나 실측하고 바꿨다. 내가 직접 따라 해보면서 "여기서 안 된다"는 부분들을 마킹하고, 실제 동작하는 플로우로 재작성했다.
둘째, 미래 설계 기록. 단순히 현재를 정정하는 것만으로는 부족하다. 앞으로 진행할 프로젝트들(새로운 디자인 패턴, 비교·분석 보드 같은 기획)을 문서에 미리 기록해 놨다. 그럼 팀원이 "이건 왜 이렇게 하지?" 할 때 문서를 보고 배경을 이해할 수 있다.
문서 정산의 세 가지 학습
이 과정에서 세 가지를 배웠다.
첫째, 문서는 선택이 아니라 부채다. 쓴 순간부터 유지비가 든다. 코드처럼. 버전 올라가면 리뷰하고, 흐름 바뀌면 갱신하고, 팀이 새 툴 도입하면 그것도 반영해야 한다. 그런데 기술 리더는 종종 이 비용을 과소평가한다. "문서는 나중에 정리하지 뭐"라는 식으로. 결과는 신뢰도 추락. 코드 리뷰와 문서 리뷰는 같은 무게여야 한다.
둘째, "현실이 단일진실"이라는 원칙이 얼마나 중요한가. 이전엔 "문서에 이렇게 나와 있으니까 이대로 하세요"라는 태도였다면, 지금은 "문서가 틀렸을 수 있으니 실제로 동작하는지 한 번 확인하고, 안 맞으면 문서를 바꾸세요"로 방향을 바꿨다. 이게 조직 문화 차원에서는 강력하다. 팀원이 주도적으로 개선할 수 있는 구조가 생기기 때문이다.
셋째, 부자연스러운 절차는 자동으로 외워지지 않는다. mac 클론에서 3중 동기화가 필요했던 이유는 특정 시점의 인프라 제약 때문이었는데, 그 배경을 문서에 안 썼다. 그래서 신입들은 "왜 이렇게 복잡해?"라고만 생각했다. 절차뿐 아니라 "왜"를 함께 기록하면, 나중에 그 제약이 사라질 때 자연스럽게 단순화할 수 있다.
다음 이터레이션을 위한 기록
앞으로 진행할 설계들도 문서에 미리 적어 놨다. "그린리뉴얼"이라는 디자인 시스템 개선, "비교보드" 같은 새 기능의 철학. 이렇게 해두면 팀원이 그걸 작업할 때 "왜 이 선택을 했나"를 빠르게 이해할 수 있다. 코드 리뷰 때도 "이건 우리 철학에 안 맞는데"라고 할 근거가 생긴다.
사실 이런 기록이 진짜 가치는 3개월 뒤에 드러난다. 당시 왜 그렇게 했는지 팀에서 깜빡했을 때, 문서를 보고 "아, 이 이유였구나" 하게 되니까. 그게 진짜 문화다.
결국 이번 커밋은 단순 문서 정산이 아니라, 팀이 자신의 의사결정을 기억하고 신뢰할 수 있는 구조를 만드는 일이었다. 코드는 실행되지만 문서는 생각을 담는다. 그 생각이 일관되고 정확하면, 팀이 더 빨리 움직인다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.