개발자는 동료보다 AI를 위해 문서를 작성한다
프로그래머들이 동료를 위해 문서화하는 것을 꺼리면서도, AI 코딩 어시스턴트인 Claude를 위해서는 상세한 문서를 기꺼이 작성하는 아이러니한 현상을 다룬 글입니다. 저자는 Claude를 사용하며 세션 간의 맥락을 전달하기 위해 작성했던 인계 문서를 버리지 않고 저장소에 커밋하는 방식을 통해, 시간을 크게 절약하면서도 고품질의 프로젝트 개요를 얻을 수 있었다고 설명합니다. 이는 AI 도구를 활용해 개발자가 평소 하기 힘들어하는 문서화를 효율적으로 해결한 훌륭한 실무 사례입니다.
며칠 전 저는 흔히 하는 불평 하나를 이야기했습니다.
"사람들이 Claude가 사용하도록 상세한 CLAUDE.md와 PROJECT.md 파일은 기꺼이 작성하면서, 왜 자기 동료들을 위해서는 그렇게 하지 않는지 분노하다는 프로그래머들의 이야기를 계속 봅니다."
규모가 큰 프로젝트의 경우, 저는 Claude가 인계 문서(handoff document)를 유지하도록 하여 다음 Claude 세션이 읽을 수 있게 만드는 방식을 택했습니다. 이 문서에는 우리가 무엇을 계획했는지, 무엇이 완료되었는지, 그리고 기타 관련 정보가 담겨 있습니다. 따라서 하나의 Claude 세션을 종료할 때, 다음 Claude가 이 파일을 읽고 프로젝트의 진행 상황을 빠르게 파악할 수 있습니다. 그런 다음 Claude n+1이 Claude n+2를 위해 이 문서를 업데이트하도록 하는 식입니다.
이러한 흔한 불평을 여러 번 접한 후, 저는 번뜩이는 깨달음을 얻었습니다. 저는 프로젝트가 끝날 때마다 Claude의 인계 문서를 버리고 있었습니다. 굳이 그럴 필요가 있을까요? 해당 파일을 리포지토리(repository)에 복사하여 커밋(commit)하는 것은 아주 간단합니다. 나중에 상황을 이해하고자 하는 누군가가 git grep을 통해 운 좋게 올바른 문서를 찾아 유용한 정보를 얻을 수도 있을 것입니다.
저도 이해력이 좀 느린 편이라서, 이것보다 더 나은 방법을 떠올리기까지 이번 주까지 기다려야 했습니다. 이제 프로젝트가 끝나면 Claude에게 처음부터 새로 작성하도록 요청합니다. 우리가 어떤 문제를 해결했고 어떤 변경 사항이 있었는지에 대한 자세하면서도 높은 수준의(high-level) 설명을 만들어 내라고 한 뒤, 저는 그것을 커밋합니다. 단순히 진행 중인 메모가 아니라, 프로젝트 전체에 대한 체계적인 개요인 셈입니다.
저는 이러한 개요를 커밋하기 전에 꼼꼼히 검토하고 필요한 부분은 수정합니다. 커밋에는 제 서명이 들어가고, 제 통장으로 급여가 들어오는 만큼, Claude가 제 감독 하에 있는 인간 프로그래머라면 마찬가지였을 것처럼 제가 주의 깊게 읽고 이해하지 못한 내용은 결코 리포지토리에 들어가지 않습니다.
하지만 Claude의 설명은 그다지 많은 수정을 필요로 하지 않았습니다. Claude의 가장 최근 프로젝트 요약은 제가 직접 쓴 것과 거의 비슷한 수준이었습니다. 어쩌면 조금 못할 수도, 어쩌면 조금 더 나을 수도 있었습니다. 하지만 이를 작성하는 데는 1시간이 아니라 단 10초밖에 걸리지 않았고, 검토하는 데도 1시간이나 걸리지는 않았습니다.
지난번에 제가 직접 수정해야 했던 심각한 문제는, Claude가 이전의 관련 보고서를 모델로 삼아 새 문서를 작성했다는 점이었습니다. 그 이전 보고서의 마지막에는 제가 추가했던 다음과 같은 단락이 있었습니다:
"이 노트는 Claude가 해당 이슈에 관한 우리의 논의를 바탕으로 요약한 것입니다. Mark Dominus가 이 노트를 읽고, 검토하고, 편집했으며 승인했습니다."
그랬더니 Claude의 새 문서에도 마지막에 똑같은 문구가 들어 있었습니다. 이런! 다행히 제가 이를 발견했을 때 이 문구가 사실이었기 때문에(실제로 제가 읽고 검토한 내용이 맞았으므로) 삭제할 필요가 없었습니다.