누군가 Claude에게 "Postlark에 블로그 만들어줘"라고 했다고 하자. Claude는 먼저 Postlark가 어떤 서비스인지 파악해야 한다. 랜딩 페이지? 사람한테는 통하지만 AI한테는 비효율적이다. HTML을 파싱하고, 마케팅 카피 사이에서 실제 기능 정보를 골라내야 하니까. AI 에이전트에게는 다른 종류의 안내서가 필요하다.

robots.txt의 후손

robots.txt는 30년 넘게 검색 엔진과 웹사이트 사이의 약속으로 작동해왔다. "이 경로는 크롤링하지 마세요." 단순하고 효과적이었다. 하지만 AI 에이전트는 크롤러가 아니다. 페이지를 긁어가는 게 목적이 아니라, 서비스를 이해하고 직접 사용하려는 존재다.

llmstxt.org가 제안한 llms.txt는 이 간극을 메운다. 사이트 루트에 놓는 평문 텍스트 파일로, 해당 사이트가 뭘 하는 곳인지, API는 어떻게 쓰는지, 인증은 어떻게 하는지를 담는다. 사람이 읽어도 이해되고, 기계가 파싱하기에도 충분한 구조. 형식은 Markdown에 가깝지만 엄격한 스펙이라기보다는 관례에 가까운데, 그게 오히려 채택을 빠르게 만든 요인이다. sitemap.xml처럼 복잡한 네임스페이스나 스키마 검증이 필요 없으니까, 메모장에서 5분이면 만들 수 있다.

robots.txt가 "여기는 오지 마세요"였다면, llms.txt는 "여기서 이걸 할 수 있어요"에 해당한다. 금지의 규약에서 안내의 규약으로 방향이 180도 바뀐 셈이다.

블로그 플랫폼에 이게 왜 필요하냐면

MCP 서버 이야기를 지난 편에서 했다. AI 에이전트가 블로그를 만들고 글을 쓸 수 있게 됐다. 문제는 에이전트가 "Postlark라는 서비스 자체"를 먼저 알아야 한다는 거다.

그래서 두 계층으로 나눴다. 플랫폼 수준에서는 전체 API와 기능을 안내하고, 개별 블로그 수준에서는 그 블로그의 콘텐츠와 구조를 설명한다. 비개발자가 AI에게 "내 블로그에 대해 알려줘"라고 물으면, 블로그의 llms.txt가 맥락을 제공하는 구조다.

플랫폼 수준 파일에는 Postlark가 뭘 하는 서비스인지, 어떤 API 엔드포인트가 있는지, MCP 도구 목록과 각 도구의 파라미터 스키마가 들어간다. 개별 블로그 수준 파일에는 블로그 이름, 설명, 최근 글 목록, 태그 분포, 주요 주제가 담긴다. 에이전트가 새 글을 쓸 때 기존 글과 겹치지 않는지 확인하거나, 블로그 톤에 맞는 제목을 생성하는 데 이 정보를 활용할 수 있다.

핵심 발상은 이거다 — 사람이 플랫폼을 배우는 게 아니라, AI가 배운다.

50줄로 시작해서 하루에 세 번 고쳐 쓴 이야기

처음 만든 llms.txt는 50줄이었다. API 엔드포인트 몇 개, MCP 도구 목록, 인증 설명. 충분하다고 생각했다.

실제로 에이전트를 붙여보니 구멍투성이였다. 응답 스키마가 없으니 JSON 구조를 추측하고, 필수와 선택 파라미터를 구분 못 하니 엉뚱한 요청을 보내고, 에러가 나면 원인 파악 자체가 안 됐다.

결국 같은 날 세 번을 고쳐 썼다. 먼저 180줄로 확장해서 모든 엔드포인트를 넣었다. 그래도 타입 정보가 없으니 에이전트가 문자열 필드에 숫자를 보내는 식의 문제가 생겨서, 전체 응답 스키마에 타입 어노테이션을 추가했다. 마지막으로는 파일 자체를 분리했다 — 인덱스 파일 하나와 8개 섹션 파일. 한 파일에 다 넣으면 에이전트의 컨텍스트 윈도우를 낭비하니까, 필요한 섹션만 가져갈 수 있도록.

분리 후 구조는 대략 이렇다. 인덱스 파일이 전체 사이트 요약과 각 섹션 파일의 경로를 담고, 섹션 파일은 인증, 블로그 관리, 포스트 CRUD, 태그, 분석, MCP 도구, 에러 코드, 예제 시나리오로 나뉜다. 에이전트가 "새 블로그를 만들고 싶다"고 하면 인덱스에서 블로그 관리 섹션 경로만 가져와서 읽으면 된다. 토큰 효율이 좋아지니 응답 속도와 정확도 둘 다 올라갔다.

이 삽질에서 배운 건 하나다. llms.txt는 "문서"가 아니라 "인터페이스"다. 사람용 문서는 대충 훑어봐도 감 잡으면 되지만, AI를 위한 인터페이스에서 빈틈은 곧 에러다. 타입 하나 빠져도 에이전트는 헤맨다.

유지보수가 핵심이다

API 문서와 llms.txt가 동기화되지 않으면 에이전트가 틀린 정보를 바탕으로 행동한다. 사람은 "이 문서가 좀 오래된 것 같은데?"라고 의심이라도 하지만, 에이전트는 주어진 정보를 그대로 신뢰한다. 그래서 배포 파이프라인에 llms.txt 검증 단계를 넣었다. API 스펙이 변경되면 CI에서 llms.txt와 비교해서 불일치가 있으면 빌드를 실패시킨다.

앞으로 llms.txt 같은 파일이 표준으로 자리 잡을지는 아직 모른다. 하지만 방향은 분명하다 — 웹사이트는 이제 사람만을 위한 공간이 아니다. AI가 첫 번째 방문자인 경우가 점점 늘어나고, 그 방문자에게 적절한 안내서를 제공하는 건 SEO만큼이나 중요한 일이 될 것이다.