Dokumentáció, amelyet AI-ügynököknek készítettek, nem csak embereknek

Az klasszikus dokumentáció emberre van szabva: renderelt HTML, szintaxiskiemelés, oldalsáv, keresés. De egyre gyakrabban nem ember jár a docs-ban, hanem egy ügynök – Claude, Cursor, ChatGPT – akinek ez a render csak zavar. Neknek tiszta szöveg és gépileg olvasható szerződés kell.

Mi a dokumentációt mindkettőnek alkalmasra tettük. Íme, mi van a motorban.

Az egyes tartalom-dokumentációs oldalaknak van egy nyers Markdown duplikátja ugyanazon az úton .md kiterjesztéssel. Ha megnyitod a /agent-setup-ot – létezik a /agent-setup.md is, ugyanaz a szöveg HTML burkolás nélkül, a MDX importok levágva, text/markdown‑ként szolgálva.

Ez két műveletet táplál a lap menüjében: Copy as Markdown (tiszta szöveget helyez a vágólapra, hogy be tudd illeszteni a modell chatjébe) és View as Markdown (közvetlenül megnyitja a .md verziót). Az ügynöknek nem kell DOM‑ot parse‑olnia – egyszerűen veszi a kész szöveget.

A minden oldal jobb felső sarkában – egy műveletmenü, amely kifejezetten az ügynök munkafolyamatához készült:

• Copy as Markdown – a lap tiszta szövege a vágólapra
• View as Markdown – a .md duplikát megnyitása
• Open in ChatGPT – a lap átadása a ChatGPT‑nek egy kattintással
• Open in Claude – ugyanaz Claude‑nál
• Connect MCP – átmenet az MCP‑szerver beállításához

A „másold ki az URL‑t, nyisd meg a chatet, kérd meg, hogy nyissa meg az oldalt” helyett – egyetlen művelet.

A llmstxt.org szabvány szerint két fájlt biztosítunk:

• /llms.txt – az összes dokumentációs oldal indexe, szekciókba csoportosítva (API Reference, Use Cases, Examples, Products). Egy térkép az ügynöknek, hogy hol kezdje.
• /llms-full.txt – a teljes dokumentáció egyetlen plain‑text fájlként. Offline indexeléshez vektoros adatbázisban vagy egyszeri beillesztéshez a modell kontextusába.

Ha RAG‑ot építesz a mi API‑nkra, a llms-full.txt egy kész korpusz, nem kell a weboldalt feltérképezni.

A szerződés több formátumban érhető el különböző eszközökhöz:

• /v1/openapi.json – a kanonikus OpenAPI 3.1 specifikáció példákkal és code‑samples‑ekkel. Klienskód‑generáláshoz és bármely OpenAPI‑eszközhöz.
• Swagger‑aliasok – /v1/swagger.json, /v1/v3/api-docs és egyéb 301‑átirányítás a kanonikusra, hogy a szokásos útvonalakat kereső eszközök ne akadjanak el.
• Postman‑gyűjtemény – /postman/astroway-api.json a Postman‑ba egy kattintással történő importáláshoz.

A /agent-setup/ oldal nem egy általános útmutató, hanem különálló instrukciók hét klienshez: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Mindegyik pontos konfigurációt és egy tools/list curl‑példát ad, hogy a kód írása előtt ellenőrizd a csatlakozást.

Az API‑referencia oldalaknál minden művelet beágyazott try-it widgettel rendelkezik: beilleszted a sandbox kulcsot, szerkeszted a kérés törzsét, megnyomod a „Send”‑et – és a valós választ látod anélkül, hogy elhagynád a docs‑ot. A metódus, az útvonal és a törzspélda a már generált curl‑snippetből származik, így a widget nem küld felesleges kéréseket az openapi.json‑ra.

Egyszerű állítás: ha a terméked egy API, a dokumentációnak nem csak emberi olvasásra, hanem az ügynök általi fogyasztásra is alkalmasnak kell lennie. A mai integrációk felét úgy indítja, hogy a fejlesztő egy docs linket dob Claude‑ba vagy Cursor‑ba, és azt kéri: „csatlakoztasd ezt”. Mi úgy csináltuk, hogy a másik végén tiszta szöveg és gépi szerződés legyen, nem HTML, amit parse‑olni kell.

Próbáld ki magad: nyiss meg bármelyik docs oldalt, kattints a jobb felső sarokban lévő műveletmenüre – és látni fogod a „Open in Claude” gombot.