개발 문서를 가장 많이 읽는 쪽이 사람에서 AI agent(사용자를 대신해 스스로 판단하고 작업을 처리하는 AI)로 넘어가고 있습니다. 개발 문서 플랫폼 Mintlify에서는 지난 1년 사이 전체 트래픽 가운데 AI agent의 비중이 약 15%에서 약 80%로 뛰었습니다. 사람의 브라우저에서 곧바로 들어오는 요청은 이제 약 20%뿐입니다. 그런데 Mintlify CEO의 처방은 문서를 agent용으로 갈아엎으라는 것이 아닙니다. 사람이 읽기 좋은 문서를 기본으로 두고, agent를 위한 기능은 그 위에 얹으라는 것입니다. 그 이유와 함께 API와 개발 도구를 만드는 팀이 지금 문서를 어떻게 손봐야 하는지 정리합니다.
1년 만에 뒤집힌 문서 트래픽
Mintlify는 2만 곳이 넘는 회사의 개발 문서와 지식 베이스를 서비스하고, 이 사이트들을 찾는 방문자는 한 달에 1억 명이 넘습니다. 이만한 규모에서 나타난 변화라 가볍게 넘기기 어렵습니다.
| 항목 | 수치 |
|---|---|
| Mintlify가 문서를 맡은 회사 | 2만 곳 이상 |
| Mintlify 기반 사이트의 월 방문자 | 1억 명 이상 |
| 1년 전 AI agent 트래픽 비중 | 약 15% |
| 현재 AI agent 트래픽 비중 | 약 80% |
| 사람의 브라우저에서 오는 요청 | 약 20% |
agent 비중이 80%에 이르렀다는 것은 문서의 주된 독자가 누구인지부터 다시 물어야 한다는 뜻입니다. Mintlify CEO는 이 변화가 소프트웨어 회사가 제품을 구상하고 만드는 방식을 근본부터 바꾼다고 봅니다.
다만 사람 독자가 줄어든 것은 아닙니다. agent 트래픽이 급격히 느는 동안 문서 사이트를 찾는 사람의 절대 수도 함께 늘었습니다. 기술 분야에 새로 들어오는 개발자가 어느 때보다 많아, 사람을 위한 교육·설명 자료의 수요도 여전합니다. 비중이 줄었을 뿐 사람 독자층은 계속 커지고 있는 셈입니다.
▲ 늘어나는 agent와 사람 방문자
agent만 보고 문서를 바꾸면 생기는 일
80%라는 숫자만 보면 사람용 안내서는 접고 agent가 읽을 원문만 내놓고 싶어질 수 있습니다. 극단적으로는 문서를 거대한 Markdown 파일 하나로 두고 채팅 창으로만 묻게 하는 방식입니다. Mintlify CEO는 이런 대응을 흔한 과잉 반응으로 보고 경계합니다.
실제로 agent 전용이나 채팅 전용 문서를 내놓은 제품에서는 사람이 제품의 능력을 쉽게 가늠하지 못했습니다. 그 뒤로는 이런 연쇄가 이어집니다.
- 개발자가 문서를 훑어보며 무엇을 할 수 있는 제품인지 판단하지 못합니다.
- 제품을 써 보지 않고, 동료에게 권하지도 않습니다.
- Reddit, 개발자 포럼, 블로그에 긍정적인 언급이 쌓이지 않습니다.
- 이런 글을 근거로 도구를 고르는 AI agent도 그 제품을 추천하지 않습니다.
agent는 스스로 취향을 갖고 도구를 고르지 않습니다. 학습 데이터와 검색 색인을 거쳐 걸러진 사람 개발자 커뮤니티의 평가를 반영할 뿐입니다. 그래서 GEO(생성형 검색 최적화, AI의 답변과 추천에 제품이 오르도록 하는 일)도 결국 사람 개발자의 마음을 얻는 데 달려 있다는 것이 Mintlify CEO의 시각입니다.
agent가 누구를 위해 일하는지도 따져 볼 대목입니다. agent는 독립적인 경제 주체가 아니라 사람을 대신해 움직입니다. agent가 일을 잘하려면 사람이 먼저 무엇을 물어야 하고 어떻게 지시해야 하는지 알아야 합니다. agent가 내놓은 결과를 믿으려면 사람이 직접 확인할 수 있는 출처와 근거도 필요합니다. 생성형 AI가 나온 뒤에도 사람들이 책을 읽고 웹사이트를 둘러보듯, 사람용 문서도 사라지지 않는다는 설명입니다.
코드는 agent가, 인프라 선택은 사람이
AI 코딩 agent가 맡는 일과 사람이 쥐고 있는 일을 나눠 보면 문서가 누구를 설득해야 하는지가 더 분명해집니다.
| 구분 | 예 | 맡는 쪽 |
|---|---|---|
| 낮은 수준의 구현 | 반복되는 기본 코드, API 호출 코드, 세세한 문법 | AI 코딩 agent가 상당 부분 자동화 |
| 높은 수준의 결정 | Supabase, ClickHouse, AWS 가운데 무엇을 쓸지 같은 핵심 인프라 선택 | 사람 개발 책임자가 최종 판단 |
인프라 선택에는 비용 약정, 성능의 득실, 장기적인 사업 결과가 걸려 있어 사람이 마지막 판단을 놓지 않습니다. Mintlify CEO는 Anthropic의 Claude 팀을 비롯한 최전선 AI 연구소 팀들의 피드백도 같다고 전합니다. agent는 돈이 드는 결정이나 중요한 약속이 걸린 순간에 여전히 사람의 판단을 구한다는 것입니다.
앱의 뼈대를 만드는 단계에서는 업체 선택이 이미 사람의 눈에서 멀어지고 있습니다. Lovable 같은 앱 제작 서비스는 어떤 데이터베이스를 쓸지 뒤에서 알아서 정하곤 합니다. Supabase를 붙이고 요금도 한데 묶어 청구하는 식입니다. Claude Code에 GitHub 같은 외부 계정을 연결하지 않고 앱을 만들어 달라고 하면 바로 접속할 수 있는 Vercel 주소에 배포까지 마치기도 합니다. agent는 미리 정해 둔 지시문과 실행 환경에 따라 특정 업체를 고르는 경우가 많습니다.
그래도 Mintlify CEO는 개발 플랫폼이 이름 없는 부품으로 완전히 가려지지는 않을 것으로 봅니다. 시제품이 팀 단위나 기업용 프로젝트로 커지면 사람이 직접 사용을 결정하고 Vercel 같은 호스팅 업체의 결제 계정을 만들어야 하기 때문입니다. 상용 소프트웨어에는 비용을 책임질 주체와 업체에 대한 신뢰가 필요합니다. 앞으로 agent에 지출 한도를 정한 디지털 지갑을 맡기면 이 단계마저 건너뛸 수 있을지 모르지만, 적어도 지금은 사람이 결정하는 구간이 분명히 남아 있습니다.
agent가 잘 읽는 문서의 조건
Mintlify를 찾는 개발팀은 문서를 agent가 읽기 좋게 만드는 복잡한 구조적 묘수를 묻곤 합니다. Docusaurus 같은 기존 문서 도구로 만든 문서를 agent가 제대로 읽지 못할까 걱정하는 팀도 있습니다. Mintlify CEO의 답은 단순합니다. 더 좋은 문서를 쓰라는 것입니다.
근거는 agent가 문서를 읽는 방식에 있습니다. LLM(대규모 언어 모델)과 agent는 사람 개발자와 근본적으로 같은 방식으로 기술 정보를 읽고 이해합니다. 차이는 훨씬 빠르게, 훨씬 많이 읽는다는 점입니다. 그래서 agent도 맥락 단서, 직관적인 목차 구조, 분명한 개념 구성을 따라 API 문서를 탐색합니다.
반대로 문서를 거대한 JSON 파일이나 정리되지 않은 코드 저장소째로 넘기는 방식은 역효과를 냅니다. Mintlify의 연구에서는 크고 구조 없는 문서, 관리되지 않은 문서, 중간에 잘린 문서를 통째로 넣으면 잘 나뉜 문서를 줄 때보다 agent 성능이 크게 떨어졌습니다. agent가 내용을 덜 이해하고, 없는 코드를 지어내는 hallucination(그럴듯하지만 틀린 내용을 만드는 현상)도 늘어납니다.
llms.txt(대규모 언어 모델이 읽기 좋게 사이트 내용을 정리해 두는 파일)나 MCP(Model Context Protocol, AI 모델을 외부 도구·데이터와 연결하는 표준) 서버 같은 장치도 쓸모는 있지만 만능 해법은 아닙니다. 내용이 틀렸거나 빠졌거나 낡았다면 이런 장치로는 메울 수 없습니다.
| 피할 것 | 대신 할 것 |
|---|---|
| 문서 전체를 거대한 Markdown이나 JSON 파일 하나로 내놓기 | 주제별로 나누고 목차 구조를 분명히 하기 |
| 코드 전체를 그대로 agent에 넘기기 | 정리된 문서와 검증한 코드 예제 건네기 |
| llms.txt와 MCP 서버만 갖추면 된다고 여기기 | 내용이 정확하고 최신인지 먼저 확인하기 |
| 채팅 창으로만 묻게 하기 | 사람이 훑어볼 빠른 시작 안내와 시각 자료 두기 |
▲ 통째로 넘긴 자료와 정리된 문서
문서는 agent가 쓰고, 사람은 방향을 잡는다
문서를 쓰는 쪽도 바뀌고 있습니다. 지난 1년 동안 개발팀이 업데이트, 새 SDK(소프트웨어 개발 도구 모음), API 변경을 유례없이 빠르게 내놓으면서 기술 문서 작성자가 손으로 문서를 최신 상태로 유지하기는 사실상 불가능해졌습니다. 그 빈자리를 AI agent가 문서의 초안 작성자이자 관리자로 채우고 있습니다.
그렇다고 기술 문서 작성자나 DevRel(개발자 관계, 개발자에게 제품을 알리고 쓰도록 돕는 일) 담당자가 필요 없어지는 것은 아니라는 것이 Mintlify CEO의 시각입니다. 코드는 쓰인 그대로만 동작하기 때문에 제품의 의도와 전체 시스템 설계는 사람이 풀어 줘야 합니다. agent가 문서를 대량으로 읽어 사용자의 앱을 만드는 만큼, 제품이 어떻게 동작하는지, SDK를 어떻게 연동하는지, 어떤 경우에 쓰는지 분명히 전하는 일은 오히려 더 중요해졌습니다.
사람의 역할은 문장을 한 줄씩 쓰는 일에서 방향을 잡는 일로 옮겨 갑니다.
- 고객 사례를 골라 정리하기
- 예외 상황(edge case)을 정의하기
- agent가 만든 결과물의 방향을 지시하기
Mintlify CEO는 앞으로 1년 안에 문서 작업이 지금보다 훨씬 자동화되고, 사람은 감독과 방향 설정을 맡게 될 것으로 내다봅니다. Mintlify도 agent가 코드 저장소를 지켜보다 변경을 감지하면 엔지니어에게 확인 질문을 던지는, 스스로 갱신되는 문서 기능을 만들고 있습니다. 모호한 코드 변경이 생길 때마다 정확한 질문을 던져 배포된 소프트웨어와 문서를 맞춰 두려는 것입니다.
문서 팀이 지금 할 일
agent가 문서의 최대 독자가 됐어도 좋은 문서의 기준은 크게 바뀌지 않았습니다. 사람이 읽기 좋은 문서가 agent에게도 좋은 문서이고, 사람 개발자의 추천이 agent의 추천으로 이어지기 때문입니다. API나 개발 도구를 만드는 팀이라면 다음 여섯 가지를 점검해 볼 수 있습니다.
- 사람이 제품을 빨리 평가할 수 있게 빠른 시작 안내, 시각 자료, 검증한 코드 예제를 갖춥니다.
- 문서를 주제별로 나누고 목차 구조와 맥락 단서를 분명히 합니다. 사용 사례와 SDK 연동 단계도 명시합니다.
- 내용이 정확하고 최신인지 먼저 확인한 뒤 llms.txt와 MCP 서버 같은 agent용 기능을 얹습니다.
- 출처와 참고 자료를 분명히 남겨 사람이 agent의 결과를 확인할 수 있게 합니다.
- Reddit, 개발자 포럼, 블로그에서 사람 개발자의 지지를 얻는 일에 계속 공을 들입니다.
- 초안 작성과 갱신은 agent에 맡기고, 사람은 제품의 의도와 고객 사례, 예외 상황을 정하는 데 힘을 씁니다.
트래픽의 80%가 agent라는 숫자는 문서를 기계용으로 바꾸라는 신호라기보다, 문서의 품질이 사람과 agent 양쪽의 선택을 함께 좌우한다는 신호로 읽는 편이 자연스러워 보입니다.