Όταν ένας AI agent παρεκτρέπεται, φτιάξε τη ντοκιμαντέισον και δοκίμασέ την

Σε έργα λογισμικού με αυτοματοποιημένους agents, τα προβλήματα συχνά δεν οφείλονται στο μοντέλο αλλά στην έλλειψη σαφούς τεκμηρίωσης. Ως συνσυντηρητής του XMLUI, έχω δει επανειλημμένα agents που «στραβώνουν» επειδή οι σωστές πληροφορίες απλώς δεν είναι προσβάσιμες στον μηχανισμό αναζήτησης που χρησιμοποιούν. Η λύση που περιγράφω παρακάτω είναι απλή αλλά συστηματική: άνοιξε ένα issue, γράψε το χαμένο documentation ως επισήμαντο διορθωτικό και χρησιμοποίησέ το ως τεστ για να αποδείξεις ότι η συστοιχία αναζήτησης πράγματι βελτιώθηκε.

Η ιδέα δεν είναι μόνο να φτιάξεις ένα άρθρο· είναι να το κάνεις «testable fix». Όταν ένα agent αποτυγχάνει να βρει την απάντηση, η προσθήκη ή η διόρθωση της τεκμηρίωσης πρέπει να παράγει μετρήσιμη αύξηση της σχετικότητας στις ερωτήσεις που απέτυχαν προηγουμένως. Στο παράδειγμα που ακολουθεί χρησιμοποίησα τον Claude για να αναπαράγω τις αποτυχίες και το MCP για να συγκρίνω εκδόσεις της τεκμηρίωσης.

Πώς αναδεικνύεται το πρόβλημα: αποτυχίες αναζήτησης, όχι μοντέλου

Το πρώτο βήμα είναι να καταγράψεις ακριβώς τι αναζήτησαν οι agents και τι επέστρεψαν. Στην περίπτωση του XMLUI, οι αποτυχημένες αναζητήσεις αφορούσαν μια απλή μετατροπή UI component: την αλλαγή ενός select στοιχείου σε radio buttons. Οι query logs έδειξαν δύο αποτυχημένες αναζητήσεις μέσα σε λίγα λεπτά, αλλά τα αποτελέσματα που επέστρεψε το σύστημα ήταν άσχετα — τεκμηρίωση για prefill, regex validation και άλλα θέματα φόρμας, όχι για radio groups.

Αυτή η διαφορά δείχνει ένα χρήσιμο διαγνωστικό: όταν το language model δίνει λογικές αλλά λανθασμένες απαντήσεις, συνήθως δεν «εφευρίσκει» — απλώς βασίζεται σε έγγραφα που δεν απαντούν στο συγκεκριμένο πρόβλημα. Είναι διαφορετικό σφάλμα από την κλασική «hallucination»: εδώ το retrieval δεν έφερε το σωστό πλαίσιο.

Παραδείγμα ο πραγματικός έλεγχος με μέτρηση σχετικότητας

Για να αξιολογήσω την επίδραση της νέας τεκμηρίωσης, πρώτα τράβηξα τις αρχικές αναζητήσεις και σημείωσα ότι οι κορυφαίες ανταποκρίσεις είχαν μέγιστο score γύρω στο 0.7. Με άλλα λόγια, το σύστημα θεωρούσε τις διαθέσιμες σελίδες μέτρια σχετικές. Έγραψα λοιπόν τη missing doc —ένα συγκεκριμένο how-to για το select-to-radio conversion— και την πρόσθεσα στο repository των docs.

Στη συνέχεια επανέτρεξα τις ίδιες αναζητήσεις και ζήτησα από το MCP να χρησιμοποιήσει την καινούρια έκδοση των τεκμηριώσεων. Το αποτέλεσμα ήταν σαφές: η καινούρια σελίδα εμφανίστηκε στην πρώτη θέση με relevance score 4.2, περίπου έξι φορές υψηλότερο από την προηγούμενη κορυφαία αντιστοιχία. Πολύ απλό και πολύ δυνατό ως απόδειξη ότι το πρόβλημα δεν ήταν το μοντέλο αλλά το index.

Τι σημαίνουν τα scores και πώς να τα διαβάσετε

Οι μηχανές αναζήτησης για RAG (retrieval-augmented generation) δεν επιστρέφουν απλώς «σωστό» ή «λάθος». Επιστρέφουν βαθμούς σχετικότητας που εξαρτώνται από τον αλγόριθμο (tf-idf, BM25, ή vector similarity), το preprocessing και το weighting των πεδίων. Ένα score 0.7 μπορεί να σημαίνει «αρκετά κοντά» αλλά πρακτικά ανεπαρκές για ένα agent που απαιτεί συγκεκριμένο how-to, ενώ ένα score 4.2 δείχνει κορυφαία αντιστοίχιση στον ίδιο αλγόριθμο και την ίδια κλίμακα.

Είναι σημαντικό να καταλάβεις την κλίμακα της πλατφόρμας σου: σε κάποιες μηχανές η διαφορά 0.7 → 4.2 είναι τεράστια, σε άλλες μπορεί να έχει άλλη ερμηνεία. Όμως το κρίσιμο είναι η σύγκριση A/B: όταν το MCP επιτρέπει να «pinάρεις» μια συγκεκριμένη έκδοση των docs και να συγκρίνεις side-by-side τα αποτελέσματα, αποκτάς ένα ρεαλιστικό πείραμα αντί για εικασίες.

Πρακτική ρουτίνα για maintainers: από το issue ως το CI test

Η ρουτίνα που εφαρμόζω περιλαμβάνει μερικά σταθερά βήματα. Αρχικά, όταν εντοπίζεται αποτυχία, συζητάμε αν πρόκειται για έλλειψη τεκμηρίωσης ή για κακή αναζήτηση. Αν είναι το πρώτο, ανοίγουμε issue και αναθέτουμε σύντομο how-to που απαντά συγκεκριμένα στο ερώτημα που απέτυχε. Το κείμενο δεν πρέπει να είναι γενικό — πρέπει να ανταποκρίνεται στις queries που είδαν αποτυχία.

Μετά την προσθήκη του doc, επαναφέρουμε τις αποτυχημένες queries και καταγράφουμε τα νέα scores. Αυτή η μέτρηση μπορεί να αυτοματοποιηθεί στο CI: όταν κάποιο PR τεκμηρίωσης ανεβαίνει, ένα test τρέχει predefined queries και ελέγχει ότι το top-k relevance βελτιώνεται πάνω από threshold. Αυτό μετατρέπει την τεκμηρίωση σε ελεγχόμενο, μετρήσιμο κομμάτι του έργου.

Πώς να γράφεις docs που «πιάνονται» από τους agents

Υπάρχουν απλές τεχνικές που αυξάνουν την πιθανότητα μια σελίδα να βρεθεί από τον retrieval layer. Πρώτον, χρησιμοποίησε ποικιλία όρων: agents μπορεί να αναζητήσουν από «radio group mutually exclusive choice» ως «choose one of two options horizontal selector», οπότε η σελίδα πρέπει να περιλαμβάνει συνώνυμα και UX/technical όρους. Δεύτερον, ξεκίνα με ένα σαφές H1 και σύντομη περίληψη του προβλήματος και της λύσης —οι search engines προτιμούν καλά δομημένο περιεχόμενο.

Τρίτον, πρόσθεσε παραδείγματα κώδικα και μικρά κομμάτια “before/after”. Τα agents συχνά αξιολογούν τεκμήρια που περιέχουν ρητά patterns και code snippets πιο υψηλά. Τέλος, συμπεριλαμβάνεις metadata και tags (π.χ. component: radio, category: form controls) όταν το index σου τα υποστηρίζει —αυτά αυξάνουν την ακρίβεια του matching χωρίς να φορτώνουν τον χρήστη.

Σύνθετες αιτίες αποτυχίας: ακροπάτημα ανάμεσα σε UX και τεχνικούς όρους

Στο παράδειγμα του XMLUI, η δεύτερη αποτυχημένη query ήταν πιο UX-εστιασμένη (“choose one of two options horizontal selector”) ενώ η πρώτη ήταν component-centric. Αυτό δείχνει μια συχνή παγίδα: οι χρήστες (ή τα agents που μιμούνται ανθρώπινες ερωτήσεις) μπορεί να σκεφτούν προβλήματα από διαφορετικές οπτικές. Αν τα έγγραφα απαντούν μόνο σε API-όρους, χάνουν τις ερωτήσεις που προέρχονται από την UX πλευρά. Καλύτερη πρακτική είναι να καλύψεις και τις δύο όψεις με σύντομες ενότητες που εξηγούν την πρόθεση και την τεχνική λύση.

Επιπλέον, η “θορυβώδης” τεκμηρίωση που αναφέρεται σε πολλά συναφή θέματα μπορεί να μειώσει τη σχετικότητα. Η λύση δεν είναι πάντα περισσότερη τεκμηρίωση, αλλά στοχευμένη, σαφής και retrievable τεκμηρίωση.

Εργαλεία και μετρικές που αξίζει να παρακολουθείς

Για να κρατήσεις το σύστημα υγιές, παρακολούθησε τα εξής: τα top-k relevance scores για σύνολο χαρακτηριστικών queries, hit-rate (πόσες queries βρίσκουν σχετικό doc πάνω από threshold), latency αναζήτησης και ποσοστό fallback όπου το μοντέλο απαντά χωρίς retrieval. Αυτές οι μετρικές δείχνουν πότε πρέπει να γράψεις νέο doc ή να αναδομήσεις τον index.

Αν το platform σου το επιτρέπει, κάνε A/B tests με pinning εκδόσεων, όπως έγινε με το MCP στο παράδειγμα. Αυτό επιτρέπει να αντιπαραβάλεις πραγματικά αποτελέσματα και να αποφασίζεις με δεδομένα πότε μια αλλαγή τεκμηρίωσης αξίζει merge.

Τι σημαίνει αυτό για τις ομάδες ανάπτυξης και τους χρήστες

Για teams, η κύρια συνέπεια είναι ότι η τεκμηρίωση παύει να είναι «δευτερεύουσα εργασία» και γίνεται μέρος της λειτουργίας του συστήματος. Να την αντιμετωπίζεις ως κώδικα: review, tests, CI, versioning. Οι maintainers κερδίζουν χρόνο και λιγότερα issue threads όταν κάθε κοινό πρόβλημα έχει ένα ξεκάθαρο, εύκολα ανακτησιμo doc.

Για τους τελικούς χρήστες και τους consumer-facing agents, αυτό σημαίνει πιο αξιόπιστες απαντήσεις, λιγότερες λανθασμένες συστάσεις UI και μεγαλύτερη ταχύτητα επίλυσης προβλημάτων. Όταν ένα agent αντιλαμβάνεται σωστά τη διαφορά μεταξύ μιας general φόρμας και ενός συγκεκριμένου radio group pattern, η εμπειρία του χρήστη γίνεται πιο συνεκτική και προβλέψιμη.

Τι αλλάζει στην πράξη

Η πρακτική του “report issue → write doc → test impact” μετατρέπει ένα άυλο πρόβλημα (ο agent απέτυχε) σε μετρήσιμη εργασία που μπορεί να προγραμματιστεί, να ανατεθεί και να τιμολογηθεί. Δεν είναι πάντα η λύση σε όλα —κάποιες αποτυχίες προέρχονται από αδυναμίες του μοντέλου ή από ανακριβή δεδομένα εισόδου— αλλά είναι το πιο φθηνό και αποδοτικό πρώτο βήμα.

Στο επίπεδο της πλατφόρμας, εντάσσοντας τέτοια τεστ στο CI και παρακολουθώντας τα metrics, μειώνεις συστηματικά την πιθανότητα επανάληψης των ίδιων σφαλμάτων. Και για κοινότητες ανοιχτού κώδικα, δίνεις σαφή process για contributors: όχι μόνο κώδικας, αλλά και τεκμηρίωση που αποδεικνύεται ότι «δουλεύει» για τα agents.