Ground Truths: Αγκυρώνοντας τους Πράκτορες AI στην Πραγματικότητα

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Ιανουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Οι πράκτορες AI είναι εντυπωσιακά ικανοί. Μπορούν να συλλογίζονται, να συνθέτουν και να παράγουν. Όμως έχουν μια θεμελιώδη αδυναμία: επινοούν πράγματα. Όχι κακόβουλα, αλλά με αυτοπεποίθηση. Ένας πράκτορας μπορεί να εφεύρει παραμέτρους API που δεν υπάρχουν, να αναφερθεί σε διαμορφώσεις που ποτέ δεν ορίστηκαν, ή να εφαρμόσει μοτίβα από τα δεδομένα εκπαίδευσής του που έρχονται σε αντίθεση με την πραγματική σας αρχιτεκτονική.

Ο τυπικός τρόπος αντιμετώπισης είναι «δώσε στον πράκτορα περισσότερο πλαίσιο». Όμως το πλαίσιο μπορεί να είναι αντιφατικό. Η τεκμηρίωση αποκλίνει από την υλοποίηση. Τα σχόλια λένε ψέματα. Ακόμη και ο κώδικας μπορεί να παραπλανήσει όταν διαβάζεται χωρίς κατανόηση της πρόθεσης.

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

Τα ονομάζουμε Ground Truths.

Τι Είναι ένα Ground Truth;

Ένα ground truth είναι μια ρητή, εκδοχοποιημένη δήλωση γεγονότος που οι πράκτορες πρέπει να σέβονται. Δεν είναι τεκμηρίωση. Δεν είναι σχόλιο. Είναι μια οντότητα πρώτης τάξης στο σύστημα με:

• Ένα μοναδικό αναγνωριστικό (όπως το GT-MAG-015 ή το GT-MAG-036)
• Μια κατάσταση κύκλου ζωής (τρέχουσα, υπό εξέταση, ή απαρχαιωμένη)
• Μια εμβέλεια (πλατφόρμα-ολόκληρη, ειδική για πακέτο, ή δεσμευμένη σε τομέα)
• Αποδεικτικά στοιχεία (διαδρομές αρχείων, URLs, ή αναφορές που αποδεικνύουν τη δήλωση)
• Καθοδήγηση πράκτορα (ρητές οδηγίες τι να κάνει/τι να αποφύγει)

Ορίστε ένα παράδειγμα από την πλατφόρμα ευφυΐας κώδικα Maguyva μας:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Αυτό δεν είναι πεζός λόγος. Είναι συμβόλαιο. Όταν ένας πράκτορας συναντά αυτό το ground truth, ξέρει:

1. Η προεπιλογή είναι ντετερμινιστική (κενά αποτελέσματα, όχι ασαφείς εικασίες)
2. Υπάρχουν συγκεκριμένες παράμετροι (find_similar, exact_match) με ορισμένες συμπεριφορές
3. Υπάρχουν αποδεικτικά στοιχεία σε συγκεκριμένα αρχεία που μπορούν να επαληθευτούν
4. Η δήλωση επαληθεύτηκε σε συγκεκριμένη ημερομηνία

Η Ανατομία ενός Μητρώου Ground Truth

Τα ground truths ζουν σε μητρώα YAML κάτω από το ai_assets/reference/ground_truths.yaml. Κάθε πακέτο ή τομέας μπορεί να έχει το δικό του μητρώο. Η δομή είναι:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

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

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Πώς οι Πράκτορες Έχουν Πρόσβαση στα Ground Truths

Τα ground truths εκτίθενται μέσα από πολλαπλά κανάλια:

1. Αποδοσμένη Τεκμηρίωση

Η εντολή orkestra sync μετατρέπει μητρώα YAML σε αναγνώσιμο markdown:

uv run orkestra sync

Αυτό δημιουργεί αρχεία GROUND_TRUTHS.md που περιλαμβάνονται στο πλαίσιο του πράκτορα. Η αποδοσμένη έξοδος ομαδοποιεί τις δηλώσεις κατά κατάσταση και κατηγορία:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Αναζήτηση CLI

Πράκτορες με πρόσβαση shell μπορούν να αναζητήσουν ground truths προγραμματιστικά:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

Η συνάρτηση αναζήτησης βαθμολογεί αντιστοιχίσεις σε πολλαπλά πεδία με σταθμισμένη σχετικότητα:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Σύνθεση Πλαισίου

Όταν οι πράκτορες αποδίδονται από ορισμούς YAML, το πλαίσιό τους μπορεί να αναφέρεται σε μητρώα ground truth:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Αυτό εξασφαλίζει ότι τα σχετικά ground truths φορτώνονται πριν ο πράκτορας ξεκινήσει την εργασία.

Κατηγορίες Ground Truths

Κοιτάζοντας σε όλα τα μητρώα μας, τα ground truths συγκεντρώνονται σε αρκετά μοτίβα:

Αρχές Προϊόντος

Περιορισμοί για το τι είναι και τι δεν είναι το προϊόν:

«Το Maguyva είναι μόνο-για-ανάγνωση ως προς τα αποθετήρια χρηστών· το μόνο μη-ανακατασκευάσιμο στοιχείο είναι η πληρωμένη κρυφή μνήμη ενσωματωμάτων.» (GT-MAG-001)

Όρια Αρχιτεκτονικής

Πού ζουν οι ευθύνες και γιατί:

«Τα όρια ανάμεσα στο pipeline και το Maguyva είναι σκόπιμα: το pipeline είναι επαναχρησιμοποιήσιμο, το Maguyva κρατά τη λογική ειδική για κώδικα, και το CQRS διαχωρίζει τις εγγραφές σταδίου από τις αναγνώσεις διακομιστή.» (GT-MAG-006)

Κανόνες Κατά της Παραίσθησης

Ρητές εντολές που κρατούν τα συμβόλαια εργαλείων ντετερμινιστικά αντί για συναγόμενα:

«Η ασαφής αντιστοίχιση συμβόλων είναι προαιρετική μέσω του find_similar=true. Η προεπιλεγμένη συμπεριφορά επιστρέφει κενά αποτελέσματα για ανύπαρκτα σύμβολα· το exact_match=true επιβάλλει αυστηρή αντιστοίχιση και απενεργοποιεί όλες τις ασαφείς εναλλακτικές.» (GT-MAG-015)

Πύλες Ποιότητας

Πρότυπα που πρέπει να διατηρούνται:

«Αλλαγές στην κοινόχρηστη υποδομή (post_filters.py, εξαγωγείς σχέσεων, κοινόχρηστοι χειριστές) ΠΡΕΠΕΙ να επικυρώνονται έναντι ΟΛΩΝ των υποστηριζόμενων γλωσσών μέσω πλήρους δημιουργίας μανιφέστου πριν από το commit. Μια επικύρωση μίας μόνο γλώσσας δεν επαρκεί για κοινόχρηστο κώδικα.» (GT-MAG-036)

Μοτίβα Κώδικα

Απαιτήσεις υλοποίησης:

«Χρησιμοποιήστε το asyncio.to_thread() για εργασία με έντονη χρήση CPU σε ασύγχρονα πλαίσια· το απαρχαιωμένο μοτίβο loop.run_in_executor() δεν πρέπει να χρησιμοποιείται σε νέο κώδικα.» (GT-MAG-018)

Ο Κύκλος Ζωής ενός Ground Truth

Τα ground truths δεν είναι στατικά. Εξελίσσονται μέσα από έναν ορισμένο κύκλο ζωής:

Υπό Εξέταση

Μια προτεινόμενη αλήθεια υπό αξιολόγηση. Η δήλωση καταγράφεται αλλά μπορεί να αλλάξει:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Τρέχουσα

Μια επαληθευμένη αλήθεια που οι πράκτορες πρέπει να σέβονται. Τα αποδεικτικά στοιχεία έχουν επικυρωθεί:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Απαρχαιωμένη

Μια αλήθεια που δεν ισχύει πλέον. Διατηρείται για ιστορική αναφορά με έναν δείκτη προς αυτό που την αντικατέστησε:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Γιατί Όχι Απλώς Τεκμηρίωση;

Η τεκμηρίωση εξυπηρετεί διαφορετικό σκοπό. Εξηγεί. Διδάσκει. Μπορεί να είναι ασαφής, μπορεί να χρησιμοποιεί προσδιοριστικά όπως «γενικά» ή «συνήθως».

Τα ground truths δεν μπορούν να είναι ασαφή. Είναι διαβεβαιώσεις. Είτε ισχύουν είτε όχι.

Σκεφτείτε τη διαφορά:

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

Ground Truth: «Η προεπιλεγμένη συμπεριφορά επιστρέφει κενά αποτελέσματα για ανύπαρκτα σύμβολα· το exact_match=true επιβάλλει αυστηρή αντιστοίχιση και απενεργοποιεί όλες τις ασαφείς εναλλακτικές.»

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

Καθοδήγηση Πράκτορα: Κάνε και Απόφυγε

Μερικά ground truths περιλαμβάνουν ρητή καθοδήγηση πράκτορα:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

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

Επαλήθευση και Συντήρηση

Τα ground truths χρειάζονται συντήρηση. Παρακολουθούμε:

• last_verified: Πότε κάποιος επιβεβαίωσε ότι η δήλωση εξακολουθεί να ισχύει
• evidence: Αρχεία που αποδεικνύουν τη δήλωση (μπορούν να ελεγχθούν για ύπαρξη)
• source: Από πού προήλθε η αλήθεια (επιθεώρηση CLI, επισκόπηση αρχιτεκτονικής, μάθηση μετά από περιστατικό)

Ένα ground truth με παλιές ημερομηνίες επαλήθευσης ή σπασμένους συνδέσμους αποδεικτικών στοιχείων είναι ένα σήμα για διερεύνηση. Είτε η αλήθεια εξακολουθεί να ισχύει και χρειάζεται επανεπαλήθευση, είτε η πραγματικότητα άλλαξε και η αλήθεια χρειάζεται ενημέρωση.

Πραγματικά Παραδείγματα από την Παραγωγή

Όριο Ασφάλειας

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Αυτό το ground truth αποτρέπει μια κατηγορία παραπλανημένων «βελτιώσεων ασφάλειας» που θα έσπαγαν το προϊόν.

Ακρίβεια Κατά τη Στιγμή της Εξαγωγής

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

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

Πολυεπίπεδο Φιλτράρισμα

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Αυτό εμποδίζει τους πράκτορες από το να προσθέτουν φίλτρα στο λάθος σημείο, ένα συνηθισμένο λάθος που προκάλεσε οπισθοδρομήσεις ακρίβειας.

Ενσωμάτωση με το Σύστημα Ενορχήστρωσης

Τα ground truths είναι ένα επίπεδο ενός ευρύτερου συστήματος πλαισίου:

1. Αρχιτεκτονικές Αποφάσεις (ADRs) - Καταγράφουν γιατί επιλέξαμε την προσέγγιση Α αντί της Β
2. Ground Truths - Δηλώνουν τι είναι οριστικά αληθές αυτή τη στιγμή
3. Μοτίβα Τομέα - Περιγράφουν πώς να κάνεις τα πράγματα σωστά
4. Αντι-Μοτίβα - Περιγράφουν τι να αποφύγεις και γιατί

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

Μέτρηση Επίδρασης

Από τότε που εισαγάγαμε τα ground truths, έχουμε παρατηρήσει:

• Λιγότερους κύκλους «διόρθωσε τη λανθασμένη διόρθωση»
• Πιο σίγουρη λήψη αποφάσεων από πράκτορες όταν τα γεγονότα είναι σαφή
• Καλύτερες επισκοπήσεις PR επειδή οι προσδοκίες είναι ρητές
• Μειωμένο χρόνο ένταξης για νέους πράκτορες (και ανθρώπους)

Η επένδυση στη συντήρηση των ground truths αποδίδει σε μειωμένη αποσφαλμάτωση και σαφέστερα όρια συστήματος.

Ξεκινώντας

Για να προσθέσετε ένα ground truth στο σύστημά σας:

1. Δημιουργήστε ένα ground_truths.yaml στον κατάλογο ai_assets/reference/ του πακέτου σας
2. Ορίστε μεταδεδομένα και διαμόρφωση απόδοσης
3. Προσθέστε δηλώσεις ακολουθώντας το σχήμα
4. Τρέξτε το uv run orkestra sync για να δημιουργήσετε τεκμηρίωση
5. Συμπεριλάβετε το μητρώο στη σύνθεση πλαισίου του πράκτορα

Ξεκινήστε με τα γεγονότα που προκαλούν τη μεγαλύτερη σύγχυση ή τους περιορισμούς που παραβιάζονται πιο συχνά. Αυτά είναι τα ground truths υψηλότερης αξίας σας.

Συμπέρασμα

Οι πράκτορες AI θα παραληρούν. Αυτή είναι η φύση τους. Όμως μπορούμε να δημιουργήσουμε περιβάλλοντα όπου η παραίσθηση περιορίζεται, όπου ορισμένα γεγονότα δεν είναι διαπραγματεύσιμα, όπου οι πράκτορες μπορούν να ελέγχουν τις υποθέσεις τους έναντι επαληθευμένης πραγματικότητας.

Τα ground truths δεν είναι μια πλήρης λύση. Χρειάζονται συντήρηση. Μπορούν να παλιώσουν. Προσθέτουν επιβάρυνση στη διαδικασία ανάπτυξης.

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

Η εναλλακτική είναι ατέλειωτοι κύκλοι πρακτόρων που κάνουν σίγουρα λάθη και ανθρώπων που τα διορθώνουν. Τα ground truths σπάνε αυτόν τον κύκλο κάνοντας τις διορθώσεις ρητές και διαρκείς.

Οι πράκτορές σας αξίζουν να ξέρουν τι είναι αληθές. Πείτε τους το.