Γιατί ο πράκτορας προγραμματισμού AI σας επινοεί διαδρομές αρχείων

Το τεκμήριο δεν είναι ένα λάθος σώμα συνάρτησης. Είναι μια σίγουρη επεξεργασία σε ένα αρχείο που δεν υπάρχει, ή σε ένα αρχείο που υπάρχει αλλά δεν είναι αυτό που υλοποιεί τη συμπεριφορά.

Ζητήσατε μια διόρθωση λήξης συνεδρίας. Ο πράκτορας άνοιξε το src/auth/session.ts. Αυτή η διαδρομή είναι εύλογη. Είναι επίσης λάθος. Ο πραγματικός χειριστής ζει στο apps/api/src/middleware/expiry.ts, που μετονομάστηκε πριν από δύο αναδιαμορφώσεις κώδικα. Ο πράκτορας δεν σας είπε ψέματα. Συμπλήρωσε μια συμβολοσειρά σε σχήμα διαδρομής από όσα έμαθε στην εκπαίδευσή του συν ό,τι ήδη υπήρχε στο παράθυρο συμφραζομένων.

Αυτό είναι το συνηθισμένο μοτίβο αποτυχίας σε ένα πραγματικό αποθετήριο. Το μοντέλο ξέρει να γράφει κώδικα. Το λάθος είναι στην επιλογή του λάθος μέρους για να τον γράψει.

Γιατί οι πράκτορες επινοούν διαδρομές αρχείων

Ένας πράκτορας προγραμματισμού είναι ένα μοντέλο πρόβλεψης επόμενου token με εργαλεία. Όταν λέτε «διόρθωσε τη λήξη συνεδρίας», πρέπει να ονομάσει ένα αρχείο πριν μπορέσει να διαβάσει ή να κάνει patch σε οτιδήποτε. Αν δεν έχει ήδη έναν θεμελιωμένο χάρτη, κατασκευάζει μια διαδρομή από:

1. Συμβάσεις ονομασίας που έχει δει σε άλλα αποθετήρια. Το src/auth/session.ts είναι συχνό σχήμα.
2. Αρχεία ήδη παρόντα στη συνομιλία, που μπορεί να είναι αυτά που επικολλήσατε την περασμένη εβδομάδα, όχι αυτά που μετράνε τώρα.
3. Λίστες καταλόγων που έτυχε να τρέξει, ελλιπείς σε ένα μεγάλο δέντρο.
4. Αρχεία οδηγιών. Τα CLAUDE.md και AGENTS.md λένε στον πράκτορα πώς να συμπεριφέρεται. Δεν είναι ζωντανό ευρετήριο συμβόλων, καλούντων ή τρεχουσών διαδρομών.

Καμία από αυτές τις πηγές δεν είναι χάρτης αυτού του αποθετηρίου, σήμερα. Το μοντέλο γεμίζει το κενό όπως γεμίζει κάθε κενό: με μια συνέχεια υψηλής πιθανότητας. Αυτή η συνέχεια συχνά μοιάζει με πραγματική διαδρομή. Μερικές φορές το αρχείο υπάρχει και βρίσκεται δίπλα στο σωστό. Μερικές φορές υπήρχε σε έναν κλάδο που συγχωνεύθηκε τον περασμένο μήνα. Μερικές φορές δεν υπήρξε ποτέ.

Το grep δεν σας σώζει εδώ αν ο πράκτορας δεν αναζητά καν τη σωστή συμβολοσειρά. Ο πράκτορας μάντεψε μια διαδρομή, μετά διάβασε ό,τι επέστρεψε εκείνη η διαδρομή, μετά το επεξεργάστηκε. Το πρώτο λάθος βήμα ήταν η διαδρομή, όχι το patch.

Το να διαβάζετε αρχεία επίσης δεν είναι το ίδιο με το να βρίσκετε τα σωστά. Τα Claude Code, Cursor, Codex και παρόμοια εργαλεία μπορούν να ανοίξουν οτιδήποτε τους δείξετε. Το ερώτημα είναι αν βρίσκουν αξιόπιστα τα σωστά αρχεία, τα σημαντικά σύμβολα, τις εξαρτήσεις, τις δοκιμές, και την ακτίνα επίδρασης πριν επεξεργαστούν. Η πρόσβαση σε αρχεία χωρίς χάρτη εξακολουθεί να ξεκινά με μαντεψιά.

Η επεξεργασία λάθος αρχείου είναι πρόβλημα ανάκτησης

Αντιμετώπισε την επινοημένη διαδρομή ως λάθος ανάκτησης, όχι ως ελάττωμα χαρακτήρα.

Αν ο πράκτορας έπρεπε να επιστρέψει path/file.ext:line πριν του επιτραπεί να επεξεργαστεί, θα συνέβαιναν δύο πράγματα. Πρώτον, θα μπορούσατε να ανοίξετε την παραπομπή και να απορρίψετε τη δουλειά σε δέκα δευτερόλεπτα. Δεύτερον, ο πράκτορας θα έπρεπε να ρωτήσει κάτι που πράγματι γνωρίζει το δέντρο.

Αυτή είναι η δουλειά ενός επιπέδου context για τη βάση κώδικα. Η σημασιολογική αναζήτηση μόνη της δεν αρκεί. Ένα κομμάτι που «ακούγεται σαν λήξη συνεδρίας» μπορεί ακόμα να προσγειωθεί σε ένα ξεπερασμένο πακέτο. Χρειάζεστε επίσης ακριβές κείμενο όταν ξέρετε τη συμβολοσειρά, αναζήτηση συμβόλων όταν ξέρετε το όνομα, δομική αναζήτηση όταν ξέρετε το σχήμα, και έναν γράφο εξαρτήσεων όταν χρειάζεστε καλούντες και ακτίνα επίδρασης.

Το Maguyva είναι αυτό το επίπεδο για πράκτορες προγραμματισμού συμβατούς με MCP. Δεν είναι επεξεργαστής κώδικα. Τα Claude Code, Cursor, Codex CLI, VS Code, Windsurf και άλλα προγράμματα-πελάτες MCP παραμένουν εκεί που είναι. Ο πράκτορας ρωτά έναν ταξινομημένο χάρτη πριν αγγίξει μια γραμμή.

Ο ισχυρισμός είναι σκόπιμα μετριοπαθής: λιγότερες παραισθητικές επεξεργασίες. Το Maguyva δεν αφαιρεί από το μοντέλο την ικανότητα να μαντεύει. Αλλάζει το προεπιλεγμένο πρώτο βήμα από «επινόησε μια εύλογη διαδρομή» σε «ζήτησε ταξινομημένες, παραπεμπόμενες τοποθεσίες».

Πώς μοιάζει μια θεμελιωμένη απάντηση

Μια χρήσιμη απάντηση στο «πού διαχειρίζεται η λήξη συνεδρίας» δεν είναι μια παράγραφος. Είναι μια σύντομη λίστα τοποθεσιών:

• apps/api/src/middleware/expiry.ts:48 - ο χειριστής
• apps/web/src/lib/auth-client.ts:112 - ο καλών
• apps/api/tests/expiry.test.ts:20 - η δοκιμή που θα αποτύχει αν η αλλαγή είναι λάθος

Μπορείτε να ανοίξετε αυτές τις γραμμές. Αν είναι λάθος, σταματάτε. Αν είναι σωστές, ο πράκτορας μπορεί να επεξεργαστεί. Η επαλήθευση είναι το θέμα, όχι ένα σύνθημα.

Το Maguyva εκθέτει 11 εργαλεία MCP για το πρόγραμμα-πελάτη, που καλύπτουν αναζήτηση, σύμβολα, ανάλυση εξαρτήσεων, ανάκτηση αρχείων, context αποθετηρίου και ντετερμινιστικές ροές εργασίας βοηθητικών εργαλείων. Τέσσερις τρόποι ανάκτησης (σημασιολογικός, δομικός, γράφου/εξαρτήσεων και κειμενικός) συγχωνεύονται σε ταξινομημένα αποτελέσματα· η αναζήτηση συμβόλων είναι ξεχωριστό εργαλείο MCP (find_symbol). Θεμελιωμένες απαντήσεις επιστρέφουν με διαδρομές αρχείων και αριθμούς γραμμής, ώστε να μπορείτε να τις βαθμολογήσετε ως προς το δέντρο μπροστά σας.

Η τεκμηρίωση περιγράφει τη συντομότερη διαδρομή: ξεκινήστε δωρεάν, ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε, συνδέστε το πρόγραμμα-πελάτη, μετά κάντε μία ερώτηση που μπορείτε να επαληθεύσετε.

Ένας βρόχος που αλλάζει την πρώτη επεξεργασία

Δεν χρειάζεστε μια νέα θρησκεία ροής εργασίας. Χρειάζεστε ένα επιπλέον βήμα πριν την πρώτη εγγραφή.

1. Κάντε μια ερώτηση που ήδη μπορείτε να αξιολογήσετε. «Ποιος κώδικας διαχειρίζεται τη σύνδεση και τη λήξη συνεδρίας;» είναι καλύτερο από «διόρθωσε το auth».
2. Απαιτήστε παραπομπές. Διαδρομή αρχείου και αριθμό γραμμής, όχι μια περίληψη της «ενότητας αυθεντικοποίησης».
3. Ανοίξτε τα παραπεμπόμενα αρχεία. Ακολουθήστε το σύμβολο. Επιβεβαιώστε την εξάρτηση που πρόκειται να αγγίξετε.
4. Μόνο τότε αφήστε τον πράκτορα να κάνει patch.

Αν το βήμα 2 δεν επιστρέψει τίποτα χρήσιμο, ο πράκτορας δεν έχει δικαίωμα να αυτοσχεδιάσει μια διαδρομή. Ξαναψάχνει, ή του δείχνετε εσείς. Ακριβώς αυτή η μία πύλη είναι που παράγει λιγότερες παραισθητικές επεξεργασίες. Το μοντέλο είναι το ίδιο μοντέλο. Ο χάρτης είναι αυτό που άλλαξε.

Τα αρχεία οδηγιών εξακολουθούν να έχουν σημασία. Κρατήστε τα. Χρησιμοποιήστε τα για συμβάσεις, κανόνες αξιολόγησης, και για ό,τι δεν πρέπει να αγγίζεται. Μην τους ζητάτε να είναι το ευρετήριο. Ένα CLAUDE.md που απαριθμεί τρεις σημαντικούς καταλόγους θα είναι ξεπερασμένο μια εβδομάδα μετά τη διάσπαση ενός πακέτου. Ένας αναζητήσιμος χάρτης ενημερώνεται όταν ενημερώνεται το αποθετήριο.

Μια συναφής αποτυχία είναι το σχεδόν-σωστό αρχείο: ο πράκτορας ανοίγει το auth.ts ενώ η συμπεριφορά ζει στο auth-client.ts, ή κάνει patch σε ένα παραγόμενο αρχείο αντί για την πηγή, ή επεξεργάζεται το αντίγραφο στο packages/legacy επειδή το όνομα ταίριαξε. Οι παραπομπές δεν κάνουν αυτά τα λάθη αδύνατα. Τα κάνουν ορατά πριν προσγειωθεί το diff.

Τι δεν θα διορθώσει ένας χάρτης για εσάς

Να είστε νηφάλιοι για το τι παίρνετε. Ένας θεμελιωμένος χάρτης δεν θα κάνει κάθε επεξεργασία σωστή — ο πράκτοράς σας μπορεί ακόμα να γράψει ένα κακό patch ακριβώς στο σωστό αρχείο. Αν η βάση κώδικά σας στηρίζεται σε δυναμική αποστολή κλήσεων, ανάκλαση ή μπαλώματα κώδικα κατά την εκτέλεση, κάποιες αναζητήσεις συμβόλων θα επιστρέφουν πιο φτωχές από όσο θα θέλατε, επειδή αυτό ακριβώς κάνει η έμμεση αναφορά κατά τον χρόνο εκτέλεσης σε κάθε στατικό ευρετήριο. Και αν ελπίζετε σε ένα ποσοστό — «παραισθητικές διαδρομές μειωμένες κατά X%» — δεν θα το βρείτε εδώ, επειδή κανείς εκτός από εσάς δεν μπορεί να μετρήσει ειλικρινά αυτόν τον αριθμό για το αποθετήριό σας.

Αυτό που μπορείτε να περιμένετε είναι στενότερο και πιο χρήσιμο: ο πράκτορας σταματά να ξεκινά τις επεξεργασίες του με μια μαντεμένη διαδρομή. Αυτό το πρώτο βήμα θεμελιώνεται σε έναν πραγματικό χάρτη, και από εκεί προέρχονται οι λιγότερες παραισθητικές επεξεργασίες. Όλα μετά την παραπομπή — η ανάγνωση του diff, η κρίση του patch — παραμένουν δουλειά σας, όπως πάντα ήταν.

Το τεστ δεν σας κοστίζει σχεδόν τίποτα: ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε και κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Ξεκινήστε με μια διαδρομή που σας έχει κάψει στο παρελθόν. Αν οι παραπομπές είναι λάθος, θα το δείτε αμέσως. Αν είναι σωστές, η επόμενη επεξεργασία του πράκτορά σας έχει καλύτερο μέρος να προσγειωθεί.

// it doesn't know the file. it knows how to find it.