당신의 API 문서는 AI에게 읽히고 있습니다. 그런데 AI가 읽지 못하고 있을 수도 있습니다.

보이지 않는 독자들

이상한 일이 벌어지고 있습니다. 개발자 문서의 트래픽은 줄지 않았는데, 페이지 체류 시간이 급락하고, 스크롤 깊이는 0이고, 튜토리얼 완료율은 바닥입니다. 구글 애널리틱스를 아무리 들여다봐도 원인이 안 보입니다.

원인은 간단합니다. 문서를 읽는 주체가 바뀌었습니다. 사람이 아니라 AI 에이전트가 읽고 있는 겁니다. 클로드 코드가, 커서가, 에이더가 당신의 문서를 GET 요청 한 번으로 가져가서 400밀리초 만에 처리합니다. 스크롤도, 클릭도, 링크 이동도 없습니다. 당신의 퍼널에는 아무것도 찍히지 않습니다.

문제는 그다음입니다. 에이전트가 문서를 가져갔을 때, 그 문서가 잘 구조화되어 있으면 작업이 성공합니다. 그렇지 않으면 에이전트는 조용히 지어냅니다. 당신의 API를 잘못 호출하는 코드가 전 세계 개발자의 프로젝트에 심어지는데, 당신은 그 사실을 알 방법이 없습니다.

구글의 애디 오스마니가 이 문제에 이름을 붙였습니다. AEO, Agentic Engine Optimization. 우리가 SEO를 배웠던 것처럼, 이제 AI 에이전트를 위한 최적화를 배워야 할 때라는 겁니다.

SEO를 기억하시나요

2000년대 중반, 웹사이트를 만들면 끝이라고 생각하던 시절이 있었습니다. "좋은 콘텐츠를 만들면 사람들이 알아서 찾아온다." 틀린 말은 아니었지만, 현실은 달랐습니다. 검색 엔진이 사이트를 크롤링하고, 인덱싱하고, 순위를 매기는 방식을 이해하지 못하면, 아무리 좋은 콘텐츠도 검색 결과 3페이지에 묻혔습니다.

그래서 SEO를 배웠습니다. 메타 태그를 달고, 사이트맵을 만들고, robots.txt를 관리하고, 페이지 로딩 속도를 최적화했습니다. 콘텐츠의 본질이 바뀐 건 아닙니다. 실제 소비자(검색 엔진)가 어떻게 콘텐츠를 소비하는지에 맞춰 포장을 바꾼 겁니다.

AEO는 정확히 같은 논리입니다. 소비자만 다릅니다. 검색 엔진 크롤러 대신 AI 코딩 에이전트. 클릭 패턴 대신 토큰 경제. 사이트맵 대신 llms.txt.

에이전트는 당신이 생각하는 것과 완전히 다르게 읽습니다

사람은 문서 홈페이지에 도착해서, 메뉴를 탐색하고, 제목을 훑고, 코드 샘플을 실행해보고, 링크를 따라가며 4~8분을 보냅니다. 이 모든 과정이 클라이언트 사이드 이벤트로 잡힙니다.

에이전트는 HTTP 요청 한두 번으로 끝냅니다. 사람이 5분 동안 클릭하며 돌아다닐 문서 계층을, GET 요청 하나에 전부 받아갑니다. '사용자 여정'이라는 개념이 서버 로그의 한 줄로 축소됩니다. 스크롤, 체류 시간, 버튼 클릭, 튜토리얼 진행률 같은 지표가 전부 무의미해집니다.

연구 데이터에서 각 에이전트의 HTTP 핑거프린트도 확인됐습니다. 클로드 코드는 axios/1.8.4, 커서는 got, 클라인은 curl/8.4.0이라는 식별자를 남깁니다. 서버 로그를 보면 AI 트래픽이 이미 얼마나 많은지 확인할 수 있습니다. 대부분의 팀이 이 데이터를 갖고 있으면서도 분류하지 않고 있을 뿐입니다.

19만 토큰짜리 문서는 존재하지 않는 것과 같습니다

에이전트가 문서를 가져갔을 때, 가장 먼저 하는 일이 토큰을 세는 겁니다. 대부분의 에이전트는 실질적으로 10만~20만 토큰 사이에서 작동합니다.

시스코의 방화벽 API 퀵스타트 가이드가 193,217토큰입니다. 이 문서 하나가 에이전트의 컨텍스트 윈도우 전체를 먹습니다. 에이전트 입장에서 이 문서는 읽을 수 없는 문서입니다. 조용히 잘라버리거나, 아예 건너뛰거나, 대충 아는 것으로 때우거나. 전부 나쁜 결과입니다.

토큰 수가 문서의 접근성을 결정하는 1급 지표가 된 겁니다. SEO에서 페이지 로딩 속도가 검색 순위에 영향을 미쳤던 것과 같습니다. 느린 페이지가 검색에서 밀리듯, 무거운 문서는 에이전트에게 무시당합니다.

실무적인 가이드라인은 이렇습니다. 퀵스타트 페이지는 15,000토큰 이하. API 레퍼런스 페이지는 25,000토큰 이하. 개념 가이드는 20,000토큰 이하로, 세부 내용은 별도 페이지로 분리해서 링크합니다. 토큰 수 계산은 글자 수를 4로 나누면 대략적인 추정치가 나옵니다.

에이전트에게 지도를 주는 세 가지 파일

SEO에 사이트맵과 robots.txt가 있었듯, AEO에도 에이전트를 안내하는 파일 체계가 생기고 있습니다.

robots.txt — 출입문. 에이전트가 가장 먼저 확인합니다. 여기서 AI 크롤러가 차단되어 있으면, 문서가 아무리 좋아도 에이전트는 접근조차 못 합니다. 트래픽 감소도 에러 메시지도 없이, 그냥 보이지 않게 됩니다. 의도치 않게 앤트로픽, 오픈AI, 구글, 퍼플렉시티 크롤러를 막고 있는 경우가 실제로 있습니다. 10분이면 확인할 수 있는 작업인데, 이 10분을 안 써서 문서 전체가 AI에게 투명인간이 되는 겁니다.

llms.txt — AI용 사이트맵. 도메인 루트에 놓는 마크다운 파일입니다. 문서의 구조를 에이전트에게 알려줍니다. 어떤 페이지에 무엇이 있고, 각 페이지가 몇 토큰인지. 에이전트가 사이트 전체를 크롤링하지 않고도 필요한 문서를 정확히 찾을 수 있게 하는 안내판입니다. llms.txt 자체는 5,000토큰을 넘지 않아야 합니다. 안내판이 안내 대상보다 무거우면 안 됩니다.

skill.md — 능력 선언서. llms.txt가 "문서가 어디 있는지"를 알려준다면, skill.md는 "이 제품이 무엇을 할 수 있는지"를 선언합니다. 에이전트가 산문형 문서를 전부 읽지 않고도, 이 API가 자기 작업에 적합한지 먼저 판단할 수 있습니다. 컨텍스트 예산을 쓰기 전에 필터링이 가능해지는 겁니다.

콘텐츠 자체를 에이전트 친화적으로 만드는 법

파일 체계를 갖추면 발견은 됩니다. 하지만 발견된 콘텐츠가 에이전트가 소화할 수 있는 형태여야 합니다.

마크다운을 제공합니다. HTML을 벗기면 태그, 네비게이션, 사이드바, 푸터가 전부 노이즈입니다. 마크다운으로 바로 접근할 수 있게 하면 토큰 오버헤드가 극적으로 줄어듭니다. URL 뒤에 .md를 붙이면 원본 마크다운에 접근할 수 있게 하는 플랫폼이 늘고 있습니다.

처음 500토큰에 핵심을 넣습니다. 이 페이지가 무엇이고, 무엇을 할 수 있고, 시작하려면 무엇이 필요한지. 에이전트는 배경 설명에 참을성이 없습니다. 사람도 마찬가지이긴 합니다만, 에이전트는 물리적으로 앞부분에 가중치를 더 둡니다.

테이블을 씁니다. 파라미터 레퍼런스를 산문으로 쓰면 토큰을 많이 소모합니다. 같은 정보를 테이블로 정리하면 토큰 효율이 훨씬 좋습니다.

"AI용 복사" 버튼을 넣습니다. 개발자가 IDE에서 AI 어시스턴트를 쓸 때, 문서를 복사 붙여넣기합니다. 렌더링된 HTML을 복사하면 네비게이션, 푸터, 광고가 딸려옵니다. 깨끗한 마크다운을 클립보드에 넣어주는 버튼 하나면, 에이전트가 받는 컨텍스트 품질이 확 달라집니다. 앤트로픽과 클라우드플레어가 이미 이 기능을 탑재했습니다.

AGENTS.md가 새로운 README입니다

README.md가 사람 개발자의 진입점이었다면, AGENTS.md가 AI 에이전트의 진입점이 되고 있습니다. 코딩 에이전트가 프로젝트를 열면, 루트의 AGENTS.md를 읽고 이후 모든 작업의 지침으로 삼습니다.

시스코 데브넷은 이미 깃허브 오픈소스 템플릿에 AGENTS.md를 기본 포함시켰습니다. 새 프로젝트를 만들면 프로젝트 구조, API 문서 링크, 테스트 환경, 코딩 컨벤션이 미리 채워진 AGENTS.md가 따라옵니다.

이건 개발 문화의 변화를 보여줍니다. 프로젝트를 시작할 때 "사람이 읽을 문서"만 만드는 시대가 끝나고 있습니다. "AI가 읽을 문서"를 함께 만드는 것이 기본이 되어가고 있습니다.

이것이 개발자와 PM에게 의미하는 것

AEO는 기술 문서 담당자만의 일이 아닙니다.

API를 만드는 개발자에게. 당신의 API 문서가 에이전트에게 읽히지 못하면, 에이전트는 경쟁사의 API를 대신 추천합니다. SEO에서 검색 순위가 곧 트래픽이었듯, AEO에서는 에이전트 접근성이 곧 개발자 채택률이 됩니다.

PM에게. "개발자 경험(DX)"의 정의가 확장되고 있습니다. 사람 개발자의 경험뿐 아니라, AI 에이전트의 경험까지 포함해야 합니다. 에이전트가 문서를 성공적으로 소화해서 올바른 코드를 생성하는 것이 새로운 DX 지표입니다.

창업자에게. AI 에이전트가 추천하는 API가 되는 것이 곧 시장 점유율의 새로운 동력입니다. 에이전트가 당신의 API를 잘 이해하고, 성공적으로 연동하고, 다시 돌아오게 만드는 것. 이건 마케팅이 아니라 문서 구조의 문제입니다.

실행 가능한 첫 걸음

대단한 인프라 투자가 필요한 게 아닙니다. 시작은 간단합니다.

robots.txt를 열어서 AI 크롤러가 차단되어 있는지 확인합니다. 10분이면 됩니다. llms.txt를 만들어서 도메인 루트에 놓습니다. 몇 시간이면 충분합니다. 주요 문서 페이지의 토큰 수를 측정하고, 30,000토큰을 넘는 페이지를 분리합니다. 핵심 API 3개에 대해 skill.md를 작성합니다. 서버 로그에서 AI 에이전트 트래픽을 분류하기 시작합니다.

SEO가 그랬듯, 먼저 움직이는 사람이 유리합니다. 그리고 SEO가 그랬듯, 에이전트를 위해 최적화하면 사람에게도 문서가 더 좋아집니다. 구조가 명확하고, 군더더기가 없고, 핵심이 앞에 오는 문서. 에이전트와 사람 모두에게 좋은 문서의 조건은 놀랍도록 비슷합니다.