AI 에이전트를 위한 문서, 단순히 인간을 위한 문서가 아닙니다

클래식 문서는 사람을 위해 만든 것: 렌더링된 HTML, 구문 강조, 사이드바, 검색. 그러나 더 자주 문서를 보는 것은 에이전트 Claude, Cursor, ChatGPT - 렌더링은 그에게 방해가 됩니다. 그는 순수한 텍스트와 머신 리드 가능한 계약이 필요합니다.

우리는 문서를 사람과 에이전트 모두에게 적합한 것으로 만들었습니다. 그 아래의 내용은 다음과 같습니다.

각 페이지의 콘텐츠 문서는 .md 파일과 동일한 경로에 .md 파일을 가지고 있습니다. /agent-setup를 열면 /agent-setup.md도 있습니다. 동일한 텍스트는 HTML 래퍼가 없는 것과 MDX 임포트가 잘린 것과 같습니다. 이 파일은 text/markdown으로 제공됩니다.

이것은 두 가지 동작을 수행합니다: Copy as Markdown (버퍼에 클린 텍스트를 복사하여 채팅에 삽입) 및 View as Markdown (.md 버전을 직접 열기). 에이전트는 DOM을 파싱할 필요가 없습니다. 그는 이미 준비된 텍스트를 가져옵니다.

각 페이지의 오른쪽 상단 코너에는 에이전트 워크플로우를위한 메뉴가 있습니다:

• Copy as Markdown - 버퍼에 클린 텍스트 복사
• View as Markdown - .md 버전 열기
• Open in ChatGPT - 채팅에 페이지를 열기
• Open in Claude - Claude를 열기
• Connect MCP - MCP 서버 설정으로 이동

“URL 복사, 채팅 열기, 페이지 열기” 대신에 단일 동작이 있습니다.

llmstxt.org 표준에 따라 두 개의 파일을 제공합니다:

• /llms.txt - 모든 페이지의 인덱스, 섹션별로 그룹화 (API Reference, Use Cases, Examples, Products). 에이전트의 지도, 시작할 곳을 알려줍니다.
• /llms-full.txt - 모든 문서를 한 plain-text 파일로 제공합니다. 오프라인 인덱스에 사용하거나 모델에 대한 단일 삽입을 위해 사용합니다.

RAG를 빌드할 때, llms-full.txt는 준비된 코퍼스를 제공합니다. 사이트를 크롤링할 필요가 없습니다.

계약은 여러 형식으로 제공됩니다:

• /v1/openapi.json - OpenAPI 3.1 스펙과 예시 및 코드 샘플이 포함된 오픈 API 3.1 스펙. 클라이언트 생성과 OpenAPI 툴링을위한 코드 생성을위한 오픈 API 3.1 스펙.
• Swagger-알리아스 - /v1/swagger.json, /v1/v3/api-docs 및 다른 301 리디렉션은 오픈 API 3.1 스펙을 제공합니다. 툴이 일반적인 경로를 찾을 때 에이전트가 방해받지 않도록합니다.
• Postman 컬렉션 - /postman/astroway-api.json을 사용하여 Postman에 단일 클릭으로 가져옵니다.

페이지 /agent-setup/는 일반적인 가이드가 아니라 각 클라이언트별로 구체적인 설정과 curl 예시를 제공합니다: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. 각 클라이언트는 정확한 설정과 tools/list를 사용하여 연결을 확인하기 위해 curl 예시를 제공합니다.

API 도움말 페이지의 각 연산에는 try-it 버튼이 있습니다: sandbox 키를 삽입하고 요청 본문을 편집하고 “Send”를 클릭하여 실제 응답을 볼 수 있습니다. 메서드, 경로 및 예시 본문은 이미 생성된 curl 스니펫에서 가져온 것입니다. 따라서 try-it 버튼은 추가적인 요청을하지 않습니다.

단순한 주제: API의 경우, 문서는 에이전트가 사용할 수 있는 것과 함께 읽을 수 있어야합니다. 절반의 통합은 개발자가 Claude나 Cursor에 문서를 링크하고 “연결하세요”라고 요청하는 경우에 시작됩니다. 우리는 클린 텍스트와 머신 리드 가능한 계약을 제공하기 위해 이것을 만들었습니다. 개발자가 시작할 수 있습니다: 문서의 어떤 페이지를 열어보세요. 메뉴 상단의 동작을 클릭하여 “Claude에 열기”를 클릭하세요.