5. AEO - 코딩 에이전트가 읽는 문서는 왜 다른가

GEO 최적화 Guide — 전체 시리즈

1. 1. GEO란 무엇인가 - SEO 너머의 AI 인용 전략
2. 2. AI마다 인용하는 소스가 다르다
3. 3. On-Site GEO 기술 구조 - 상품 DB에서 JSON-LD까지
4. 4. Off-Site GEO - 공식 사이트를 안 보는 AI에게 선택받는 법
5. 5. AEO - 코딩 에이전트가 읽는 문서는 왜 다른가 ← 현재 글

AI가 읽는 문서는 한 종류가 아니다

4편 까지 On-Site와 Off-Site GEO를 정리했습니다. 공식 사이트의 JSON-LD, 외부 디렉토리, 커뮤니티 채널까지. 소비자가 ChatGPT나 Perplexity에 뭔가 물어볼 때 우리 브랜드가 인용 소스로 올라오게 하는 작업이었습니다.

그런데 AI가 읽는 문서가 이게 전부가 아닙니다.

개발자가 Claude Code나 Cursor한테 “이 API 연동해줘"라고 시키면, 에이전트가 혼자 API 문서를 크롤링합니다. 이때 에이전트가 문서를 처리하는 방식이 사람이 보는 페이지와 다릅니다.

이걸 AEO(Agentic Engine Optimization) 라고 부릅니다. 며칠 전에 정리된 개념 이라 국내에는 논의가 거의 없는데, GEO 하는 입장에서 한 번은 짚고 넘어갈 만합니다.

AEO와 GEO는 뭐가 다른가

같은 AI라도 누가 쓰느냐에 따라 최적화가 달라집니다.

겹치는 원칙도 있습니다. SSR 기반 서빙, robots.txt 점검, 구조화된 콘텐츠. 이 세 가지는 두 영역 모두에서 깔려야 합니다. GEO를 제대로 깐 조직은 AEO 진입 장벽이 낮습니다.

GEO는 “콘텐츠가 답변에 인용되느냐"를 봅니다. AEO는 “에이전트가 API를 제대로 쓰느냐"를 봅니다. 후자가 실패하면 아무도 모르는 사이에 잘못된 코드가 나갑니다.

에이전트는 사람처럼 문서를 읽지 않는다

사람이 개발자 포털에 도착하면 메뉴를 훑고, Getting Started를 클릭하고, 샘플 코드를 Run 해보고, 관련 링크 몇 개를 타고 들어가면서 4~8분 머뭅니다. 이 동작이 분석 도구에 전부 기록됩니다.

에이전트는 한두 번의 HTTP GET으로 페이지를 통째로 가져와서 파싱하고 끝냅니다. 스크롤도 클릭도 없습니다. GA에는 체류 시간 400ms짜리 요청 한 건만 남습니다.

서버 로그를 보면 User-Agent에서 가려낼 수 있습니다.

기존에 그냥 “알 수 없는 크롤러"로 묶이던 트래픽 중 상당수가 여기일 수 있습니다.

긴 문서는 에이전트가 끝까지 읽지 않는다

에이전트는 컨텍스트 제한이 있습니다. Claude나 GPT 계열이 보통 100K~200K 토큰 사이입니다. 문서 하나가 이 창을 넘거나 근접하면 에이전트가 조용히 다음 중 하나를 합니다.

• 뒷부분을 잘라먹습니다. 중요한 내용이 뒤에 있었다면 답변이 틀립니다
• 더 짧은 다른 문서로 넘어갑니다
• 청킹하다가 레이턴시만 늘고 오류가 납니다
• 포기하고 자기가 학습한 지식으로 답을 만듭니다. 이게 환각입니다

실제로 API 문서 하나가 10만 토큰을 넘는 케이스도 있습니다. 이쯤 되면 단일 문서가 에이전트 컨텍스트를 혼자 다 써버립니다.

그래서 문서 길이가 지표가 됩니다. 권장 기준은 이렇습니다.

GEO에는 이런 제약이 없습니다. 소비자용 AI는 필요한 스니펫만 뽑아가면 그만이기 때문입니다. AEO는 문서 전체가 컨텍스트에 들어가야 해서 길이 설계가 필요합니다.

파일 네 개로 시작한다

복잡한 기술 없이 파일 네 개 정도로 시작하면 됩니다.

먼저 robots.txt. 4편에서 다룬 것과 같은 파일인데, 코딩 에이전트 User-Agent도 같이 고려해야 합니다. 무심코 전체 차단이 걸려 있으면 에이전트가 문서를 아예 못 봅니다.

다음이 llms.txt. /llms.txt 위치에 Markdown으로 올리는 에이전트용 사이트맵입니다. 페이지 이름이 아니라 “여기 들어가면 뭘 알 수 있는지"를 설명합니다. 페이지별 토큰 수도 같이 적어두면 에이전트가 읽을지 말지 판단할 수 있습니다.

# MyService Documentation

## Getting Started
- [Quick Start](/docs/quickstart): 5분 안에 첫 API 호출 (8K tokens)
- [Authentication](/docs/auth): OAuth 2.0, API Key 인증 (12K tokens)

## API Reference
- [Users API](/docs/api/users): 유저 CRUD (12K tokens)
- [Events API](/docs/api/events): 이벤트 스트리밍, 웹훅 (8K tokens)

skill.md 는 서비스가 “무엇을 할 수 있는지"를 선언적으로 적는 파일입니다. 긴 문서를 다 안 읽어도 capability를 빨리 파악하게 해줍니다. What I can accomplish, Required inputs, Constraints, Key documentation 네 섹션이 기본 구성입니다.

마지막이 AGENTS.md. 프로젝트 루트에 두는 README의 에이전트 버전입니다. 코딩 에이전트가 프로젝트를 열면 가장 먼저 찾습니다. 오픈소스 쪽에서는 이미 깔고 시작하는 경우가 늘고 있습니다.

한국 기업 관점에서 AEO는 누구 얘기인가

솔직히 말해서 국내 대부분 기업은 AEO 1순위 대상이 아닙니다. 개발자 포털을 운영하는 회사가 많지 않습니다. 이커머스, 유통, 금융, 서비스업은 소비자용 GEO만 제대로 해도 효과가 훨씬 큽니다.

AEO를 진지하게 볼 만한 경우는 이런 곳입니다.

• API를 공개하는 회사: 결제 PG, 배송, 지도, 인증, 데이터 API 사업자. 개발자가 Cursor로 연동 코드를 짜는 게 이미 디폴트
• 내부 개발 플랫폼을 운영하는 대기업: 그룹 공통 API, 인증 게이트웨이, 사내 데이터 플랫폼 문서가 대상
• 오픈소스/개발자 도구: GitHub에 프로젝트를 공개하고 있다면 AGENTS.md는 거의 필수에 가까움
• MCP 서버 제공자: skill.md는 직결되는 컨벤션

내부 데이터 플랫폼을 에이전트에 붙이는 작업을 돌려봤는데, 막상 에이전트가 내부 위키와 메타데이터를 잘 못 읽어서 답이 엉망인 경우가 자주 나왔습니다. 이때 AEO 원칙 몇 개만 적용해도 결과가 달라집니다. 문서를 Markdown으로 제공하고, 토큰 수를 페이지에 박고, 네비게이션 노이즈를 걷어내는 것만으로 파싱 품질이 체감될 만큼 올랐습니다.

파일 네 개로 다 해결되는 건 아닙니다. 조직별 용어 차이나 부서별 암묵적 맥락은 여전히 남습니다. 이건 다른 차원 문제라 파일 설계만으로는 안 풀립니다.

GEO를 했다면 추가 비용은 크지 않다

이미 GEO를 구축했다면 이행 비용이 생각보다 작습니다. 겹치는 작업이 많습니다.

• robots.txt를 AI 크롤러 관점에서 재점검 (GPTBot, ClaudeBot, PerplexityBot 외에 코딩 에이전트 User-Agent도)
• 주요 문서 페이지별 토큰 수 계산 (글자 수 ÷ 4로 근사)
• /llms.txt 초안 작성. 주요 문서 목록과 토큰 수
• 상위 3~5개 API에 skill.md 작성
• 내부 GitHub 저장소에 AGENTS.md 배치
• 개발자 문서를 Markdown으로도 서빙. URL에 .md 붙이면 원본 반환하는 식
• 서버 로그에서 코딩 에이전트 트래픽 세그먼트 분리해서 baseline 잡기

robots.txt 재점검과 llms.txt 초안은 반나절이면 끝납니다. skill.md와 AGENTS.md도 상위 API 몇 개부터 돌리면 부담이 크지 않습니다.