오스마니 기술 — AEO, 에이전트는 문서를 어떻게 읽나 | DAKER 커뮤니티
무엇 : 코드 편집기 앞에서 막히는 순간은 대개 모델이 부족해서가 아니라, 모델이 읽을 문서 입구를 찾지 못해서 시작됩니다. Addy Osmani가 말한 AEO는 사람에게 예쁜 문서를 만드는 일이 아니라, AI 에이전트가 한두 번의 요청 안에서 필요한 규칙과 예시를 붙잡게 만드는 문서 운영법입니다. 오늘의 핵심은 검색 노출보다 실행 가능한 문서 구조입니다.
언제 쓰나 : Claude Code나 코딩 에이전트가 사내 SDK, API, 저장소 규칙, 배포 절차를 반복해서 잘못 읽을 때 씁니다. 특히 “문서는 있는데 에이전트가 엉뚱한 예시를 고른다”, “토큰을 많이 쓰고도 핵심 제약을 놓친다”, “사람용 튜토리얼만 따라가다 오래된 경로를 택한다”는 상황에서 AEO가 작업 경로를 바꿉니다.
핵심 원리
- 에이전트의 문서 방문은 사람처럼 여러 화면을 둘러보는 여정이 아닙니다. 단일 HTTP 요청, 원문 텍스트 파싱, 제한된 컨텍스트 안의 선택으로 압축됩니다.
- 그래서 문서는 검색 가능한 제목보다 파싱 가능한 구조, 짧은 시작점, 명시된 권한과 한계, 복사 가능한 최소 예시를 먼저 가져야 합니다.
- AEO의 실제 단서는 robots.txt, llms.txt, skill.md, 토큰 수 표시, Copy for AI 버튼처럼 에이전트가 “어디서 시작하고 무엇을 가져갈지” 정하는 표지판입니다.
- 비유하자면 사람용 문서가 전시장 안내문이라면, 에이전트용 문서는 작업자가 바로 집어 드는 공구함 라벨입니다. 비유는 구조를 설명할 뿐이고, 실제 판단은 원문 텍스트·토큰·권한 규칙으로 검증해야 합니다.
적용 방법
- 먼저 에이전트가 접근해도 되는 문서와 막아야 할 문서를 robots.txt 관점으로 나눕니다. 민감한 관리자 경로와 오래된 문서는 시작점에서 제외합니다.
- llms.txt나 동등한 안내 파일에 핵심 문서, 최신 API, 금지된 구버전 경로, 예제 위치를 짧게 묶습니다.
- 가장 자주 쓰는 API나 워크플로 1개를 골라 skill.md 형태로 목적, 입력, 출력, 실패 조건, 완료 증거를 적습니다.
- Claude Code 작업 지시에는 “공식 문서 확인, 토큰 낭비가 큰 페이지 제외, 완료 전 테스트 증거 제출”을 명시합니다.
- AI 트래픽이나 반복 실패 로그를 보고 에이전트가 실제로 어디에서 길을 잃는지 다음 문서 수정 대상으로 삼습니다.
- 긴 튜토리얼 하나로 모든 것을 설명하려 하지 마세요. 에이전트는 짧은 진입점과 명시적 경계를 더 잘 씁니다.
- 사람이 읽는 마케팅 문장과 에이전트가 실행할 절차를 섞지 마세요. 목적, 명령, 제약, 검증을 분리해야 합니다.
- 문서에 외부 비밀값, 내부 계정, 임시 우회 절차를 넣지 마세요. AEO는 접근성을 높이지만, 권한 경계를 흐리면 안 됩니다.
이미지 차트 : 첫 이미지는 AEO를 “문서가 읽히는 상태”로 바꾸는 장면을 보여 줍니다. 두 번째 이미지는 접근 허용, 구조 발견, 용량 파악, 기능 정의, 복사 지원으로 이어지는 작업 순서를 압축합니다.
공식 검증 : 이 글은 Addy Osmani 공식 사이트의 글 3개와 비공개 검증 메모 10항목을 기준으로 작성했습니다. 공개 본문에는 DAKER 정책에 맞춰 외부 원문 링크를 싣지 않았고, 관련 실무 흐름은 DAKER 클로드 코드 디렉터리에서 이어 볼 수 있습니다.
오늘 한 가지 문서를 골라 에이전트가 처음 읽을 세 줄을 다시 써 보세요. 그 세 줄이 목표, 금지 경로, 완료 증거를 말하지 못하면 Claude Code의 다음 실험도 같은 자리에서 멈출 가능성이 큽니다.