8년 된 문서 프레임워크가 2026년에 부활한 이유: 이제 문서는 사람이 안 읽습니다

요즘 개발자 커뮤니티에 좀 이상한 일이 있습니다. 2017년에 나와서 한 번 유행하고 지나간 문서 작성 프레임워크가 다시 상위권에 올라옵니다. 이름은 Diátaxis. 그런데 이번에 이걸 다시 꺼내든 이유가 묘합니다. 문서를 잘 쓰자는 게 아닙니다. AI가 문서를 잘 읽게 하자는 겁니다.

미리 밝혀둘 게 있습니다. 이 주제로 최근 30일치 커뮤니티 데이터를 뒤졌는데 건질 만한 스레드가 거의 없었습니다. 그래서 이 글은 실시간 반응을 정리한 것이라기보다 Diátaxis라는 프레임워크와 지금 개발 현장의 변화를 엮어 읽어본 쪽에 가깝습니다. 감안하고 봐주세요.

Diátaxis가 뭐길래

Diátaxis는 Django 문서 팀에서 오래 일한 다니엘레 프로카이다(Daniele Procida)가 정리한 문서 분류 체계입니다. 얼개는 간단합니다. 기술 문서는 딱 네 종류뿐이라는 겁니다.

• 튜토리얼(Tutorial): 처음 온 사람이 손을 움직여 뭔가를 만들어보는 학습용 문서
• How-to 가이드: 이미 아는 사람이 특정 문제를 해결하려고 찾는 실무용 문서
• 레퍼런스(Reference): API 목록, 설정값, 파라미터 같은 사실의 나열
• 설명(Explanation): 왜 이렇게 설계했는지, 배경과 맥락을 다루는 문서

중요한 건 네 칸으로 나눈다는 게 아니라 절대 섞지 말라는 규칙입니다. 튜토리얼 한복판에 “참고로 이 옵션은 이런 것도 있고요"라며 레퍼런스를 끼워 넣는 순간 초보자는 길을 잃습니다. 레퍼런스에 설계 철학을 늘어놓으면 급한 사람은 원하는 값을 못 찾고요.

프로카이다는 이걸 두 축으로 설명합니다. 하나는 “실무 중심이냐 이론 중심이냐”, 다른 하나는 “학습 중일 때냐 일하는 중일 때냐”. 두 축을 교차시키면 사분면이 나오고 각 칸이 위 네 문서에 맞아떨어집니다. 개발자들이 이 프레임워크를 좋아한 이유가 여기 있습니다. 두루뭉술한 조언이 아니라 지금 쓰는 문서가 어느 칸인지 바로 판정할 수 있는 도구거든요.

왜 하필 지금 다시 뜨는가

이 프레임워크는 2020년 전후에 한 차례 크게 유행했습니다. Django, Gatsby, Cloudflare 같은 곳이 문서를 뜯어고쳤고요. 그러다 “좋은 이야기지만 현실에서는 지키기 어렵다"는 쪽으로 정리되면서 잠잠해졌습니다.

판을 바꾼 건 코딩 에이전트입니다. 2025년을 지나면서 Claude Code, Cursor 같은 도구가 실무에 자리 잡았습니다. 이제 라이브러리 문서를 제일 많이 읽는 쪽은 사람이 아닙니다. 에이전트는 작업을 받으면 문서를 통째로 긁어 읽고 필요한 조각을 추려 코드를 씁니다.

문제는 여기서 터집니다. 사람은 문서가 좀 뒤죽박죽이어도 눈으로 훑으면서 “이건 예시고 저건 실제 API구나” 하고 알아서 걸러냅니다. 에이전트는 그 필터가 약합니다. 튜토리얼용 샘플 코드를 프로덕션 설정으로 착각합니다. 설명 문서에 나온 “이렇게 하면 안 됩니다” 예시를 그대로 베껴오기도 하고요. 문서에 장르가 섞여 있을 때 제일 크게 손해 보는 독자가 AI입니다.

Diátaxis가 8년 전부터 주장한 “섞지 마라"는 사람한테 권장 사항이었습니다. 에이전트한테는 정확도 문제입니다.

llms.txt와 문서의 두 번째 얼굴

이 흐름에서 같이 나오는 게 llms.txt입니다. robots.txt가 크롤러에게 길을 알려주듯 LLM에게 “이 사이트에서 뭘 어디서 읽으면 되는지"를 알려주는 파일입니다. 문서 사이트 상당수가 이걸 붙이기 시작했습니다.

그런데 막상 llms.txt를 만들어보면 곧바로 벽에 부딪힙니다. 링크 목록을 정리하려면 각 문서가 무슨 성격인지 스스로 답할 수 있어야 하거든요. “이 페이지는 시작하는 사람용인가, 참조용인가?” 여기에 답이 안 나오는 문서 구조라면 llms.txt도 쓸모없는 링크 더미가 됩니다.

AI용 문서를 따로 만드는 게 아니라 원래 문서부터 제대로 정리해야 한다는 얘기가 됩니다. 문서 담당자들 이야기도 비슷합니다. AI 대응한다고 새 포맷을 뽑는 것보다 있는 문서에서 장르 섞인 부분을 걷어내는 쪽이 효과가 큽니다.

반론도 만만치 않습니다

물론 모두가 동의하는 건 아닙니다. 반박은 크게 세 갈래입니다.

첫째, 사람은 사분면으로 검색하지 않는다는 지적입니다. 실제 사용자는 “How-to 섹션을 봐야지"라고 생각하지 않고 그냥 에러 메시지를 검색창에 붙여넣습니다. 네 칸으로 갈라놓으면 궁금증 하나 풀자고 세 페이지를 왔다 갔다 하는 일이 생깁니다.

둘째, 유지 비용입니다. 같은 기능을 네 종류로 쓰면 기능이 바뀔 때 네 군데를 고쳐야 합니다. 인력이 넉넉한 조직이 아니면 한두 칸은 방치됩니다. 낡은 문서만 남아 되레 해를 끼치고요.

셋째는 좀 더 근본적인 반문입니다. 에이전트가 문맥을 알아서 파악하는 능력은 계속 좋아지는 중입니다. 그런데 지금 AI 읽기 편하라고 문서 구조를 뒤엎는 게 몇 년 뒤에도 유효하냐는 겁니다. 오늘의 모델 약점에 맞춰 조직 프로세스를 짜는 건 위험하다는 시각이죠.

셋 다 일리가 있습니다. 다만 앞의 둘은 Diátaxis를 교조적으로 적용했을 때 생기는 문제에 가깝습니다. 프로카이다 본인도 이걸 규격이 아니라 나침반이라고 표현했습니다. 네 칸을 물리적 디렉터리로 강제하라는 게 아니라 지금 쓰는 문단이 어느 성격인지 자각하라는 쪽에 무게가 있습니다.

그래서 뭘 하면 되나

문서 전체를 거창하게 갈아엎을 필요는 없습니다. 효과 큰 순서대로 보면 이렇습니다.

README, 아니 가장 많이 읽히는 문서 한 페이지를 열어보세요. 그 안에 설치법, 사용 예시, 옵션 표, 설계 배경이 뒤엉켜 있다면 거기가 첫 번째 수술 대상입니다. 최소한 “따라 하는 부분"과 “찾아보는 부분”만 갈라놔도 사람이든 에이전트든 체감이 달라집니다.

그다음은 예시 코드에 라벨 붙이기입니다. “이건 학습용 최소 예시”, “이건 프로덕션 권장 설정"처럼 한 줄만 덧붙여도 에이전트가 잘못 베껴 쓰는 사고가 줄어듭니다. 사람한테도 도움이 되고요.

레퍼런스에서 잡담을 걷어내는 것도 효과가 좋습니다. 파라미터 표 안에 “저희는 이 설계를 오래 고민했는데요” 같은 문장이 섞여 있다면 설명 문서로 보내야 할 내용입니다.

마무리

Diátaxis가 다시 화제가 된 건 프레임워크가 갑자기 좋아져서가 아닙니다. 문서의 독자가 바뀌었기 때문입니다. 사람은 어수선한 문서도 어떻게든 읽어냈습니다. 에이전트는 그게 안 됩니다. 그 대가는 잘못된 코드로 돌아옵니다.

찜찜한 대목이 하나 남습니다. 지금 문서를 정리하는 이유가 사람을 위해서인지, AI에게 잘 보이려는 건지 헷갈릴 때가 있습니다. 아직은 두 방향이 대체로 겹치니 다행입니다. 언젠가 갈라지는 순간이 오면 어느 쪽을 고를지 저는 자신이 없습니다. 여러분 팀의 문서는 지금 어느 사분면에 걸쳐 있나요.