사람한테는 안 쓰던 문서를, AI한테는 쓴다고요? 'AI가 바꾼 개발 문화'에 대한 뼈 때리는 이야기

어쩐지 뜨끔한 이야기

개발하면서 우리가 제일 안 하는 일 중 하나가 뭘까요? 바로 문서화(documentation)예요. "코드만 깔끔하면 됐지, 주석이나 README는 나중에 쓰지 뭐" 하다가 결국 안 쓰고 넘어가는 거, 다들 한 번쯤 해보셨죠? 동료가 "이 함수 뭐 하는 거예요?" 물어봐도 "아 그거 코드 보면 알아요" 하고 넘기던 우리인데요.

그런데 신기한 일이 벌어지고 있어요. 똑같은 개발자가 Claude나 ChatGPT 같은 AI 코딩 도구를 쓰기 시작하니까, 갑자기 문서를 쓰기 시작했다는 거예요. AI한테 "이 프로젝트는 이런 구조이고, 이 함수는 이렇게 써야 하고, 이런 규칙을 지켜줘" 하고 친절하게 설명을 적어주기 시작한 거죠. 사람 동료한테는 그렇게 인색하던 설명을, AI한테는 술술 써주는 이 아이러니. 이게 바로 이번 글의 핵심이에요.

왜 이런 일이 벌어질까요

곰곰이 생각해 보면 이유가 보여요. 사람한테 문서를 안 쓰는 이유는 "써봤자 안 읽잖아" 또는 "물어보면 그때 답해주면 되지"라는 마음 때문이거든요. 즉, 문서를 쓰는 비용은 지금 당장 내가 내는데, 그 혜택은 미래의 누군가(어쩌면 나조차도 아닌)가 가져가니까 동기부여가 안 되는 거예요.

그런데 AI는 달라요. 내가 지금 적어준 설명을, AI가 바로 다음 순간 읽고 반영해서 더 나은 코드를 뱉어주거든요. 그러니까 문서화의 보상이 즉각적이에요. CLAUDE.md 파일에 "우리 프로젝트는 탭 대신 스페이스 4칸을 써"라고 한 줄 적으면, 바로 그 규칙대로 코드가 나와요. 비용과 보상 사이의 시차가 사라진 거죠. 사람은 "읽어줄까 말까" 불확실하지만, AI는 "무조건 읽고 즉시 반영"하니까 손이 가는 거예요.

여기서 재밌는 통찰이 나와요. 그동안 우리가 문서화를 안 했던 건 게을러서가 아니라, 보상 구조가 잘못 설계되어 있었기 때문이라는 거예요. 동기부여가 약했던 거지, 능력이 없던 게 아니란 거죠.

그래서 뜻밖의 좋은 일이 생겨요

여기서 한 가지 놀라운 부수 효과가 있어요. AI를 위해 적어둔 문서가, 결국 사람한테도 도움이 된다는 거예요. CLAUDE.md나 프로젝트 설명 파일에 "이 모듈은 이런 역할이고, 이 부분은 이렇게 동작한다"고 적어두면, 새로 합류한 동료가 그 파일을 읽고 프로젝트를 빠르게 이해할 수 있거든요. AI 주려고 쓴 문서가 사람한테도 선물이 되는 거죠.

이건 좀 역설적이에요. 우리가 "사람을 위해 문서를 쓰자"고 아무리 외쳐도 안 되던 일이, "AI한테 일을 잘 시키자"는 이기적인(?) 동기에서 출발하니까 자연스럽게 이뤄진 거예요. 좋은 습관을 만드는 건 의지력이 아니라 올바른 보상 설계라는 걸 보여주는 사례예요.

업계 흐름에서 보면

요즘 AI 코딩 도구들이 다 이 방향으로 가고 있어요. Claude Code는 CLAUDE.md, Cursor는 .cursorrules, GitHub Copilot도 프로젝트별 지침 파일을 읽어요. 이런 파일들의 공통점은 "AI가 우리 프로젝트의 맥락을 이해하도록 사람이 미리 설명을 적어두는 곳"이라는 거예요. 이걸 요즘은 컨텍스트 엔지니어링(context engineering)이라고 부르기도 해요. AI한테 어떤 배경 정보를 줘야 좋은 결과가 나오는지를 설계하는 일이죠.

흥미로운 건, 이 흐름이 결국 '코드 옆에 항상 살아있는 문서를 두는' 오래된 이상을 실현시키고 있다는 점이에요. 예전엔 위키나 컨플루언스에 문서를 따로 두니까 코드랑 따로 놀고 금방 낡았는데, 이제는 문서가 코드 레포 안에, AI가 매번 읽는 위치에 있으니까 자연스럽게 최신 상태로 유지돼요.

한국 개발자에게

당장 해볼 수 있는 게 있어요. 여러분 프로젝트에 CLAUDE.md나 README를 열고, AI한테 설명하듯이 "이 프로젝트의 구조, 코딩 규칙, 자주 쓰는 명령어"를 적어보세요. 신기하게도 AI 주려고 쓴 그 문서가, 3개월 뒤의 여러분 자신과 새 팀원한테 큰 도움이 될 거예요. 'AI를 잘 쓰는 사람'이 되려는 노력이 곧 '문서를 잘 남기는 사람'이 되는 길이 된 거죠.

마무리

핵심은 이거예요. 사람은 보상이 즉각적일 때 좋은 습관을 들인다. AI가 우연히 그 보상 구조를 만들어줬고, 덕분에 우리는 드디어 문서를 쓰기 시작했어요. 여러분은 AI를 위해 문서를 쓰면서, '사람을 위한 문서'에 대한 생각이 바뀌셨나요? 혹시 AI한테는 친절하면서 동료 PR 리뷰엔 한 줄만 남기고 있진 않나요?