문서 사이트를 에이전트가 읽기 쉬운 형태로 만들기: llms.txt, MCP, 그리고 실제로 중요한 .well-known 파일들

AI agents는 인간 대신 여러분의 문서를 점점 더 많이 읽게 됩니다. 만약 문서 사이트가 브라우저를 위해 HTML만 출력한다면, 에이전트는 스크래핑하고 추측해야 합니다. 더 나은 표면(surface)이 있는데, 그 대부분은 몇 가지 작고 표준적인 파일들로 이루어져 있습니다. 여기 OrchestKit 문서 사이트에 배포하는 전체 스택과 각 구성 요소가 존재하는 이유, 그리고 이를 검증하는 방법을 설명합니다.

1. llms.txt — 에이전트의 목차

/llms.txt에 있는 일반 텍스트 인덱스: 제품이 무엇인지, 제약 조건은 무엇인지, 그리고 모든 기계가 읽을 수 있는 리소스에 대한 링크 지도를 제공합니다. 내용을 약 30k 문자 이내로 유지하세요. 상세한 페이지 목록은 /docs/llms.txt에, 전체 코퍼스는 /llms-full.txt에 넣으세요. 장점은 에이전트가 크롤링하는 대신 한 번의 요청으로 방향을 잡을 수 있다는 것입니다.

2. Markdown 콘텐츠 협상(content negotiation)

페이지 URL에 .md를 추가하거나 (Accept: text/markdown 전송) 원시 Markdown을 반환하세요. 에이전트는 깨끗한 토큰을 얻고, 인간은 여전히 렌더링된 페이지를 받습니다.

3. 읽기 API를 위한 OpenAPI spec

문서 사이트라도 API 표면(검색, 페이지 가져오기)을 가지고 있습니다. 예측 가능한 경로에 OpenAPI 문서를 게시하여 에이전트가 리버스 엔지니어링 없이 호출할 수 있도록 하세요. 이를 RFC 9727과 결합하세요. 이는 모든 API 진입점을 열거하는 /.well-known/api-catalog 링크셋입니다.

4. MCP 서버

Model Context Protocol은 에이전트가 여러분의 도구를 네이티브하게 호출할 수 있게 합니다. 우리는 /api/mcp에서 Streamable HTTP를 통해 읽기 전용 MCP 서버를 노출하고, 발견을 위한 server-card.json도 제공합니다. 검색 문서와 ID로 문서 가져오기라는 두 가지 도구만 있어도 유용하기에 충분합니다.

5. .well-known 식별 파일들

• agent-card.json (A2A): 여러분의 에이전트 기술을 선언합니다.
• agent-skills/index.json: 소비자(consumer)가 검증할 수 있도록 각 기술에 대한 SHA-256 다이제스트를 포함하는 Agent Skills Discovery RFC입니다.
• oauth-protected-resource (RFC 9728): API가 익명이라면, 그렇게 말하세요. 비어 있는 authorization_servers는 누락이 아니라 긍정적인 신호입니다.

6. 개체 그래프가 조정할 수 있는 JSON-LD

6. 개체 그래프가 조정할 수 있는 JSON-LD

@id로 연결된 schema.org 그래프(Organization, SoftwareApplication, WebSite)를 발행하고, sameAs는 이미 여러분을 검증한 레지스트리(GitHub, 패키지 레지스트리, Wikidata)를 가리키게 하세요. 모든 곳에서 재사용되는 단일 표준 Organization 블록을 사용하여 그래프가 충돌하는 식별자를 보지 않도록 하세요. 절대 aggregateRating을 꾸며내지 마세요. 대신 실제 신호(예: GitHub 스타를 InteractionCounter로)를 노출하세요.

7. robots.txt에 크롤러에게 진실을 말하기

원하는 명시적 AI 크롤러(GPTBot, ClaudeBot, OAI-SearchBot, Google-Extended 등)를 허용하고, Content-Signal 지시문을 발행하세요. 사이트맵과 스키마 맵을 연결하세요.

검증 방법

curl -s https://yoursite/llms.txt로 가져오고, 각 .well-known 경로를 가져와 구조화된 데이터 유효성 검사기(structured-data validator)를 통해 JSON-LD를 실행해 보세요. 만약 Claude Code 기반으로 구축한다면, 오픈 소스 OrchestKit 문서 사이트가 위에 언급된 모든 항목을 구현하고 있습니다 — 소스는 GitHub에 있으며 MIT 라이선스가 적용되었고 라우트 핸들러를 직접 읽어볼 수 있습니다.

저는 OrchestKit(Claude Code용 무료 MIT 플러그인, 111 스킬/37 에이전트/210 후크)을 유지 관리하고 있습니다. 여기서 설명하는 에이전트 검색 표면은 오늘날 그 문서 사이트가 제공하는 것입니다.