AI 코딩 에이전트가 문서를 읽는 방식은 인간과 근본적으로 다르다. 아직도 인간 독자만을 위한 최적화에 머물고 있다면, 점점 비중이 커지는 에이전트 독자층은 당신의 도구 밖에서 보이지 않는 존재로 남게 된다. Docs, CLI, MCP, Skills까지 — AI 에이전트가 상호작용하는 인터페이스 생태계는 이미 넓게 펼쳐져 있다.
개발자 포털에서 벌어지고 있는 한 가지 흐름이 눈에 띈다. 아직 충분한 주목을 받지 못하고 있지만, 분명히 짚고 넘어갈 필요가 있다.
엔지니어가 Claude Code를 열고 스펙 구현을 요청한 뒤 엔터를 친다. 에이전트는 문서 일부를 가져온다. 필요한 내용을 취하고, 원시 텍스트로 파싱하고, HTML을 걷어내고, 토큰 수를 센다. 그리고 컨텍스트로 활용하거나 — 토큰 수가 컨텍스트 윈도우를 초과한다면 — 조용히 버린다.
애널리틱스에는 아무것도 남지 않는다. 스크롤 깊이는 0, 페이지 체류 시간은 400밀리초. 링크 클릭도, 튜토리얼 완료도, UI 인터랙션도 없다. 몇 년에 걸쳐 최적화해온 퍼널에는 아무런 신호도 잡히지 않는다.
하지만 에이전트는 분명히 거기 있었다. 문서를 읽었다. 그리고 그 문서가 어떻게 구조화되어 있느냐에 따라, 작업을 성공적으로 완료하거나 — 콘텐츠가 지나치게 무겁거나, 구조가 엉성하거나, 잘못 설정된 robots.txt에 막혀 — 그럴듯한 오답을 지어낸다.
이 문제를 다루는 분야를 나는 에이전틱 엔진 최적화라고 부르기 시작했다.
에이전틱 엔진 최적화 (AEO)란 기술 콘텐츠를 AI 코딩 에이전트가 실제로 활용할 수 있도록 구조화하고, 포맷을 맞추고, 제공하는 실천이다 — 인간 독자만을 위한 것이 아니라.
가장 자주 떠오르는 비유는 SEO다. 우리는 수년에 걸쳐 검색 크롤러와 인간의 클릭 패턴에 맞게 콘텐츠를 최적화하는 법을 익혔다. AEO는 같은 발상이지만, 소비자가 다르다. 콘텐츠를 자율적으로 가져오고, 파싱하고, 추론하는 AI 에이전트가 그 대상이다.
중요한 요소들은 꽤 구체적이다:
robots.txt 설정이 AI 트래픽을 실제로 통과시키고 있는가?이 중 하나라도 문제가 생기면, 에이전트는 콘텐츠를 아예 건너뛰거나 미묘하게 틀린 결과를 내놓는다. 골치 아픈 점은, 어떤 애널리틱스 이벤트도 발생하지 않아 대부분 알아차리기조차 어렵다는 것이다.
여기서 행동 방식의 차이를 명확히 짚어둘 필요가 있다. 처음 예상했던 것보다 훨씬 크기 때문이다.
인간 개발자는 문서 홈페이지에 도착해 관련 섹션으로 이동한다. 제목을 훑고, 몇 단락을 읽고, 인터랙티브 콘솔에서 코드 샘플을 실행해보고, 내부 링크 두세 개를 따라가며 4~8분을 보낸다. 애널리틱스는 이 모든 행동을 기록한다.
최근 발표된 연구 논문(Developer Experience with AI Coding Agents)은 Claude Code, Cursor, Cline, Aider, VS Code, Junie 등 주요 AI 코딩 에이전트 9개가 개발자 문서를 가져오는 HTTP 트래픽을 분석했다. 결과는 꽤 충격적이었다.
에이전트는 일반적으로 여러 페이지에 걸친 탐색을 한두 번의 HTTP 요청으로 압축한다. 인간이라면 문서 계층을 클릭하며 몇 분을 보낼 곳에서, 에이전트는 단 한 번의 GET 요청으로 전체 페이지를 받아 다음으로 넘어간다. '사용자 여정'이라는 개념 자체가 단일 서버 이벤트로 압축돼 버리는 것이다.
실질적인 결과: 스크롤 깊이, 페이지 체류 시간, 버튼 클릭, 튜토리얼 완료, 링크 추적, 폼 인터랙션 등 클라이언트 사이드 애널리틱스 이벤트가 전부 보이지 않게 된다. 에이전트는 그 모든 것을 그냥 통과해버린다.
이 연구는 서버 로그에서 AI 에이전트 트래픽을 식별하는 데 활용할 수 있는 고유한 행동 시그니처도 밝혀냈다:
| 에이전트 | HTTP 런타임 | 사전 요청 방식 | 시그니처 |
|---|---|---|---|
| Aider | Headless Chromium (Playwright) | 필요 시 GET | Mozilla/Safari 전체 user-agent |
| Claude Code | Node.js / Axios | 필요 시 GET | axios/1.8.4 |
| Cline | curl | GET + OpenAPI/Swagger 스캔 | curl/8.4.0 |
| Cursor | Node.js / got | HEAD 탐색 → GET | got (sindresorhus/got) |
| Junie | curl | 순차적 다중 페이지 GET | curl/8.4.0 |
| OpenCode | Headless Chromium (Playwright) | 필요 시 GET | Mozilla/Safari 전체 user-agent |
| VS Code | Electron / Chromium | 필요 시 GET | Electron 마커가 포함된 Chromium 스타일 |
| Windsurf | Go / Colly | 필요 시 GET | colly |
코딩 에이전트 외에도, ChatGPT·Claude·Google Gemini·Perplexity 같은 AI 어시스턴트 웹 서비스 역시 사용자가 채팅 인터페이스에 URL을 공유하면 고유한 시그니처를 남긴다. 각 서비스가 자체적으로 서버 사이드 요청을 발생시키기 때문이다.
무엇을 봐야 할지 알면, 애널리틱스에서 AI 에이전트 트래픽을 따로 분류할 수 있다. 내 로그에도 이미 상당한 양이 쌓여 있다는 사실에 적잖이 놀랐다.
전체 그림에서 가장 저평가된 부분이 바로 이것이다: 토큰 경제학.
에이전트의 컨텍스트는 무한하지 않다. 대부분 실용적인 한계는 10만~20만 토큰 사이이며, 컨텍스트 관리는 모든 작업에서 활성 제약 조건이다. 해당 논문은 구체적인 사례를 제시한다. Cisco Secure Firewall Management Center REST API 퀵 스타트 가이드(버전 10.0)는 193,217 토큰, 약 71만 8,000자에 달한다. 단 하나의 문서가 대부분 에이전트의 전체 컨텍스트 윈도우를 거의 소진하거나 초과할 수 있는 것이다.
에이전트가 너무 긴 문서를 만났을 때 일어날 수 있는 일들이 있는데, 어느 것도 좋지 않다:
이는 곧 토큰 수가 이제 1급 문서 지표가 됐음을 의미한다. 문서 페이지별 토큰 수를 추적하지 않고 있다면, 에이전트가 실제로 콘텐츠 읽기를 시도할지 결정할 때 사용하는 신호를 놓치고 있는 것이다.
대략적인 가이드로 삼기에 적절한 수치들이다:
AEO는 단일한 무언가가 아니다 — 신호와 표준이 겹겹이 쌓인 구조다. 기반부터 표면까지, 스택으로 생각하면 이해하기 쉽다:
robots.txt)에이전트가 가장 먼저 들르는 곳이다. 콘텐츠를 가져오기 전에, 많은 에이전트는 robots.txt를 확인해 접근 가능한 범위를 파악한다.
알려진 AI 크롤러를 차단하도록 잘못 설정된 robots.txt는 에이전트의 문서 접근을 통째로 막아버린다. 아무런 트래픽도, 오류도, 이상 징후도 없이. 문서가 에이전트에게 보이지 않는 상태인지조차 모르고 있던 팀들이 이 문제에 발목을 잡히는 걸 직접 봤다.
실천 방법:
robots.txt에서 AI 에이전트 user-agent를 의도치 않게 차단하는 규칙이 있는지 점검agent-permissions.json를 살펴볼 것 — 어떤 자동화 인터랙션을 허용할지, 속도 제한, 선호 API 엔드포인트 등을 선언적으로 명시할 수 있는 새로운 스펙llms.txt를 통한 검색접근 권한이 있더라도, 에이전트는 여전히 올바른 콘텐츠를 찾아야 한다. 이 역할을 하는 것이 llms.txt다.
나는 llms.txt를 AI 에이전트용 사이트맵으로 본다. yourdomain.com/llms.txt에 위치한 플랫 형태의 마크다운 파일로, 문서 전체를 구조화된 디렉터리 형태로 — 설명과 함께 — 제공한다. 덕분에 에이전트가 사이트 전체를 크롤링하지 않고도 필요한 내용을 파악할 수 있다.
잘 작성된 llms.txt는 대략 다음과 같은 형태다:
# YourProduct Documentation
## Getting Started
- [Quick Start Guide](/docs/quickstart): Install and make your first API call in 5 minutes
- [Authentication](/docs/auth): OAuth 2.0 and API key authentication patterns
- [Core Concepts](/docs/concepts): Data model, entities, and terminology
## API Reference
- [REST API Overview](/docs/api): Base URLs, versioning, pagination, error codes
- [Users API](/docs/api/users): CRUD operations for user management (12K tokens)
- [Events API](/docs/api/events): Event streaming and webhook configuration (8K tokens)
## MCP Integration
- [MCP Server](/docs/mcp): Model Context Protocol server for direct agent integration
좋은 llms.txt의 조건:
skill.md를 통한 기능 신호llms.txt는 에이전트에게 콘텐츠의 위치를 알려준다. skill.md는 제품이 실제로 무엇을 할 수 있는지를 알려준다.
이 차이는 처음 보기보다 훨씬 중요하다. 에이전트가 산문 형태의 문서에서 기능을 유추해야 하는 대신, skill.md는 의도를 엔드포인트와 리소스에 선언적으로 매핑해 기능을 직접 드러낸다.
인증 서비스용 skill.md는 다음과 같은 형태가 될 수 있다:
---
name: auth-service
description: Handles user authentication, OAuth 2.0 flows, and session management
---
## What I can accomplish
- Authenticate users via OAuth 2.0 (authorization code, client credentials, PKCE)
- Issue and validate JWT tokens
- Manage user sessions and refresh token rotation
- Integrate with SSO providers (SAML, OIDC)
## Required inputs
- Client ID and Client Secret (from developer console)
- Redirect URI (must be pre-registered)
- Requested scopes (read:user, write:data, admin)
## Constraints
- Rate limit: 1000 token requests per minute per application
- Token expiry: access tokens 1hr, refresh tokens 30 days
- PKCE required for public clients
## Key documentation
- [OAuth 2.0 Guide](/docs/oauth): Full flow walkthrough with code samples
- [Token Reference](/docs/tokens): Token structure, claims, validation
- [Postman Collection](/docs/postman): Ready-to-use request templates
이것이 에이전트가 의미 있는 판단을 내릴 수 있게 해주는 장치다 — 문서를 가져오는 것에 그치지 않고, 전체 내용을 읽는 데 컨텍스트 예산을 쓰기 전에 해당 API가 사용자의 의도를 실제로 충족할 수 있는지를 먼저 파악할 수 있다.
완벽한 검색 가능성과 기능 신호가 갖춰져도, 실제 콘텐츠 자체가 에이전트가 읽을 수 있는 형태여야 한다. 여기서 중요하다고 파악한 것들이다:
HTML만이 아니라 마크다운으로도 제공하라. 많은 문서 플랫폼은 URL에 .md를 붙이거나 쿼리 파라미터를 통해 원본 마크다운에 접근할 수 있게 해준다. 이 방법을 알기 쉽게 노출하라. 에이전트는 HTML보다 마크다운을 처리할 때 토큰 부담이 현저히 낮다 — 태그 노이즈도, 네비게이션 크롬도, 푸터 쓰레기도 없으니.
읽기가 아닌 스캔을 위한 구조로 만들어라. 에이전트는 선형으로 읽지 않는다 — 구조를 파싱한다:
네비게이션 노이즈를 제거하라. HTML에 포함된 사이드바, 브레드크럼, 푸터 링크는 마크다운/텍스트에서 그저 소음이다. 파싱 가능한 콘텐츠 경로에서 배제하라.
유용한 내용을 앞으로 배치하라. 모든 페이지의 첫 500 토큰은 이 세 가지를 답해야 한다: 이것이 무엇인지, 무엇을 할 수 있는지, 시작하려면 무엇이 필요한지. 에이전트는 긴 서두에 인내심이 없다.
말보다 단순하지만 효과는 놀랍도록 크다: 문서 페이지에 토큰 수를 노출하라. llms.txt 인덱스와 페이지 자체(메타데이터 또는 페이지 헤더 형태로) 양쪽에 담는 것이 이상적이다.
에이전트가 현명한 판단을 내리는 데 필요한 정보를 제공하는 것이다:
구현은 간단하다. 서버 사이드에서 문자 수를 세고 ~4로 나눠 대략적인 토큰 수를 추산한 뒤, 메타 태그나 HTTP 응답 헤더로 노출하면 된다.
인프라 레이어라기보다 UX 브리지에 가깝지만, 포함할 가치가 있다: AI용 복사 버튼이다.
AI 어시스턴트가 탑재된 IDE에서 작업하는 개발자가 문서를 컨텍스트로 넣고 싶을 때, 지금은 렌더링된 HTML에서 복사-붙여넣기를 한다 — 네비게이션 노이즈, 푸터, 온갖 것이 딸려온다. 깨끗한 마크다운을 클립보드에 복사해주는 "AI용 복사" 버튼은 사소해 보이지만, 에이전트가 받는 컨텍스트의 품질을 실질적으로 높여준다.
Anthropic, Cloudflare 등은 이미 이 기능의 변형을 출시했다. 구현 비용은 낮고, 신호 가치는 크다.
특별히 짚어둘 것이 있다: AGENTS.md다.
README.md가 인간 개발자가 저장소를 탐색할 때 기본 진입점이 된 것처럼, AGENTS.md는 AI 에이전트의 진입점이 되어가고 있다. 코딩 에이전트가 프로젝트를 열면 루트 디렉터리에서 AGENTS.md를 찾고, 이후 모든 작업에 그 지침을 반영한다.
이에 대해 별도로 글을 쓴 바 있지만, 핵심만 요약하면 좋은 AGENTS.md에는 다음이 포함된다:
Cisco DevNet은 이미 이를 오픈소스 프로젝트의 GitHub 템플릿 기본 파일로 채택했다. 새로 생성되는 프로젝트에는 프로젝트별 내용, OpenAPI 문서 링크, DevNet 샌드박스, 테스트 환경이 미리 채워진 AGENTS.md가 기본으로 포함된다.
지금 당장 할 수 있는 일 하나: 애널리틱스에서 AI 레퍼럴 트래픽 추적을 시작하라.
주목할 레퍼럴 소스들이다:
labs.perplexity.ai/referral
chatgpt.com/(none)
chatgpt.com/organic
link.edgepilot.com/referral
platform.openai.com/referral
perplexity/(not set)
claude.ai/referral
copilot.microsoft.com/referral
gemini.google.com/referral
앞서 언급한 HTTP 시그니처 — axios/1.8.4, curl/8.4.0, got (sindresorhus/got), colly — 도 함께 모니터링해야 한다. 레퍼러 없이 직접 유입되는 에이전트 트래픽을 잡아내기 위해서다.
AI 트래픽 세그먼트를 제대로 구축해두면, 이 모든 작업이 실제로 효과를 내고 있는지 판단할 수 있는 선행 지표를 얻게 된다.
잠시 물러나 생각해볼 필요가 있다. AEO는 단순한 기술 체크리스트를 넘어, 더 큰 무언가를 가리키고 있다.
웹의 역사 대부분에서 개발자 포털은 인간의 인지 패턴을 중심으로 설계됐다. 점진적 공개, 시각적 계층 구조, 인터랙티브 예시, 안내형 튜토리얼 — 이 모두는 매 단계마다 인간이 개입한다는 전제 위에 세워져 있다.
에이전트 중심 세계에서는 그 전제들이 무너진다:
이것이 인간 중심 설계가 더 이상 중요하지 않다는 뜻은 아니다. 인간도 여전히 문서를 읽는다. 하지만 점점 더 AI 어시스턴트의 컨텍스트 안에서 읽게 된다 — 인간이 최종 수혜자이더라도, 에이전트가 직접적인 소비자인 경우가 많아진다는 뜻이다.
앞으로 최고의 문서는 두 독자를 동시에 만족시켜야 할 것이다. 인간을 위한 스캔 가능하고 잘 구조화된 문서, 에이전트를 위한 기계 가독성 높고 토큰 효율적인 문서.
지금 당장 문서 사이트의 에이전트 준비 상태를 점검한다면 확인할 항목들이다:
검색 가능성
llms.txt가 루트에 존재하며 모든 문서의 구조화된 인덱스를 포함robots.txt가 알려진 AI 에이전트 user-agent를 의도치 않게 차단하지 않음agent-permissions.json가 자동화 클라이언트에 대한 접근 규칙을 정의AGENTS.md가 코드 저장소에 존재하며 관련 문서로 연결콘텐츠 구조
토큰 경제학
llms.txt에 노출됨기능 신호
skill.md 파일이 각 서비스/API를 호출하는 방법뿐 아니라 무엇을 할 수 있는지 설명애널리틱스
UX 브리지
.md 붙이기)도구
이 항목들의 점검 일부를 자동화하기 위해 agentic-seo를 만들었다. 사이트의 AEO 개선 기회를 스캔하는 경량 감사 도구로, llms.txt 존재 여부, robots.txt의 에이전트 차단, 토큰 수, 마크다운 접근 가능성 등을 확인한다. Lighthouse와 같되, 에이전트 준비 상태에 특화된 도구라고 생각하면 된다.
이 목록을 보면서 어디서 시작해야 할지 막막하다면, 내가 추천하는 순서다:
robots.txt 점검 — 10분이면 되고, 에이전트의 조용한 차단을 막는다llms.txt 추가 — 몇 시간 투자로 즉각적인 검색 가능성 향상skill.md 작성 — 에이전트가 가장 많이 찾을 법한 것부터 시작SEO는 훌륭한 콘텐츠만으로는 충분하지 않다는 것을 가르쳐줬다. 그 시대의 실제 트래픽 패턴에 맞는 방식으로 발견 가능하게 만들어야 한다. AEO는 소비자만 다를 뿐, 같은 교훈이다.
AI 코딩 에이전트는 이미 문서 트래픽의 상당 부분을 차지하며 그 비중은 계속 커지고 있다. 인간 독자와는 근본적으로 다르게 행동한다. 그런데 대부분의 개발자 포털은 아직 이를 위해 만들어지지 않았다.
여기서 먼저 움직이는 팀은 실질적인 경쟁 우위를 얻게 될 것이다. 에이전트가 추천하고, 성공적으로 통합하고, 다시 찾는 API가 바로 그들의 것이 된다. 그렇지 않은 팀은 문서 품질과 실제 에이전트 작업 성공률 사이에 점점 벌어지는 간극을 목격하게 될 것이다 — 원인을 파악하기도 어려운 조용한 실패다.
다행인 것은, 에이전트를 위한 문서를 만들면 인간을 위한 문서도 함께 좋아진다는 점이다. 두 규율은 서로 충돌하기보다 상당 부분 겹친다.
llms.txt부터 시작하라. skill.md를 만들어라. robots.txt를 점검하라. 토큰 수를 측정하라. 대부분은 주말 하나면 해결된다. 그리고 그 효과는 이미 실재한다.