The Myth of the Post-Documentation Era
There is a growing sentiment in engineering circles right now that documentation is a relic of the...
개요 #
요즘 엔지니어링 커뮤니티에서 심심찮게 나오는 말이 있다. "이제 문서화는 한물간 일 아니냐"는 것이다. 논리는 대략 이렇다. 우리는 에이전트가 개발을 주도하는 시대에 살고 있고, AI가 소스 코드나 OpenAPI 명세를 순식간에 읽어낼 수 있는데 굳이 사람이 시간을 들여 산문을 쓸 이유가 있느냐는 거다. 게다가 코드는 너무 빨리 바뀌니까, 사람이 쓴 문서는 커밋되는 순간 이미 낡은 것이 된다는 주장이다.
Dev.to 창업자 Ben Halpern은 이 깔끔해 보이는 흑백논리에 정면으로 반박한다. 결론부터 말하면, 틀렸다는 것이다. 소스 오브 트루스(source of truth)에서 완벽한 결정론을 좇는 건 애초에 불가능한 꿈이다. 코드와 명세는 시스템이 어떻게(how) 동작하는지는 말해주지만, 왜(why) 그렇게 만들어졌는지는 근본적으로 설명하지 못한다.
코드가 메우지 못하는 '의도의 간극' #
설령 당신이 오로지 AI 에이전트를 위한 시스템을 만든다 해도, 원시 API 명세와 실제 운영 현실 사이에는 구조적으로 큰 틈이 벌어져 있다.
에이전트는 패턴 매칭과 문법 실행에는 놀라운 능력을 보이지만, 아키텍처 철학과 인간의 의도 앞에서는 여전히 헤맨다. 명세는 엔드포인트와 파라미터, 페이로드까지는 정의할 수 있다. 그러나 특정 아키텍처 트레이드오프를 왜 그렇게 결정했는지, 레거시 예외 케이스에 얽힌 역사적 맥락이 무엇인지는 담아내지 못한다. 이 경계의 뉘앙스를 설명하려면 결국 말과 글이 필요하다.
산문은 비결정론적 시스템에 가드레일을 세워준다. 그 글을 최종적으로 읽는 쪽이 사람이 아니라 기계라 하더라도, 의도를 전달하는 가장 효율 높은 수단은 여전히 글이다.
쓰레기가 쓰레기를 설명하는 위험 #
물론 이 말이 예전처럼 거대한 정적 위키 페이지를 손으로 관리하던 시절로 돌아가자는 뜻은 아니다. 자동화는 여기서 큰 역할을 한다. 코드 변경과 함께 문서가 동적으로 생성되는 이른바 '캐스케이딩 자동화'는 상당히 강력하다.
그런데 여기에 함정이 하나 있다. 쓰레기가 쓰레기를 설명하는 상황은 완전히 무용지물이라는 것이다.
문서 생성을 검증 없는 LLM에 통째로 넘겨버리면, 환각으로 만들어진 맥락이 빠르게 변하는 코드를 설명하는 피드백 루프에 빠진다. 명료함이 아니라 소음만 쌓인다.
핵심은 감독이다. 문서가 전부 봇으로 생성되더라도, 사람 엔지니어의 감독은 타협할 수 없는 조건이다. 생성된 산문이 넓은 맥락을 정확하고 높은 수준에서 설명하고 있는지 직접 검증하고 확인해야 한다. 자동 생성 문서는 API의 비결정론적 사촌쯤으로 생각하면 된다. 대단히 가치 있지만, 고삐를 바짝 쥐고 있을 때에만 그렇다.
신뢰의 위기, 그리고 평판 시스템이라는 숙제 #
지금 이 새로운 패러다임을 가로막는 가장 큰 장애물은 신뢰다. 문서가 믿을 만한지 직관적으로 판단할 지표가 없다는 점이, 사람 개발자에게든 자율 에이전트에게든 큰 병목으로 작용한다.
과거 오픈소스 시대에는 거칠지만 나름 효과적인 평판 대리 지표가 있었다. 어떤 저장소에 깃허브 스타가 1만 개 붙어 있고, 이슈 트래커가 활발하며, 최근 커밋이 꾸준하다면, 그 프로젝트와 문서가 안정적이라고 어느 정도 믿을 수 있었다.
문제는 AI 시대에는 아직 이런 평판 시스템이 없다는 것이다. 지금 이 순간이 완전히 새로운 데다, 자동화된 지표는 조작하기가 너무 쉽다. 그래서 모든 게 어딘가 붕 떠 있는 느낌이다.
Halpern은 개발자 도구의 다음 큰 변화가 단순히 에이전트를 더 빠르게, 코드 생성을 더 깔끔하게 만드는 데 그치지 않을 거라고 본다. 진짜 변화는 평판 문제를 푸는 데서 온다. 소프트웨어가 기대는 지식 베이스의 신뢰도를 자동으로 검증하고, 점수 매기고, 보증하는 시스템을 만드는 일이다.
그때가 오기 전까지는, 마크다운 파일을 지우지 말자. 기계도 여전히 행간을 읽어야 하니까.
이 글은 위 출처를 바탕으로 한국 독자를 위해 재작성한 기사입니다. 원문의 사실과 수치에 근거하며, 별도의 견해를 포함하지 않습니다.