전통적인 문서는 사람을 위해 만들어집니다: 렌더링된 HTML, 구문 강조, 사이드바, 검색. 하지만 점점 더 docs를 방문하는 것은 사람이 아니라 에이전트(Claude, Cursor, ChatGPT)이며, 이들에게는 이런 렌더링이 방해만 될 뿐입니다. 에이전트에게 필요한 것은 깨끗한 텍스트와 기계가 읽을 수 있는 계약입니다.
우리는 문서를 양쪽 모두에게 쓸모 있게 만들었습니다. 내부 구조는 다음과 같습니다.
모든 페이지의 .md 쌍둥이
섹션 제목: “모든 페이지의 .md 쌍둥이”콘텐츠 문서의 모든 페이지에는 같은 경로에 .md 접미사를 붙인 원본 Markdown 쌍둥이가 있습니다. /agent-setup을 열었다면 /agent-setup.md도 있습니다. HTML 래퍼 없이 같은 텍스트이며, MDX import는 제거되고, text/markdown으로 제공됩니다.
이것이 페이지 메뉴의 두 가지 동작을 뒷받침합니다: Copy as Markdown(모델과의 채팅에 붙여 넣을 수 있도록 깨끗한 텍스트를 클립보드에 복사)과 View as Markdown(.md 버전을 바로 열기). 에이전트는 DOM을 파싱할 필요 없이 준비된 텍스트를 가져가면 됩니다.
페이지 상단의 동작 드롭다운
섹션 제목: “페이지 상단의 동작 드롭다운”모든 페이지의 오른쪽 위에는 에이전트 워크플로를 위해 만든 동작 메뉴가 있습니다:
- Copy as Markdown: 페이지의 깨끗한 텍스트를 클립보드에 복사
- View as Markdown:
.md쌍둥이 열기 - Open in ChatGPT: 클릭 한 번으로 페이지를 ChatGPT에 전달
- Open in Claude: Claude에서도 마찬가지
- Connect MCP: MCP 서버 설정으로 이동
“URL을 복사하고, 채팅을 열고, 페이지를 읽어 달라고 요청”하는 대신 동작 하나면 됩니다.
llms.txt와 llms-full.txt
섹션 제목: “llms.txt와 llms-full.txt”llmstxt.org 표준에 따라 두 개의 파일을 제공합니다:
/llms.txt: 모든 문서 페이지의 인덱스로, 섹션(API Reference, Use Cases, Examples, Products)별로 묶여 있습니다. 에이전트가 어디서부터 시작할지 알려 주는 지도입니다./llms-full.txt: 전체 문서를 하나의 plain text 파일로 제공합니다. 벡터 데이터베이스에서 오프라인 인덱싱을 하거나 모델 컨텍스트에 한 번에 넣을 때 사용합니다.
우리 API 위에 RAG를 구축한다면 llms-full.txt가 바로 쓸 수 있는 코퍼스이므로, 사이트를 크롤링할 필요가 없습니다.
기계가 읽을 수 있는 명세
섹션 제목: “기계가 읽을 수 있는 명세”계약은 여러 도구에 맞춰 여러 형식으로 제공됩니다:
/v1/openapi.json: 예제와 code-samples가 포함된 정식 OpenAPI 3.1 명세입니다. 클라이언트 코드 생성과 모든 OpenAPI 도구에 사용합니다.- Swagger 별칭:
/v1/swagger.json,/v1/v3/api-docs등은 정식 경로로 301 리디렉션되므로, 익숙한 경로를 찾는 도구도 막히지 않습니다. - Postman 컬렉션:
/postman/astroway-api.json으로 클릭 한 번에 Postman으로 가져올 수 있습니다.
클라이언트별 /agent-setup
섹션 제목: “클라이언트별 /agent-setup”/agent-setup/ 페이지는 하나의 일반 가이드가 아니라 일곱 개 클라이언트를 위한 개별 안내입니다: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. 각 안내는 정확한 설정과 tools/list curl 예제를 제공하므로, 코드를 작성하기 전에 연결을 확인할 수 있습니다.
인라인 try-it
섹션 제목: “인라인 try-it”API 레퍼런스 페이지의 모든 작업에는 try-it 위젯이 내장되어 있습니다: sandbox 키를 넣고, 요청 본문을 편집하고, “Send”를 누르면 docs를 떠나지 않고 실제 응답을 볼 수 있습니다. 메서드, 경로, 본문 예제는 이미 생성된 curl 스니펫에서 가져오므로, 위젯이 openapi.json에 불필요한 요청을 보내지 않습니다.
이 모든 것이 필요한 이유
섹션 제목: “이 모든 것이 필요한 이유”논지는 간단합니다: 제품이 API라면 문서는 눈으로 읽기에만 적합해서는 안 되고, 에이전트가 소비하기에도 적합해야 합니다. 오늘날 통합의 절반은 개발자가 docs 링크를 Claude나 Cursor에 던지고 “이거 연결해 줘”라고 요청하는 데서 시작합니다. 우리는 그 반대편에 파싱해야 하는 HTML이 아니라 깨끗한 텍스트와 기계용 계약이 있도록 만들었습니다.
직접 해 보세요: docs의 아무 페이지나 열고 오른쪽 위의 동작 메뉴를 누르면 “Open in Claude”가 보입니다.