AEO란 무엇인가: 에이전트가 문서를 읽는 방식에 맞춰 구조를 바꾸는 법 | DAKER 커뮤니티

코드 편집기 앞에서 작업이 막히는 순간은 모델 성능보다 문서의 입구에서 갈리는 경우가 많습니다. 문서는 분명 있는데도 에이전트가 엉뚱한 예시를 고르거나, 긴 설명을 따라가다 핵심 제약을 놓치는 일이 반복되기 때문입니다.

Addy Osmani가 말한 AEO는 사람에게 보기 좋은 문서를 만드는 방법이 아니라, AI 에이전트가 한두 번의 요청 안에서 필요한 규칙과 예시를 붙잡도록 문서를 운영하는 방식입니다. 지금 중요한 것은 검색 노출보다 실행 가능한 문서 구조입니다.

오늘의 핵심은 검색 노출보다 실행 가능한 문서 구조입니다.

AEO가 필요한 순간

AEO는 Claude Code나 코딩 에이전트가 사내 SDK, API, 저장소 규칙, 배포 절차를 반복해서 잘못 읽을 때 특히 유용합니다. 문서는 있는데 에이전트가 오래된 경로를 고르거나, 토큰을 많이 쓰고도 핵심 제약을 놓치거나, 사람용 튜토리얼만 따라가며 작업이 길어지는 상황에서 문서의 구조를 다시 점검할 필요가 있습니다.

에이전트는 문서를 어떻게 읽나

에이전트의 문서 방문은 사람이 여러 화면을 둘러보는 방식과 다릅니다. 단일 HTTP 요청, 원문 텍스트 파싱, 제한된 컨텍스트 안에서의 선택으로 압축됩니다. 그래서 문서는 검색에 잘 걸리는 제목보다, 파싱하기 쉬운 구조와 짧은 시작점이 더 중요해집니다.

이때 먼저 필요한 것은 명시된 권한과 한계, 그리고 바로 복사해 쓸 수 있는 최소 예시입니다. 사람용 문서가 전시장 안내문에 가깝다면, 에이전트용 문서는 작업자가 바로 집어 드는 공구함 라벨에 가깝습니다. 다만 이 비유는 구조를 설명할 뿐이고, 실제 판단은 원문 텍스트와 토큰, 권한 규칙으로 검증해야 합니다.

에이전트에게 중요한 것은 예쁜 문서보다 어디서 시작하고 무엇을 가져가야 하는지가 분명한 문서입니다.

AEO의 실제 단서들

AEO는 추상적인 개념에 머물지 않습니다. robots.txt, llms.txt, skill.md, 토큰 수 표시, Copy for AI 버튼 같은 요소는 에이전트가 시작점과 우선순위를 정하는 표지판이 됩니다. 결국 문서 운영의 핵심은 에이전트가 길을 잃지 않도록 진입 경로와 경계를 짧고 분명하게 드러내는 데 있습니다.

적용 방법

접근 가능한 문서와 제외할 문서를 먼저 나눕니다

먼저 에이전트가 접근해도 되는 문서와 막아야 할 문서를 robots.txt 관점으로 구분하는 것이 좋습니다. 민감한 관리자 경로와 오래된 문서는 시작점에서 제외해야 합니다.

핵심 문서의 입구를 짧게 묶습니다

llms.txt나 그에 준하는 안내 파일에는 핵심 문서, 최신 API, 금지된 구버전 경로, 예제 위치를 짧게 정리하면 됩니다. 에이전트가 처음 읽는 몇 줄 안에서 방향을 잡을 수 있어야 합니다.

자주 쓰는 작업 하나를 기준으로 skill.md를 만듭니다

가장 자주 쓰는 API나 워크플로 하나를 골라 skill.md 형태로 목적, 입력, 출력, 실패 조건, 완료 증거를 적어 두면 에이전트가 작업 단위를 더 안정적으로 이해할 수 있습니다.

작업 지시에도 문서 원칙을 반영합니다

Claude Code 작업 지시에는 공식 문서 확인, 토큰 낭비가 큰 페이지 제외, 완료 전 테스트 증거 제출 같은 기준을 함께 적는 것이 좋습니다. 문서 구조와 작업 지시가 따로 놀면 같은 실수가 반복되기 쉽습니다.

실패 로그를 다음 수정 대상으로 삼습니다

AI 트래픽이나 반복 실패 로그를 보면 에이전트가 실제로 어디에서 길을 잃는지 드러납니다. 그 지점을 다음 문서 수정 대상으로 삼으면 됩니다.

긴 튜토리얼 하나보다 짧은 진입점과 명시적 경계가 에이전트에게 더 잘 작동합니다.

문서를 만들 때 피할 점

긴 튜토리얼 하나로 모든 것을 설명하려 하기보다, 짧은 진입점과 명시적 경계를 두는 편이 낫습니다. 또한 사람이 읽는 마케팅 문장과 에이전트가 실행할 절차를 한 문서 안에서 뒤섞지 않는 것이 좋습니다. 목적, 명령, 제약, 검증은 분리되어야 합니다.

문서에 외부 비밀값, 내부 계정, 임시 우회 절차를 넣지 않는 것도 중요합니다. AEO는 접근성을 높이는 방식이지만, 권한 경계까지 흐리게 만들어서는 안 됩니다.

이미지가 보여 주는 흐름

첫 이미지는 AEO를 문서가 읽히는 상태로 바꾸는 장면을 보여 줍니다. 두 번째 이미지는 접근 허용, 구조 발견, 용량 파악, 기능 정의, 복사 지원으로 이어지는 작업 순서를 압축합니다.

참고 자료

이 글은 Addy Osmani 공식 사이트의 글 3개와 비공개 검증 메모 10항목을 기준으로 작성했습니다. 관련 실무 흐름은 https://daker.ai/community?directory=claude-code에서 이어 볼 수 있습니다.

지금 운영 중인 문서 가운데 에이전트가 처음 읽을 세 줄을 다시 쓴다면, 무엇부터 바꾸게 될지 궁금합니다.