AI Συνέντευξη Σειρά 16: Πώς πρέπει να είναι μια καλή κωδικοποίηση spec;

Μια καλή Κωδικοποίηση Spec (προγραμματισμός βάσει προδιαγραφών) έχει ως πυρήνα τη μετατροπή μιας "θολής ιδέας" σε μια "ακριβή, επαληθεύσιμη και εκτελέσιμη σύμβαση". Δεν είναι απλώς η σύνταξη ενός εγγράφου, αλλά η δημιουργία μιας γλώσσας επικοινωνίας χωρίς ασάφειες μεταξύ ανθρώπου και AI (ή ανθρώπου με άνθρωπο). Παρακάτω θα περιγράψω πώς μοιάζει ένα καλό spec από τέσσερις διαστάσεις: δομή περιεχομένου προδιαγραφών, αρχές σύνταξης, διαδικασία συνεργασίας με AI, επαλήθευση ποιότητας.

1. Τυπική δομή εγγράφου προδιαγραφών (με παράδειγμα λειτουργικής μονάδας)

Ενότητα	Υποχρεωτικό περιεχόμενο	Παράδειγμα
1. Στόχος και πεδίο	Περιγραφή σε μία πρόταση τι κάνει, διευκρίνιση τι δεν κάνει	"Υλοποίηση API εγγραφής χρήστη, χωρίς επαλήθευση email"
2. Συμβόλαιο εισόδου/εξόδου	Δομή δεδομένων, τύποι, υποχρεωτικά/προαιρετικά πεδία, παραδείγματα τιμών	`POST /register` σώμα αίτησης `{email: string, password: string}`, απόκριση `201` ή `400` με κωδικό σφάλματος
3. Συμπεριφορά και λογική	Επιχειρηματικοί κανόνες, οριακές συνθήκες, μεταβάσεις καταστάσεων	"Το μήκος κωδικού πρόσβασης 8-20 χαρακτήρες, τουλάχιστον ένα ψηφίο· αν το email υπάρχει ήδη, επιστροφή `409`"
4. Διαχείριση σφαλμάτων	Όλα τα πιθανά σενάρια εξαίρεσης και αντίστοιχοι κωδικοί/μηνύματα σφάλματος	"Αποτυχία σύνδεσης βάσης δεδομένων → επιστροφή `503`, χωρίς έκθεση stack trace"
5. Μη λειτουργικές απαιτήσεις	Απόδοση (χρόνος απόκρισης <200ms), ασφάλεια (παραμετροποιημένα ερωτήματα), καταγραφή, παρατηρησιμότητα	"Όλα τα SQL πρέπει να χρησιμοποιούν προμεταγλωττισμένα· καταγραφή `email` χωρίς καταγραφή `password`"
6. Δοκιμαστικές περιπτώσεις (κρίσιμο)	Τουλάχιστον 3 τυπικές είσοδοι + 2 οριακές/εξαιρετικές είσοδοι, με αναμενόμενη έξοδο	Βλέπε παρακάτω πίνακα
7. Εξαρτήσεις και περιορισμοί	Ποιες βιβλιοθήκες, εκδόσεις, μεταβλητές περιβάλλοντος	"Python 3.10+, FastAPI, μεταβλητή περιβάλλοντος `DB_URL`"

Παράδειγμα δοκιμαστικών περιπτώσεων (ενσωματωμένες στο spec)

Σενάριο	Είσοδος	Αναμενόμενη έξοδος
Κανονική εγγραφή	email: `a@b.com`, pwd: `Pass1234`	`201`, επιστροφή `user_id`
Πολύ μικρός κωδικός	pwd: `Ab1`	`400`, κωδικός σφάλματος `WEAK_PASSWORD`
Email ήδη υπάρχει	ίδιο email	`409`, κωδικός σφάλματος `EMAIL_EXISTS`

Ένα καλό Spec πρέπει να γράφει πρώτα τις δοκιμαστικές περιπτώσεις, γιατί το AI μπορεί να δημιουργήσει απευθείας unit tests βάσει αυτών, τα οποία θα εκτελεστούν αυτόματα μετά την ολοκλήρωση.

2. Βασικές αρχές σύνταξης Spec (παραλλαγή SMART)

Αρχή	Εξήγηση	Αντιπαράδειγμα
Ακρίβεια (Precise)	Χρήση συγκεκριμένων αριθμών, τύπων, boolean συνθηκών· αποφυγή "όσο το δυνατόν", "συνήθως"	❌ "Ο κωδικός πρέπει να είναι αρκετά ασφαλής" → ✅ "Ο κωδικός τουλάχιστον 8 χαρακτήρες, περιέχει κεφαλαίο, πεζό, ψηφίο"
Επαληθευσιμότητα (Verifiable)	Κάθε απαίτηση μπορεί να ελεγχθεί ως επιτυχία/αποτυχία μέσω αυτοματοποιημένης δοκιμής ή χειροκίνητης επιθεώρησης	❌ "Ο κώδικας πρέπει να είναι κομψός" → ✅ "Η κυκλωματική πολυπλοκότητα συνάρτησης ≤ 10, χωρίς επαναλαμβανόμενα μπλοκ κώδικα"
Χωρίς ασάφεια (Unambiguous)	Ο ίδιος όρος έχει την ίδια σημασία σε όλο το κείμενο· αν χρειαστεί, δίνεται γλωσσάρι	❌ "Αν ο χρήστης δεν υπάρχει, επιστροφή σφάλματος" → ✅ "Ο χρήστης δεν υπάρχει → επιστροφή `404` και `{code: 'USER_NOT_FOUND'}`"
Πληρότητα (Complete)	Κάλυψη happy path, όλων των εξαιρετικών μονοπατιών, μη λειτουργικών απαιτήσεων	❌ Γράφτηκε μόνο το επιτυχημένο σενάριο → ✅ Συμπερίληψη timeout βάσης, ανεπαρκών δικαιωμάτων κλπ.
Ατομικότητα (Atomic)	Ένα spec περιγράφει μόνο ένα ανεξάρτητα παραδοτέο χαρακτηριστικό (για εύκολη ολοκλήρωση από το AI)	❌ Ένα spec για "ολόκληρο το σύστημα πληρωμών" → ✅ Διαχωρισμός σε "δημιουργία εντολής πληρωμής", "επαλήθευση callback", "επιστροφή χρημάτων"

3. Διαδικασία κωδικοποίησης Spec κατά τη συνεργασία με AI

Ο άνθρωπος γράφει το spec (με την παραπάνω δομή, ειδικά δοκιμαστικές περιπτώσεις και υπογραφές συναρτήσεων).
Το spec τροφοδοτείται μία φορά στο AI (χωρίς προσθήκη απαιτήσεων μέσω διαλόγου, αποφεύγοντας μόλυνση από vibe).
Το AI παράγει κώδικα + unit tests (το AI πρέπει να δημιουργεί εκτελέσιμες δοκιμές βάσει των δοκιμαστικών περιπτώσεων στο spec).
Εκτέλεση δοκιμών: Αν όλες περάσουν, προχωρήστε στο επόμενο βήμα· αν όχι, τροποποιήστε το spec ή διορθώστε απευθείας τον κώδικα (εδώ μπορεί να γίνει μικρός κύκλος, αλλά πρέπει να καταγράφονται οι αλλαγές).
Ανθρώπινος έλεγχος: Ελέγξτε αν έχει εισαχθεί λειτουργία εκτός spec (scope creep), ελέγξτε ασφάλεια/απόδοση.
Σταθεροποίηση: Υποβολή του εγγράφου spec και του τελικού κώδικα μαζί στο αποθετήριο ως μόνιμη τεκμηρίωση.

Βασική πρακτική: Κωδικοποίηση του Spec – χρήση spec.md + test_spec.py, όπου το αρχείο δοκιμών προέρχεται απευθείας από τα παραδείγματα του spec, ώστε μελλοντικές αλλαγές στον κώδικα να επαληθεύονται απλά τρέχοντας τις δοκιμές.

4. Αποτελέσματα ενός καλού Spec (μπορούν να χρησιμοποιηθούν ως κριτήρια αποδοχής)

Βεβαιότητα: Το ίδιο spec σε διαφορετικά AI (ή άτομα) οδηγεί σε παρόμοιες υλοποιήσεις.
Ελεγξιμότητα: Μετά τη σύνταξη κώδικα, μπορεί αμέσως να επαληθευτεί αυτόματα το 90% της ορθότητας.
Συντηρησιμότητα: Μετά από έξι μήνες, οποιοσδήποτε διαβάζει το spec μπορεί να κατανοήσει την αρχική σχεδιαστική πρόθεση.
Χαμηλό κόστος επικοινωνίας: Κατά τη συζήτηση της ομάδας, συζητείται μόνο το spec, όχι συγκεκριμένες γραμμές κώδικα.
Ενσωματωμένη ασφάλεια/ποιότητα: Οι απαιτήσεις ασφάλειας (π.χ. παραμετροποιημένα ερωτήματα) και οι οριακές συνθήκες αναγράφονται στο spec, το AI πρέπει να τις ακολουθεί.

5. Παράδειγμα ενός καλού Spec (πολύ απλοποιημένο)

# Spec: API εγγραφής χρήστη

## Πεδίο
- Λήψη email, password
- Δεν αποστέλλεται email επαλήθευσης, δεν ελέγχεται η γνησιότητα email

## Συμβόλαιο
POST /register
Content-Type: application/json
Αίτηση: { "email": string, "password": string }
Απόκριση 201: { "user_id": string }
Απόκριση 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Απόκριση 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Συμπεριφορά
- Το email πρέπει να ακολουθεί βασική μορφή RFC 5322 (a@b.c)
- password: μήκος 8-20, τουλάχιστον ένα ψηφίο και ένα κεφαλαίο γράμμα
- Χρήση bcrypt για κρυπτογραφημένη αποθήκευση, κόστος αλατιού 10
- Αν πριν την αποθήκευση στη βάση διαπιστωθεί ότι το email υπάρχει ήδη → 409

## Δοκιμαστικές περιπτώσεις (είσοδος -> αναμενόμενος κωδικός κατάστασης + πεδία απόκρισης)
| Είσοδος email | password | Αναμενόμενο |
|---------------|----------|-------------|
| test@x.com | Pass1234  | 201, user_id υπάρχει |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (ήδη υπάρχον email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Μη λειτουργικά
- Όλα τα SQL πρέπει να χρησιμοποιούν παραμετροποιημένα ερωτήματα (αντι-εισβολή)
- Καταγραφή IP προέλευσης εγγραφής, χωρίς καταγραφή κωδικού
- Χρόνος απόκρισης 95% αιτήσεων < 100ms (χωρίς bcrypt)

## Εξαρτήσεις
- Python 3.10+, FastAPI, bcrypt, asyncpg

Καλή Κωδικοποίηση Spec = μετατροπή των "σχεδιαστικών αποφάσεων" του ανθρώπου σε "δοκιμαστικές περιπτώσεις + υπογραφές τύπων + περιορισμούς συμπεριφοράς" του μηχανήματος, αφήνοντας το AI να γεμίσει μόνο την υλοποίηση, ενώ ο άνθρωπος διατηρεί τον έλεγχο της ποιότητας και της κατεύθυνσης.