배포 브랜치에 머지되는 순간, 문서 관리도 시작되어야 한다

이 글은 내가 만들고 있는 문서 형상관리 시스템, Harness Docs에 대한 시리즈의 첫 번째 글이다.

이번 글에서는 이 시스템이 어떻게 동작하는지보다, 왜 이 프로젝트를 시작하게 되었는지를 먼저 정리하려고 한다. 문서가 왜 자꾸 stale해지는지, 왜 그 문제를 사람의 책임감에만 맡기면 안 된다고 생각하게 됐는지, 그리고 왜 배포 브랜치에 머지되는 순간을 문서 관리의 시작점으로 보게 됐는지를 이야기하려 한다.

내가 만들고 있는 것은 소규모 팀을 위한 문서 형상관리 시스템이다. 하네스 위에서 돌아가고, 코드 변경과 문서 변경을 따로 떨어진 일이 아니라 하나의 운영 흐름으로 다루는 것을 목표로 한다. 어떤 문서가 stale 후보인지 판단하고, upstream과 downstream 문서의 연결을 추적하고, 알림을 보내고, 수정이 필요한 상태를 드러내고, 문서를 쓰는 과정에서는 AI의 도움까지 받을 수 있게 하려 한다.

이 프로젝트를 시작한 이유는 거창하지 않다. 아주 단순하게 말하면, 문서는 너무 자주 낡고, 팀은 그 사실을 너무 늦게 알아차리기 때문이다.

온보딩하면서 느낀 문제는 문서의 부재보다 최신성의 부재였다

입사하고 나서 온보딩을 하면서 가장 크게 느낀 어려움은 제품의 스펙이 문서보다 코드에 더 많이 숨어 있다는 점이었다.

물론 코드의 퀄리티를 높이는 일은 여전히 중요하다. 코드가 명확할수록 시스템의 실제 동작을 이해하기 쉬워지고, 제품을 파악하는 데도 큰 도움이 된다. 문제는 코드가 제품을 이해하기 위한 거의 유일한 출처가 되어버릴 때다. 그 상태에서는 구현을 읽을 수 있어야만 제품을 이해할 수 있고, 코드의 퀄리티가 충분히 높지 않다면 그 비용은 훨씬 더 커진다.

이때 힘든 것은 단순히 문서가 부족하다는 사실만이 아니다. 더 큰 문제는, 문서가 있어도 그 문서가 지금 믿을 수 있는 상태인지 알기 어렵다는 데 있다.

문서가 stale해졌다는 사실은 생각보다 눈에 잘 띄지 않는다. 코드는 수정되고 배포되는데, 관련 문서는 그대로 남아 있다. 시간이 지나면 문서는 존재하지만, 읽는 사람 입장에서는 늘 한 번 더 의심해야 하는 대상이 된다. 정말 이 설명이 지금도 맞는지, 이 흐름이 아직도 유효한지, 여기 적힌 전제가 최근 변경 이후에도 유지되는지 다시 확인해야 한다.

그러면 문서는 이해를 돕는 자산이 아니라, 검증 비용이 붙는 힌트가 된다. 온보딩하는 사람에게 이건 꽤 큰 문제다. 제품을 빠르게 이해해야 하는 시점에, 믿을 수 있는 최신 정보가 어디 있는지부터 다시 찾아야 하기 때문이다.

내가 풀고 싶었던 문제는 결국 "문서가 없어서 힘들다"에만 머물지 않았다. 더 정확하게는 "무엇을 믿어야 하는지 알기 어려운 상태가 팀을 계속 느리게 만든다"는 문제였다.

사람끼리 알리고 리뷰하는 문화만으로는 문서가 유지되지 않았다

문서가 stale해지는 문제를 이야기하면 보통 해결책은 익숙한 방향으로 나온다. 변경이 생기면 서로 알려주고, 리뷰할 때 문서도 같이 보자고 말하고, 문서가 바뀌어야 하면 각자 책임감을 갖고 업데이트하자는 식이다.

이 접근이 완전히 틀렸다고 생각하지는 않는다. 실제로 어느 정도는 필요하다. 하지만 실무를 여러 번 겪으면서 더 분명하게 느낀 것은, 문서 작성은 대부분의 사람에게 본업의 중심이 아니라는 점이다. 문서가 중요하지 않아서 안 쓰는 게 아니다. 중요하다는 걸 알아도, 급한 일과 비교하면 늘 뒤로 밀린다. 구현, 대응, 배포, 일정, 협업이 먼저 오고, 문서는 늘 "곧 해야 하는 일"이 된다.

그래서 문서 관리를 사람의 자율적인 책임에만 기대는 방식은 구조적으로 흔들릴 수밖에 없다.

실제로 내가 본 방식도 그랬다. 사람끼리 알림을 주고받고, 리뷰 문화로 보완하려고 했지만 정보는 같은 직군끼리만 공유되기 쉬웠다. 어떤 시스템이 있는지, 무엇이 어디에 연결되어 있는지, 누가 어떤 맥락을 알고 있는지는 팀 전체 관점에서 보이지 않았다.

특히 상위 문서가 바뀌었을 때 하위 문서도 함께 바뀌어야 한다는 것은 누구나 이해한다. 하지만 그 연결 관계가 시스템으로 관리되지 않으면 결국 누락된다. 시간이 지나면 문서는 쌓이는데, 그 문서들이 서로 어떤 영향을 주고받는지는 아무도 자신 있게 설명하지 못하는 상태가 된다.

문제는 사람들이 게을러서가 아니다. 변경의 전파를 사람이 기억에 의존해서 관리해야 하는 구조 자체가 이미 불리한 것이다.

그래서 문서 관리의 시작점을 사람의 기억이 아니라 코드 이벤트에 붙이고 싶었다

이 지점에서 생각이 바뀌었다.

문서 유지보수는 좋은 습관이나 성실함의 문제로만 다뤄지면 안 된다. 문서가 실제 운영에 필요하다면, 문서의 최신성도 운영 흐름 안에 들어와야 한다. 누군가 나중에 기억해서 고치는 방식이 아니라, 변경이 발생하는 순간 시스템이 반응하는 방식이어야 한다.

그래서 내가 세운 기준은 꽤 단순하다. 코드가 배포 브랜치에 머지되는 순간, 문서 관리도 시작되어야 한다는 것이다.

이 시점이 중요한 이유는 실제로 팀의 상태를 바꾸는 변경이 그 순간 일어나기 때문이다. 기능이 추가되거나, 규칙이 바뀌거나, 동작 방식이 달라지는 것은 결국 코드가 머지되고 배포 가능한 상태가 되는 시점과 연결된다. 그렇다면 문서도 그 이벤트를 기준으로 관리되어야 한다. 그래야 문서 업데이트가 "아, 이것도 써야 하지"가 아니라 "이 변경이 일어났으니 관련 문서 상태도 다시 평가해야 한다"가 된다.

내가 만들고 있는 시스템은 바로 이 지점에서 출발한다. 배포 브랜치에 코드가 머지되면 시스템은 다음 질문을 던져야 한다.

• 어떤 문서가 stale 후보인가
• 어떤 upstream 문서와 downstream 문서가 영향을 받는가
• 누구에게 알려야 하는가
• 어떤 문서가 수정이 필요한 상태인가
• 사람이 문서를 다시 쓰기 시작하도록 무엇을 도와줘야 하는가

핵심은 자동화 그 자체가 아니다. 핵심은 문서 관리의 시작점을 사람의 기억에서 코드 이벤트로 옮기는 것이다.

문서는 파일의 집합이 아니라 연결된 운영 시스템이어야 한다

문서 관리가 어려운 이유 중 하나는, 많은 팀이 문서를 각각의 독립된 결과물처럼 다루기 때문이다. 하지만 실제로 문서는 거의 항상 연결되어 있다.

상위 수준의 제품 문서가 바뀌면, 하위 수준의 운영 문서나 구현 문서도 영향을 받는다. 정책 문서가 바뀌면 사용자 가이드가 바뀔 수 있고, 어떤 구조에 대한 설명이 달라지면 관련된 온보딩 자료도 손봐야 할 수 있다. 그런데 이 연결이 명시적으로 관리되지 않으면, 상위 문서의 변경은 그 문서 안에서만 끝나고 만다. 그 뒤에 따라 바뀌어야 하는 문서들은 각자 알아서 챙겨야 하는 숙제가 된다.

나는 이게 문서 관리가 실패하는 아주 큰 이유라고 본다.

문서가 stale해지는 건 한 파일을 누가 안 고쳐서 생기는 문제가 아니다. 어떤 변경이 어떤 문서들에 영향을 주는지, 그 전파 관계를 시스템이 전혀 추적하지 않기 때문에 생기는 문제다. 그래서 이 프로젝트에서는 문서를 쓰는 기능 자체보다, 문서 사이의 upstream과 downstream 관계를 관리하는 것이 더 중요하다.

문서를 많이 남기는 것보다 먼저 필요한 것은, 무엇이 무엇에 영향을 주는지를 드러내는 일이다.

소규모 팀일수록 문서 최신성을 시스템으로 다뤄야 한다

이 시스템을 소규모 팀에 맞춰 생각하게 된 이유도 여기에 있다.

큰 조직은 전담 역할을 두거나 별도의 운영 체계를 유지할 여지가 상대적으로 크다. 하지만 소규모 팀은 대부분의 사람이 동시에 여러 역할을 맡는다. 구현도 해야 하고, 운영도 봐야 하고, 협업도 풀어야 한다. 그런 환경에서는 문서가 더 쉽게 부수적인 일로 밀린다.

그런데 소규모 팀일수록 문서가 없거나 믿기 어려울 때 받는 타격은 더 크다. 사람이 적기 때문에 정보가 특정 개인의 머릿속에 더 많이 쌓이고, 문서가 그 공백을 메워주지 못하면 팀 전체 이해 속도가 느려진다. 새로 합류한 사람이 제품을 파악하는 시간도 길어지고, 이미 있는 사람들 사이에서도 "그건 저 사람이 더 잘 안다"는 식의 의존이 커진다.

결국 소규모 팀에 필요한 것은 거대한 지식관리 솔루션이 아니라, 변경을 놓치지 않게 하는 운영 메커니즘이다. 문서를 잘 쓰자는 합의보다 먼저 필요한 것은, 문서가 낡아졌다는 신호가 시스템적으로 드러나게 만드는 일이다.

AI는 문서를 대신 쓰는 존재보다, 다시 쓰기 시작할 수 있게 만드는 보조여야 한다

이 프로젝트에 AI 지원을 넣으려는 이유도 같은 맥락에 있다.

많은 경우 문서를 안 쓰는 이유는 필요성을 몰라서가 아니다. 시작 비용이 크기 때문이다. 무엇을 써야 하는지, 어디까지 반영해야 하는지, 어떤 표현으로 정리해야 하는지 막막해서 미뤄진다. 특히 변경이 복잡하거나 연결된 문서가 많을수록, "일단 나중에 하자"가 되기 쉽다.

그래서 시스템은 단순히 알림만 보내서는 부족하다고 생각했다. "이 문서가 stale 후보입니다"라고 알려주는 것만으로는 사람의 부담이 충분히 줄지 않는다. 어떤 변경이 있었는지, 왜 이 문서가 영향을 받는지, 어디부터 고치면 되는지까지 이어져야 한다.

AI는 그 과정에서 초안 작성, 변경 요약, 반영 포인트 제안 같은 방식으로 문서 작성의 진입 비용을 낮출 수 있다. 중요한 건 AI가 문서 관리를 마법처럼 해결해준다는 기대가 아니라, 사람들이 문서를 다시 쓰기 시작할 수 있게 돕는 인터페이스가 되는 것이다.

내가 만들고 싶은 것은 문서 저장소가 아니라 문서 운영 시스템이다

이 프로젝트를 시작하게 된 이유를 한 문장으로 줄이면 이렇다.

문서는 중요하다고 모두가 말하지만, 실제 운영에서는 너무 쉽게 stale해지고, 그 문제를 사람의 자율성에만 맡겨서는 해결되지 않는다고 느꼈기 때문이다.

그래서 나는 문서 관리를 별도의 선행 과제가 아니라, 코드 변경 이후 반드시 반응해야 하는 시스템의 일부로 만들고 싶었다. 배포 브랜치에 머지되는 순간을 기준으로 문서 상태를 다시 평가하고, 문서 간 연결을 추적하고, 필요한 변경을 드러내고, 실제 작성까지 돕는 흐름을 만들고 싶었다.

내가 만들고 싶은 것은 문서를 많이 쌓아두는 저장소가 아니다. 변경이 생겼을 때 어떤 문서를 다시 봐야 하는지 놓치지 않게 만드는 운영 시스템이다.

문서가 좋은 팀은 문서를 사랑하는 팀이 아니라, 문서가 낡아졌다는 사실을 시스템적으로 놓치지 않는 팀이라고 생각한다. 이 프로젝트는 그 전제를 실제 도구로 만들고 싶어서 시작했다.

다음 글에서는 이 생각을 조금 더 구체적으로 풀어보려고 한다. 내가 왜 문서의 최신성 문제를 stale 판단으로 다루게 되었는지, 그리고 upstream과 downstream 관계를 어떤 기준으로 보고 있는지를 정리해보겠다.