Tài liệu được tạo cho AI agents, không chỉ cho con người

Кlassична документація được làm cho con người: HTML đã render, highlight cú pháp, sidebar, tìm kiếm. Nhưng ngày càng nhiều lần docs không phải con người mà là agent - Claude, Cursor, ChatGPT - người mà toàn bộ render này chỉ gây cản trở. Nó cần văn bản thuần và hợp đồng máy đọc được.

Chúng tôi đã làm tài liệu phù hợp cho cả hai. Đây là những gì bên trong.

Mỗi trang nội dung tài liệu có bản sao Markdown thô cùng đường dẫn với hậu tố .md. Mở /agent-setup - cũng có /agent-setup.md, cùng một văn bản không có bao bọc HTML, các import MDX đã bị cắt, trả về dưới dạng text/markdown.

Điều này cung cấp hai hành động trong menu trang: Copy as Markdown (đặt văn bản thuần vào clipboard để dán vào chat với mô hình) và View as Markdown (mở phiên bản .md trực tiếp). Agent không cần parse DOM - nó lấy ngay văn bản sẵn có.

Ở góc trên bên phải của mỗi trang - menu hành động, được tạo riêng cho workflow của agent:

• Copy as Markdown - văn bản thuần của trang vào clipboard
• View as Markdown - mở bản sao .md
• Open in ChatGPT - chuyển trang tới ChatGPT chỉ bằng một cú click
• Open in Claude - tương tự cho Claude
• Connect MCP - chuyển tới cài đặt máy chủ MCP

Thay vì “sao chép URL, mở chat, yêu cầu truy cập trang” - chỉ một hành động.

Theo chuẩn llmstxt.org chúng tôi cung cấp hai file:

• /llms.txt - chỉ mục của tất cả các trang tài liệu, được nhóm theo các mục (API Reference, Use Cases, Examples, Products). Bản đồ cho agent, nơi bắt đầu.
• /llms-full.txt - toàn bộ tài liệu trong một file plain-text. Dùng cho việc index offline trong cơ sở dữ liệu vector hoặc chèn một lần vào ngữ cảnh của mô hình.

Nếu bạn xây dựng RAG trên API của chúng tôi, llms-full.txt là corpus đã sẵn sàng, không cần crawl site.

Hợp đồng được cung cấp bằng một số định dạng cho các công cụ khác nhau:

• /v1/openapi.json - đặc tả OpenAPI 3.1 chuẩn với các ví dụ và code-samples. Dùng cho việc sinh mã client và bất kỳ công cụ OpenAPI nào.
• Swagger-aliases - /v1/swagger.json, /v1/v3/api-docs và các redirect 301 khác sẽ chuyển tới chuẩn, để các công cụ tìm đường thường không gặp lỗi.
• Postman-collection - /postman/astroway-api.json để import vào Postman chỉ bằng một cú click.

Trang /agent-setup/ - không phải một hướng dẫn chung, mà là các hướng dẫn riêng cho bảy khách hàng: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Mỗi cái cung cấp cấu hình chính xác và ví dụ curl tools/list để kiểm tra kết nối trước khi viết code.

Trên các trang API reference, mỗi thao tác có widget try-it tích hợp: bạn chèn sandbox-key, chỉnh sửa body request, nhấn «Send» - và thấy phản hồi thực tế, không rời docs. Method, path và ví dụ body được lấy từ curl snippet đã được sinh sẵn, vì vậy widget không thực hiện các request thừa tới openapi.json.

Câu đơn giản: nếu sản phẩm của bạn là API, tài liệu phải phù hợp không chỉ để người đọc mắt mà còn để agent tiêu thụ. Một nửa các tích hợp ngày nay bắt đầu bằng việc developer gửi link docs vào Claude hoặc Cursor và yêu cầu “kết nối cái này”. Chúng tôi đã làm sao để ở cuối cùng có văn bản thuần và hợp đồng máy, không phải HTML cần phải parse.

Thử tự mình: mở bất kỳ trang docs nào, nhấn menu hành động ở trên cùng bên phải - và bạn sẽ thấy «Open in Claude».