Πώς να γράψετε καλή αναφορά σφάλματος (για AI ή developer)

Μια καλή αναφορά σφάλματος επιτρέπει σε κάποιον άλλον — έναν developer ή μια AI — να δει το ίδιο πρόβλημα που είδατε εσείς, χωρίς να σας κάνει ερωτήσεις. Χρειάζεται συγκεκριμένο τίτλο, τα ακριβή βήματα για να αναπαραχθεί, τι περιμένατε, τι συνέβη πραγματικά, κάθε μήνυμα σφάλματος αντιγραμμένο λέξη προς λέξη, και πού συνέβη: ποια σελίδα, browser, συσκευή και χρήστης. Ένα σφάλμα ανά αναφορά, με στιγμιότυπο οθόνης αν βοηθά.

Τα περισσότερα σφάλματα παίρνουν περισσότερο χρόνο για να κατανοηθούν παρά για να διορθωθούν. Μια σαφής αναφορά αφαιρεί το κομμάτι της κατανόησης. Αυτό έχει ακόμα μεγαλύτερη σημασία με τα εργαλεία AI: μια AI δεν μπορεί να κάνει συμπληρωματική ερώτηση για το τι εννοούσατε με το «το checkout είναι περίεργο», οπότε μαντεύει — και μια λάθος εικασία μπορεί να χαλάσει κάτι άλλο.

Το πρότυπο

Αντιγράψτε το και συμπληρώστε το:

Τίτλος: [Τι δεν πάει καλά, πού] — π.χ. «Η φόρμα κρατήσεων απορρίπτει ώρες μετά τις 6μμ»

Βήματα για αναπαραγωγή:
1. ...
2. ...
3. ...

Αναμενόμενο: [τι θα έπρεπε να συμβεί]
Πραγματικό: [τι συνέβη αντί γι' αυτό]

Μήνυμα σφάλματος: [ακριβές κείμενο, αν υπάρχει]
Πού: [σελίδα/URL, browser, συσκευή, με ποιον χρήστη συνδεδεμένοι]
Πόσο συχνά: [κάθε φορά / μερικές φορές / μία φορά]
Στιγμιότυπο ή εγγραφή: [επισυνάπτεται]

Το υπόλοιπο του οδηγού εξηγεί κάθε μέρος.

Βήμα 1: Αναπαράγετέ το πρώτα

Πριν γράψετε, προσπαθήστε να ξαναγίνει το σφάλμα. Θα μάθετε ποια βήματα έχουν σημασία και αν συμβαίνει κάθε φορά.

• Ξεκινήστε από καθαρή κατάσταση: ανανεώστε τη σελίδα ή κάντε αποσύνδεση και ξανά σύνδεση.
• Σημειώστε κάθε κλικ και κάθε πράγμα που πληκτρολογήσατε.
• Προσπαθήστε να βρείτε τη συντομότερη διαδρομή που το ενεργοποιεί.
• Δοκιμάστε έναν δεύτερο browser ή λογαριασμό. Αν συμβαίνει μόνο σε έναν χρήστη, αυτό είναι μεγάλη ένδειξη.

Για περισσότερα, δείτε πώς να κάνετε debugging σε εφαρμογή φτιαγμένη με AI.

Βήμα 2: Γράψτε συγκεκριμένο τίτλο

Ο τίτλος πρέπει να λέει τι δεν πάει καλά και πού, ώστε όποιος σκανάρει μια λίστα να καταλάβει ποιο σφάλμα είναι.

Βήμα 3: Καταγράψτε ακριβή βήματα

Αριθμήστε τα. Να είστε κυριολεκτικοί: ποια σελίδα, ποιο κουμπί, τι πληκτρολογήσατε.

1. Συνδεθείτε ως πελάτης (δοκιμαστικός λογαριασμός: customer@example.com).
2. Προσθέστε το «Starter kit» στο καλάθι.
3. Εισάγετε τον κωδικό έκπτωσης WELCOME10 και πατήστε Apply.
4. Πατήστε Checkout.

Το «δοκίμασε να κάνεις checkout με κωδικό» παραλείπει τις λεπτομέρειες που συχνά έχουν σημασία: ποιος χρήστης, ποιο προϊόν, ποιος κωδικός, αν εφαρμόστηκε πρώτα.

Βήμα 4: Αναμενόμενο έναντι πραγματικού

Αυτό είναι η καρδιά της αναφοράς. Γράψτε και τα δύο, γιατί η διαφορά είναι το σφάλμα.

• Αναμενόμενο: Η σελίδα checkout ανοίγει με την έκπτωση 10% να φαίνεται στο σύνολο.
• Πραγματικό: Το κουμπί δείχνει ένα spinner για ένα δευτερόλεπτο, και μετά τίποτα. Χωρίς κωδικό έκπτωσης, το checkout δουλεύει.

Χωρίς το «αναμενόμενο», ο αναγνώστης μπορεί να μην ξέρει ότι η συμπεριφορά είναι λάθος. Χωρίς το «πραγματικό», δεν ξέρει τι να ψάξει.

Βήμα 5: Αντιγράψτε τα σφάλματα ακριβώς

Τα μηνύματα σφάλματος είναι ο ταχύτερος δρόμος προς την αιτία. Αντιγράψτε τα ως κείμενο, λέξη προς λέξη — μην τα παραφράζετε.

Πού να τα βρείτε:

• Στην οθόνη: κάθε μήνυμα που δείχνει η εφαρμογή.
• Κονσόλα browser: ανοίξτε τα εργαλεία προγραμματιστή (F12, ή δεξί κλικ → Inspect) και δείτε την καρτέλα Console για κόκκινες γραμμές.
• Καρτέλα Network: στα εργαλεία προγραμματιστή, βρείτε το αίτημα που απέτυχε και σημειώστε το URL και τον κωδικό κατάστασης (για παράδειγμα POST /api/checkout → 500).
• Logs του server, αν έχετε πρόσβαση.

Μια γραμμή όπως TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 συχνά δείχνει κατευθείαν στο πρόβλημα.

Βήμα 6: Προσθέστε πλαίσιο

• Πού: το URL της σελίδας, το περιβάλλον (προεπισκόπηση, staging ή ζωντανό).
• Ποιος: ποιος χρήστης ή ρόλος — διαχειριστής, μέλος, αποσυνδεδεμένος.
• Συσκευή και browser: το «Safari σε iPhone» έναντι του «Chrome σε Windows» μπορεί να έχει σημασία.
• Δεδομένα: κάτι ασυνήθιστο στην εγγραφή — πολύ μακρύ κείμενο, ειδικοί χαρακτήρες, μεγάλος αριθμός στοιχείων.
• Πότε ξεκίνησε: το «μετά την αλλαγή που κάναμε χθες στους κωδικούς έκπτωσης» είναι χρυσάφι.
• Πόσο συχνά: κάθε φορά, ή μία στις δέκα.

Βήμα 7: Δείξτε το

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

Γράφοντας αναφορές σφαλμάτων για εργαλείο AI

Η ίδια δομή λειτουργεί και ως prompt. Δύο προσθήκες βοηθούν:

• Πείτε τι δεν πρέπει να αλλάξει, ώστε η διόρθωση να μην προκαλέσει νέο πρόβλημα.
• Ζητήστε να επαληθεύσει τη διόρθωση, όχι μόνο να τη γράψει.

Συνδεδεμένος ως πελάτης, με το «Starter kit» στο καλάθι και τον κωδικό WELCOME10 εφαρμοσμένο, το πάτημα του Checkout δεν κάνει τίποτα. Αναμενόμενο: η σελίδα checkout ανοίγει με 10% έκπτωση στο σύνολο. Πραγματικό: ένα σύντομο spinner και μετά τίποτα. Η καρτέλα network δείχνει ότι το POST /api/checkout επέστρεψε 500. Το checkout χωρίς κωδικό δουλεύει. Βρες την αιτία και διόρθωσέ την χωρίς να αλλάξεις τον τρόπο που υπολογίζονται οι τιμές για παραγγελίες χωρίς κωδικό. Μετά έλεγξε το checkout με κωδικό ποσοστού, κωδικό σταθερού ποσού και χωρίς κωδικό.

Αν δεν είστε σίγουροι για την αιτία, ζητήστε πρώτα διάγνωση:

Μην αλλάξεις κώδικα ακόμα. Με βάση αυτή την αναφορά, ποιες είναι οι πιθανές αιτίες, και τι θα επιβεβαίωνε την καθεμία;

Συνηθισμένα λάθη

• «Είναι χαλασμένο.» Χωρίς βήματα, χωρίς αναμενόμενο αποτέλεσμα, τίποτα να γίνει.
• Πολλά σφάλματα σε μία αναφορά. Κάποια διορθώνονται, άλλα χάνονται.
• Παραφρασμένα σφάλματα. Το «κάποιο undefined πράγμα» κρύβει το χρήσιμο μέρος.
• Παράλειψη χρήστη ή ρόλου. Πολλά σφάλματα αφορούν μόνο διαχειριστές ή μόνο νέους χρήστες.
• Περιγραφή μόνο της διόρθωσης που θέλετε («πρόσθεσε έλεγχο null») αντί για το πρόβλημα.
• Κοινοποίηση μυστικών σε στιγμιότυπα οθόνης ή επικολλημένα logs.

Λίστα ελέγχου

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

Αναφορά σφαλμάτων στον agent του Mythex

Σε ένα έργο Mythex, η αναφορά είναι το prompt. Μερικές λειτουργίες βοηθούν:

• Επισυνάψτε ένα στιγμιότυπο της προεπισκόπησης ή της οθόνης σφάλματος — έως 5 αρχεία ανά μήνυμα.
• Η εντολή /fix εστιάζει τον agent στη διόρθωση ενός σφάλματος· η λειτουργία Plan του επιτρέπει να ερευνήσει πριν αλλάξει κώδικα.
• Η εντολή /test βάζει τον agent να αναπαράγει ροές μέσα στην ίδια την προεπισκόπηση και να αναφέρει τι βλέπει.
• Revert to this point αναιρεί μια διόρθωση που έκανε τα πράγματα χειρότερα.

Η σελίδα της τεκμηρίωσης για debugging με prompts χρησιμοποιεί την ίδια δομή βημάτων / αναμενόμενου / πραγματικού. Για τον κύκλο διόρθωσης και ελέγχου γύρω της, δείτε πώς να επαναλαμβάνετε τη δουλειά σε εφαρμογή φτιαγμένη με AI.

Ερωτήσεις