Τεκμηρίωση, φτιαγμένη για AI-πράκτορες, όχι μόνο για ανθρώπους

Παραδοσιακή τεκμηρίωση κάνει την εμφάνισή της: η HTML, η φυσική σύνταξη, ο sidebar, η αναζήτηση. Αλλά όχι πια ο άνθρωπος, ο Claude, ο Cursor, ο ChatGPT. Ο αγγελιαδάς δεν χρειάζεται τον ρεντερ. Χρειάζεται μόνο τον καθαρό κώδικα και τον μηχανόνομο συμβόλαιο.

Έκαναν την τεκμηρίωση κατάλληλη για και για τον αγγελιαδά. Δείτε τι κρύβεται κάτω από τον ρεντερ.

Κάθε σελίδα της τεκμηρίωσης έχει ένα αντίγραφο Markdown-αρχείου με την ίδια ονομασία αλλά με суфікκο .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 - ανοίξτε την σελίδα στο ChatGPT με ένα κλικ
• Open in Claude - το ίδιο για τον Claude
• Connect MCP - μεταβείτε στην οθόνη ρυθμίσεων του MCP-server

Αντικατάστε “κάντε κλικ στην URL, ανοίξτε το διάλογο, ζητήστε να εισέλθετε στην σελίδα” με μια ενέργεια.

Σύμφωνα με το πρότυπο llmstxt.org παραδίδουμε δύο αρχεία:

• /llms.txt - ο δείκτης όλων των σελίδων της τεκμηρίωσης, συσσωματισμένος σε ενότητες (API Reference, Use Cases, Examples, Products). Ο δείκτης για τον αγγελιαδά, από όπου ξεκινάτε.
• /llms-full.txt - η ολόκληρη τεκμηρίωση ως plain-text αρχείο. Για την offline-ινдексήση σε μια βιομηχανική βάση ή για την έναρξη μιας ενιαίας εισαγωγής σε ένα διάλογο.

Αν κάνετε ένα RAG πάνω από τον API μας, llms-full.txt είναι ο καθαρός κώδικα, δεν χρειάζεται να κάνετε κράουλινγκ στην ιστοσελίδα.

Ο συμβόλαιο παραδίδεται σε διάφορους μορφές για διαφορετικούς εργαλεία:

• /v1/openapi.json - η κανόνιση OpenAPI 3.1-συμβόλαιο με παραδείγματα και code-samples. Για την κωδικοποίηση των πελάτων και οποιοδήποτε OpenAPI-εργαλείο.
• Swagger-αλυσίδες - /v1/swagger.json, /v1/v3/api-docs και άλλες 301-μεταφράσεις στο κανόνι, για τα εργαλεία που αναζητούν τις συνηθισμένες διαδρομές.
• Postman-συλλογή - /postman/astroway-api.json για την εισαγωγή στην Postman με ένα κλικ.

Η σελίδα /agent-setup/ - δεν είναι ένας γενικός οδηγός, αλλά συγκεκριμένες οδηγίες για επτά πελάτες: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Κάθε μια δίνει τον ακριβή ρυθμισμό και curl-παράδειγμα tools/list, για να ελέγξετε την σύνδεση πριν από την κωδικοποίηση.

Στις σελίδες της API-τεκμηρίωσης κάθε ενέργεια έχει ένα inline-εργαλείο try-it: εισάγετε τον sandbox-κωδικό, επεξεργαστείτε το σώμα της αιτήσεως, πατήστε “Send” - και θα δείτε την πραγματική απάντηση, χωρίς να βγείτε από την τεκμηρίωση. Ο μορφής, η διαδρομή και το παράδειγμα του σώματος λαμβάνονται από το ήδη συσσωματισμένο curl-snippet, οπότε το εργαλείο δεν κάνει επιπλέον αιτήματα στην openapi.json.

Η απλή ιδέα: αν ο προϊόν σας είναι API, η τεκμηρίωση πρέπει να είναι κατάλληλη όχι μόνο για την ανάγνωση με τα μάτια, αλλά και για την κατανάλωση από τον αγγελιαδά. Η μισή από τις συνδετήσεις σήμερα ξεκινά με το να κάνετε κλικ στην URL, να ανοίξετε το διάλογο και να ζητήσετε “συνδέστε το”. Έκαναμε έτσι, ώστε να παραδίδουμε τον καθαρό κώδικα και τον μηχανόνομο συμβόλαιο, και όχι HTML, που πρέπει να παραλύσετε.