Dokumentacja stworzona dla AI-agentów, a nie tylko dla ludzi

Klasyczna dokumentacja zrobiona pod człowieka: renderowany HTML, podświetlany skład, pasek boczny, wyszukiwarka. Ale coraz częściej do docs idzie nie człowiek, ale agent - Claude, Cursor, ChatGPT - którym ten render tylko przeszkadza. Potrzebuje czystego tekstu i maszynowego kontraktu.

Zrobiliśmy dokumentację przyjazną dla obu. Oto co pod kapotem.

Każda strona dokumentacji ma oryginalny Markdown-duplikat z tym samym ścieżkiem, ale z sufiksem .md. Otwierając /agent-setup - jest i /agent-setup.md, ten sam tekst bez HTML-obudowy, MDX-importy zredukowane, oddaje się jako text/markdown.

To żywi dwa działania w menu strony: Kopiuj jako Markdown (kładzie czysty tekst w buforze, aby wstawić w czacie z modelem) i Zobacz jako Markdown (otwiera .md-wersję bezpośrednio). Agenta nie trzeba parszować DOM - on bierze gotowy tekst.

W prawym górnym rogu każdej strony - menu działania, zrobione właśnie pod agentowy workflow:

• Kopiuj jako Markdown - czysty tekst strony w buforze
• Zobacz jako Markdown - otwiera .md-duplikat
• Otwórz w ChatGPT - przesyła stronę do ChatGPT jednym kliknięciem
• Otwórz w Claude - to samo dla Claude
• Połącz MCP - przejście do ustawień MCP-servera

Zamiast “skopiuj URL, otwórz czat, poproś wejść na stronę” - jedna akcja.

Zgodnie z standardem llmstxt.org oddajemy dwa pliki:

• /llms.txt - indeks wszystkich stron dokumentacji, zgrupowany w sekcjach (API Reference, Use Cases, Przykłady, Produkty). Mapa dla agenta, z czego zacząć.
• /llms-full.txt - cała dokumentacja w jednym pliku tekstowym. Dla offline-indeksacji w bazie wektorowej lub jednorazowego wstawiania w kontekście modelu.

Jeśli budujesz RAG na powierzchni naszego API, llms-full.txt - to gotowy korpus, nie trzeba kraulować strony.

Kontrakt oddaje się kilkoma formatami pod różne narzędzia:

• /v1/openapi.json - kanoniczna OpenAPI 3.1-specyfikacja z przykładami i code-samples. Dla kodogeneryj klientów i każdego OpenAPI-toolingu.
• Swagger-aliasy - /v1/swagger.json, /v1/v3/api-docs i inne 301-redirują na kanon, aby narzędzia, które szukają zwyczajne ścieżki, nie spadły.
• Postman-kolekcja - /postman/astroway-api.json dla importu w Postman jednym kliknięciem.

Strona /agent-setup/ - nie jeden ogólny gaid, ale oddzielne instrukcje pod sześć klientów: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Każda daje dokładny konfig i curl-przykład tools/list, aby sprawdzić podłączenie przed pisaniem kodu.

Na stronach dokumentacji każda operacja ma wbudowany try-it: wstawiasz sandbox-klucz, redagujesz ciało zapytania, naciskasz “Send” - i widzisz realną odpowiedź, nie wychodząc z docs. Metoda, ścieżka i przykład ciała bierze się z już zrobionego curl-snippetu, więc try-it nie robi dodatkowych zapytań po openapi.json.

Prosta teza: jeśli Twój produkt - API, dokumentacja musi być przyjazna nie tylko dla czytania oczami, ale i dla spożycia agentem. Półtora integracji dzisiaj zaczyna się od tego, że developer kładzie link na docs w Claude czy Cursor i prosi “podłącz to”. Zrobiliśmy tak, aby na końcu był czysty tekst i maszynowy kontrakt, a nie HTML, który trzeba parszować.