동료에겐 한 줄도 안 쓰던 문서, 왜 Claude한테는 술술 쓸까

개발자 사이에서 오래된 농담이 하나 있습니다. “문서? 코드가 곧 문서지.” 동료가 “이 함수 어떻게 쓰는 거예요?“라고 물으면 한숨부터 나오던 사람들이, 요즘은 AI한테 줄 문서를 밤새 다듬고 있습니다. 같은 손가락으로 말이죠. 이 묘한 풍경이 지금 개발 커뮤니티에서 자주 회자되는데요. 단순한 유머를 넘어, 우리가 왜 문서를 쓰고 왜 안 쓰는지에 대한 진짜 이유를 들춰냅니다.

먼저 솔직하게 말씀드릴 게 있습니다. 이번 주제는 최근 30일 사이 새로 달궈진 논쟁이라기보다, 개발 문화에 꾸준히 흐르는 오래된 아이러니에 가깝습니다. 그래서 특정 화제의 댓글 수를 들이밀기보다, 이 현상이 왜 벌어지는지를 차분히 뜯어보려 합니다.

CLAUDE.md라는 이름의 새로운 문서 문화

요즘 AI 코딩 도구를 쓰는 프로젝트를 열어보면 낯선 파일이 하나 보입니다. CLAUDE.md 같은 이름의 파일인데요. 프로젝트 구조, 코딩 규칙, 주의사항, 빌드 방법이 정성껏 정리돼 있습니다.

흥미로운 건 이겁니다. 정작 사람을 위한 README.md는 “TODO: 나중에 작성"으로 비어 있는 경우가 허다하다는 점이죠. 같은 저장소 안에서 한 문서는 빈약하고, 다른 문서는 풍성합니다.

왜일까요. AI 에이전트는 이 파일을 매번 읽습니다. 잘 쓰면 결과물이 즉각 좋아지고, 대충 쓰면 엉뚱한 코드를 뱉습니다. 피드백이 즉각적이라는 거죠. 반면 사람 동료를 위한 문서는 효과가 보일 때까지 몇 주, 몇 달이 걸립니다. 어쩌면 영영 안 보일 수도 있고요.

문서를 안 쓴 게 아니라, 보상이 없었던 겁니다

여기서 첫 번째 진실이 드러납니다. 개발자들이 문서화를 싫어한 게 아니었습니다. 보상 구조가 없었던 겁니다.

생각해보면 동료를 위한 문서는 보상이 참 인색합니다. 내가 한 시간 들여 정리해도, 그 동료가 안 읽으면 헛수고입니다. 읽어도 고맙다는 말 한마디로 끝나죠. 게다가 코드는 계속 바뀌는데 문서는 그대로라, 금방 거짓말쟁이가 됩니다. 차라리 슬랙으로 물어보라고 하는 게 효율적으로 느껴집니다.

그런데 AI한테 쓰는 문서는 다릅니다. 방금 쓴 규칙이 다음 응답에 바로 반영됩니다. 내가 들인 5분이 그 자리에서 더 나은 코드로 돌아옵니다. 즉각적이고 명확한 보상이 생긴 거죠. 인간은 결국 보상에 반응하는 동물입니다.

AI는 화내지 않고, 무시하지 않고, 평가하지 않는다

두 번째 진실은 조금 더 불편합니다. 사람을 위한 문서를 안 쓰는 데는 감정적 비용도 있었습니다.

동료에게 “이건 이렇게 쓰세요"라고 문서로 남기는 일은 묘하게 부담스럽습니다. 너무 자세히 쓰면 잔소리 같고, 대충 쓰면 성의 없어 보입니다. 내가 모르는 걸 들킬까 봐, 혹은 동료가 “이 정도는 나도 알아요"라고 생각할까 봐 신경 쓰입니다. 문서 하나에도 인간관계의 미묘한 정치가 끼어듭니다.

AI는 이 모든 걸 면제해 줍니다. 잔소리라고 삐지지 않고, 무시하지도 않고, 나를 평가하지도 않습니다. 그냥 시키는 대로 받아들입니다. 개발자가 가장 편하게 자기 생각을 글로 옮길 수 있는 상대가, 아이러니하게도 사람이 아닌 기계가 된 셈입니다.

그런데 이 문서들, 사람한테도 유용하다는 반전

여기서 진짜 재밌는 일이 벌어집니다. AI를 위해 쓴 CLAUDE.md를 새로 합류한 신입 동료가 열어봅니다. 그러고는 말합니다. “이거 제가 일주일 헤맬 내용이 다 정리돼 있네요.”

AI에게 설명하려면 어쩔 수 없이 맥락을 명시적으로 써야 합니다. “이건 다들 알겠지” 하고 넘어가던 암묵지를 전부 글로 풀어야 하죠. AI는 분위기 파악을 못 하니까요. 그렇게 쓰다 보면 결과적으로 사람에게도 가장 친절한 문서가 만들어집니다.

즉 우리는 “AI를 위한 문서"라는 핑계로, 사실은 그동안 미뤄왔던 제대로 된 문서화를 드디어 하고 있는 겁니다. 동기가 무엇이든, 결과물은 팀 전체의 자산이 됩니다.

마무리

결국 이 아이러니가 알려주는 건 단순합니다. 개발자는 문서화를 못 하는 게 아니라, 할 이유가 부족했을 뿐이라는 거죠. AI가 그 빠진 이유를 채워준 셈입니다. 보상은 즉각적으로, 부담은 0으로 만들어서요. 한 가지 질문을 남기고 싶습니다. AI한테 쓰던 그 정성의 절반만 옆자리 동료에게 돌린다면, 우리 팀의 협업은 얼마나 달라질까요. 어쩌면 가장 좋은 문서는, 사람과 AI 모두가 읽을 수 있는 문서가 아닐까요.