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

Η κλασική τεκμηρίωση φτιάχνεται για ανθρώπους: HTML με render, επισήμανση σύνταξης, sidebar, αναζήτηση. Όλο και πιο συχνά όμως τα docs δεν τα διαβάζει άνθρωπος αλλά ένας agent (Claude, Cursor, ChatGPT), στον οποίο όλο αυτό το render απλώς εμποδίζει. Χρειάζεται καθαρό κείμενο και ένα συμβόλαιο αναγνώσιμο από μηχανές.

Κάναμε την τεκμηρίωση κατάλληλη και για τους δύο. Να τι υπάρχει από κάτω.

Κάθε σελίδα της τεκμηρίωσης περιεχομένου έχει ένα ακατέργαστο δίδυμο σε Markdown στην ίδια διαδρομή με την κατάληξη .md. Αν ανοίξεις το /agent-setup, υπάρχει και το /agent-setup.md: το ίδιο κείμενο χωρίς το περίβλημα HTML, με τα MDX imports αφαιρεμένα, σερβιρισμένο ως text/markdown.

Αυτό τροφοδοτεί δύο ενέργειες στο μενού της σελίδας: Copy as Markdown (βάζει το καθαρό κείμενο στο πρόχειρο, για να το επικολλήσεις σε μια συνομιλία με μοντέλο) και View as Markdown (ανοίγει απευθείας την έκδοση .md). Ο agent δεν χρειάζεται να κάνει parse το DOM: παίρνει έτοιμο κείμενο.

Στην πάνω δεξιά γωνία κάθε σελίδας υπάρχει ένα μενού ενεργειών, φτιαγμένο ειδικά για το workflow των agents:

• 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). Ο χάρτης που δείχνει στον agent από πού να ξεκινήσει.
• /llms-full.txt: όλη η τεκμηρίωση σε ένα αρχείο plain text. Για offline indexing σε βάση διανυσμάτων ή για εφάπαξ εισαγωγή στο context ενός μοντέλου.

Αν χτίζεις RAG πάνω στο API μας, το llms-full.txt είναι έτοιμο corpus, δεν χρειάζεται να κάνεις crawl τον ιστότοπο.

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

• /v1/openapi.json: η κανονική προδιαγραφή OpenAPI 3.1 με παραδείγματα και code samples. Για παραγωγή clients και κάθε εργαλείο OpenAPI.
• Aliases τύπου Swagger: τα /v1/swagger.json, /v1/v3/api-docs και άλλα κάνουν 301 redirect στην κανονική διαδρομή, ώστε τα εργαλεία που ψάχνουν τις συνηθισμένες διαδρομές να μη σκοντάφτουν.
• Συλλογή Postman: /postman/astroway-api.json για import στο Postman με ένα κλικ.

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

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

Η θέση είναι απλή: αν το προϊόν σου είναι API, η τεκμηρίωση πρέπει να είναι κατάλληλη όχι μόνο για ανάγνωση με τα μάτια, αλλά και για κατανάλωση από agent. Οι μισές ενσωματώσεις σήμερα ξεκινούν με έναν developer που ρίχνει έναν σύνδεσμο προς τα docs στο Claude ή στο Cursor και ζητά “σύνδεσέ το”. Φροντίσαμε ώστε στην άλλη άκρη να υπάρχει καθαρό κείμενο και συμβόλαιο για μηχανές, όχι HTML που πρέπει να γίνει parse.

Δοκίμασέ το: άνοιξε οποιαδήποτε σελίδα των docs, πάτησε το μενού ενεργειών πάνω δεξιά και θα δεις το “Open in Claude”.