잘 만드는 팀은 왜 문서를 먼저 쓸까

개발을 하다 보면 문서의 중요성에 대한 이야기를 자주 듣게 된다.

요구사항 문서,
기술 문서,
설계 문서,
회고 문서.

좋은 팀일수록 문서를 잘 관리한다고 말한다.

그런데 솔직히 말하면 예전의 나는 문서가 왜 그렇게 중요한지 명확하게 설명하지 못했다.

문서를 작성한다고 해서 기능이 더 빨리 만들어지는 것도 아니고,
사용자가 늘어나는 것도 아니고,
매출이 오르는 것도 아니다.

코드를 작성하면 눈에 보이는 결과물이 생기지만 문서는 그렇지 않다.

그래서 누군가

문서를 작성하면 뭐가 좋은데?

라고 물어보면 선뜻 답하기 어려웠다.

문서의 가치를 증명하기 어려웠다

개발자는 보통 결과물로 이야기한다.

배포된 기능,
해결된 버그,
개선된 성능.

이런 것들은 비교적 측정하기 쉽다.

반면 문서는 그렇지 않다.

문서를 작성했다고 해서 당장 눈에 띄는 변화가 생기지는 않는다.

오히려 작성하는 시간만큼 개발이 늦어지는 것처럼 보이기도 한다.

그래서 나 역시 문서의 필요성을 강하게 주장하기보다는 그냥 습관처럼 작성하는 편이었다.

좋다고는 느끼고 있었지만 왜 좋은지 명확하게 설명할 수는 없었다.

그래도 계속 기록했다

문서를 작성하는 이유는 거창하지 않았다.

그냥 까먹기 싫었다.

왜 이런 의사결정을 했는지,
왜 특정 라이브러리를 선택했는지,
어떤 문제를 겪었는지.

그 순간에는 당연하게 느껴지지만 몇 달만 지나도 기억은 흐려진다.

그래서 요구사항을 정리했고,

구현 전에 생각한 내용을 적었고,

작업이 끝난 뒤에는 간단하게 회고를 남겼다.

- 왜 이 기능이 필요한가
- 어떤 방법을 검토했는가
- 어떤 선택을 했는가
- 예상했던 문제는 무엇인가
- 실제로 발생한 문제는 무엇인가

처음에는 개인 메모에 가까웠다.

누군가 읽기를 기대하고 작성한 문서는 아니었다.

시간이 지나고 나서 가치가 보였다

문서의 진짜 가치는 나중에 나타났다.

몇 달 전에 작성했던 문서를 다시 읽게 된 적이 있었다.

당시에는 단순한 기록이라고 생각했는데 생각보다 많은 정보가 남아 있었다.

왜 그렇게 구현했는지,
어떤 고민을 했는지,
어떤 실수를 했는지.

이미 한 번 고민했던 문제를 다시 고민하지 않아도 됐다.

특히 장애나 버그를 다시 마주쳤을 때 도움이 많이 됐다.

기억은 흐려졌지만 기록은 남아 있었기 때문이다.

그때 처음으로 문서가 미래의 나를 위한 투자라는 생각을 하게 됐다.

문화는 설득보다 경험으로 만들어졌다

더 흥미로웠던 것은 다른 사람들의 변화였다.

내가 작성한 문서를 참고하는 동료가 생겼다.

회고를 읽고 비슷하게 기록하기 시작한 사람도 있었다.

어떤 의사결정을 했는지 문서로 남아 있으니 질문도 줄어들었다.

사실 문서화를 해야 한다고 적극적으로 설득한 적은 별로 없다.

오히려 반대였다.

문서의 장점을 설명하는 것보다 실제로 도움이 되는 경험을 만드는 것이 더 효과적이었다.

누군가 문서를 읽고 도움을 받으면 다음에는 본인도 기록하게 된다.

그런 경험들이 하나씩 쌓이면서 자연스럽게 문화가 만들어졌다.

돌아보면 문서 문화는 제도로 만든 것이 아니라 사례로 만들어진 것에 가까웠다.

AI 시대일수록 더 중요해지는 것

최근에는 AI 덕분에 구현 속도가 정말 빨라졌다.

예전보다 코드를 작성하는 시간은 분명 줄어들고 있다.

하지만 무엇을 만들어야 하는지,
왜 만들어야 하는지,
어떤 문제를 해결하려는지는 여전히 사람이 정의해야 한다.

오히려 구현 비용이 낮아질수록 문제 정의의 가치가 커진다고 생각한다.

그리고 그 과정은 대부분 문서로 남는다.

좋은 문서는 사람뿐 아니라 AI에게도 좋은 컨텍스트가 된다.

최근 프로젝트에서 CLAUDE.md 같은 문서를 관리하기 시작한 이유도 비슷하다.

결국 구현보다 중요한 것은 맥락이고,
문서는 그 맥락을 보존하는 가장 단순한 방법이다.

마무리

돌아보면 문서는 개발 속도를 높이기 위해 작성한 것이 아니었다.

그저 잊지 않기 위해 남긴 기록이었다.

하지만 시간이 지나고 보니 그 기록은 의사결정을 공유하게 만들었고,
비슷한 실수를 줄여줬고,
팀의 공통된 맥락을 만드는 역할을 하고 있었다.

지금도 문서의 가치를 숫자로 증명하긴 어렵다.

다만 한 가지는 확실하다.

좋은 문서는 작성하는 순간보다 다시 읽는 순간에 더 큰 가치를 만든다.

그리고 그런 기록들이 쌓이면서 결국 팀의 문화가 되는 것 같다.