Verità di base: ancorare gli agenti AI alla realtà

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Gli agenti AI sono straordinariamente capaci. Sanno ragionare, sintetizzare e generare. Ma hanno una debolezza fondamentale: si inventano le cose. Non in malafede, ma con sicurezza. Un agente può inventare parametri API che non esistono, fare riferimento a configurazioni mai definite, o applicare pattern dai suoi dati di addestramento che contraddicono la tua architettura reale.

La mitigazione standard è “dare all’agente più contesto”. Ma il contesto può essere contraddittorio. La documentazione si scosta dall’implementazione. I commenti mentono. Persino il codice può fuorviare se letto senza capire l’intento.

Ci serviva qualcosa di più esplicito. Qualcosa che non potesse essere ignorato o frainteso. Qualcosa che ancorasse gli agenti a una realtà verificabile.

Le chiamiamo Verità di Base.

Cos’è una Verità di Base?

Una verità di base è un’affermazione di fatto esplicita e versionata che gli agenti devono rispettare. Non è documentazione. Non è un commento. È un’entità di primo livello nel sistema, con:

• Un identificatore univoco (come GT-MAG-015 o GT-MAG-036)
• Uno stato di ciclo di vita (corrente, provvisoria, o deprecata)
• Un ambito (piattaforma intera, specifico per package, o vincolato a un dominio)
• Prove (percorsi di file, URL, o riferimenti che dimostrano l’affermazione)
• Indicazioni per l’agente (istruzioni esplicite su cosa fare/evitare)

Ecco un esempio dalla nostra piattaforma di Code Intelligence 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

Questo non è prosa. È un contratto. Quando un agente incontra questa verità di base, sa:

1. Il default è deterministico (risultati vuoti, non ipotesi approssimative)
2. Ci sono parametri specifici (find_similar, exact_match) con comportamenti definiti
3. Esistono prove in file specifici che possono essere verificati
4. L’affermazione è stata verificata a una data specifica

L’anatomia di un registro di Verità di Base

Le verità di base vivono in registri YAML sotto ai_assets/reference/ground_truths.yaml. Ogni package o dominio può avere il proprio registro. La struttura è:

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..."
    ...

Il registro include metadati sulla collezione stessa, configurazione di rendering per la generazione della documentazione, e le affermazioni stesse. Ogni affermazione segue uno schema rigoroso validato da modelli 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

Come gli agenti accedono alle Verità di Base

Le verità di base sono esposte attraverso più canali:

1. Documentazione renderizzata

Il comando orkestra sync trasforma i registri YAML in markdown leggibile:

uv run orkestra sync

Questo genera file GROUND_TRUTHS.md inclusi nel contesto dell’agente. L’output renderizzato raggruppa le affermazioni per stato e categoria:

## 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. Ricerca da CLI

Gli agenti con accesso shell possono cercare le verità di base programmaticamente:

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

La funzione di ricerca assegna un punteggio ai risultati su più campi con rilevanza pesata:

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. Composizione del contesto

Quando gli agenti vengono renderizzati da definizioni YAML, il loro contesto può fare riferimento ai registri di verità di base:

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

Questo garantisce che le verità di base rilevanti vengano caricate prima che l’agente inizi il lavoro.

Categorie di Verità di Base

Osservando i nostri registri, le verità di base si raggruppano in diversi pattern:

Principi di prodotto

Vincoli su cosa il prodotto è e non è:

“Maguyva è di sola lettura rispetto ai repository degli utenti; l’unico asset non ricostruibile è la cache di embedding a pagamento.” (GT-MAG-001)

Confini architetturali

Dove vivono le responsabilità e perché:

“I confini tra pipeline e Maguyva sono intenzionali: la pipeline è riutilizzabile, Maguyva contiene la logica specifica del codice, e CQRS separa le scritture dello stage dalle letture del server.” (GT-MAG-006)

Regole anti-allucinazione

Mandati espliciti che mantengono i contratti degli strumenti deterministici invece che inferiti:

“Il matching fuzzy dei simboli è opt-in tramite find_similar=true. Il comportamento predefinito restituisce risultati vuoti per simboli inesistenti; exact_match=true impone un matching rigoroso e disabilita tutti i fallback fuzzy.” (GT-MAG-015)

Gate di qualità

Standard che devono essere mantenuti:

“Le modifiche all’infrastruttura condivisa (post_filters.py, estrattori di relazioni, handler condivisi) DEVONO essere validate contro TUTTI i linguaggi supportati tramite generazione del manifest completo prima del commit. Una validazione a linguaggio singolo non è sufficiente per il codice condiviso.” (GT-MAG-036)

Pattern di codice

Requisiti di implementazione:

“Usa asyncio.to_thread() per lavoro CPU-bound in contesti async; il pattern deprecato loop.run_in_executor() non deve essere usato in nuovo codice.” (GT-MAG-018)

Il ciclo di vita di una Verità di Base

Le verità di base non sono statiche. Evolvono attraverso un ciclo di vita definito:

Provvisoria

Una verità proposta in fase di valutazione. L’affermazione è registrata ma può cambiare:

- 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.

Corrente

Una verità verificata che gli agenti devono rispettare. Le prove sono state convalidate:

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

Deprecata

Una verità che non si applica più. Conservata come riferimento storico con un puntatore a ciò che l’ha sostituita:

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

Perché non semplice documentazione?

La documentazione serve a uno scopo diverso. Spiega. Insegna. Può essere vaga, può usare qualificatori come “generalmente” o “tipicamente”.

Le verità di base non possono essere vaghe. Sono asserzioni. O si applicano o non si applicano.

Considera la differenza:

Documentazione: “L’API generalmente restituisce risultati vuoti quando un simbolo non viene trovato, sebbene il matching fuzzy possa essere abilitato in alcune configurazioni.”

Verità di base: “Il comportamento predefinito restituisce risultati vuoti per simboli inesistenti; exact_match=true impone un matching rigoroso e disabilita tutti i fallback fuzzy.”

La prima è utile per gli esseri umani che imparano il sistema. La seconda è azionabile per gli agenti che prendono decisioni.

Indicazioni per l’agente: fare ed evitare

Alcune verità di base includono indicazioni esplicite per l’agente:

- 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"

Questo elimina l’ambiguità. Un agente che legge questo sa non solo cosa è vero, ma quali azioni quella verità implica.

Verifica e manutenzione

Le verità di base richiedono manutenzione. Tracciamo:

• last_verified: quando qualcuno ha confermato che l’affermazione è ancora valida
• evidence: file che dimostrano l’affermazione (può essere verificata la loro esistenza)
• source: da dove ha origine la verità (ispezione da CLI, revisione architetturale, apprendimento post-incidente)

Una verità di base con date di verifica obsolete o link di prova rotti è un segnale da indagare. O la verità è ancora valida e necessita una riverifica, oppure la realtà è cambiata e la verità va aggiornata.

Esempi reali dalla produzione

Confine di sicurezza

- 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.

Questa verità di base previene una classe di “miglioramenti di sicurezza” mal indirizzati che romperebbero il prodotto.

Accuratezza al momento dell’estrazione

- 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.

Questa è nata da un’esperienza dolorosa. Gli agenti riparavano i language pack falliti aggiungendo filtri solo-validatore che facevano sembrare più verde il test harness, mentre l’estrattore Maguyva live continuava a emettere gli edge sbagliati. La regola costringe le correzioni a tornare sul percorso reale: config YAML, query, o handler.

Filtraggio multi-livello

- 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).

Questo impedisce agli agenti di aggiungere filtri nel posto sbagliato, un errore comune che causava regressioni di accuratezza.

Integrazione con il sistema di orchestrazione

Le verità di base sono un livello di un sistema di contesto più ampio:

1. Decisioni architetturali (ADR) - Registrano perché abbiamo scelto l’approccio A invece di B
2. Verità di base - Affermano cosa è definitivamente vero in questo momento
3. Pattern di dominio - Descrivono come fare le cose correttamente
4. Anti-pattern - Descrivono cosa evitare e perché

Un agente che lavora nel sistema ha accesso a tutti e quattro. Le verità di base forniscono l’ancora fattuale, mentre le decisioni spiegano la storia, i pattern guidano l’implementazione, e gli anti-pattern avvertono delle insidie.

Misurare l’impatto

Da quando abbiamo introdotto le verità di base, abbiamo osservato:

• Meno cicli di “correggere la correzione allucinata”
• Un processo decisionale degli agenti più sicuro quando i fatti sono chiari
• Revisioni delle PR migliori perché le aspettative sono esplicite
• Tempi di onboarding ridotti per i nuovi agenti (e per gli esseri umani)

L’investimento nel mantenere le verità di base ripaga in meno debugging e confini di sistema più chiari.

Come iniziare

Per aggiungere una verità di base al tuo sistema:

1. Crea un ground_truths.yaml nella directory ai_assets/reference/ del tuo package
2. Definisci metadati e configurazione di rendering
3. Aggiungi affermazioni seguendo lo schema
4. Esegui uv run orkestra sync per generare la documentazione
5. Includi il registro nella composizione del contesto dell’agente

Inizia dai fatti che causano più confusione o dai vincoli che vengono violati più spesso. Quelle sono le tue verità di base a più alto valore.

Conclusione

Gli agenti AI avranno allucinazioni. È nella loro natura. Ma possiamo creare ambienti in cui l’allucinazione è vincolata, in cui certi fatti non sono negoziabili, in cui gli agenti possono verificare le proprie assunzioni contro una realtà verificata.

Le verità di base non sono una soluzione completa. Richiedono manutenzione. Possono diventare obsolete. Aggiungono overhead al processo di sviluppo.

Ma offrono qualcosa di prezioso: un vocabolario condiviso di fatti di cui sia gli esseri umani che gli agenti possono fidarsi. In un mondo in cui gli agenti partecipano sempre di più allo sviluppo software, quella base condivisa diventa essenziale.

L’alternativa sono cicli infiniti di agenti che commettono errori con sicurezza e di esseri umani che li correggono. Le verità di base rompono quel ciclo rendendo le correzioni esplicite e durature.

I tuoi agenti meritano di sapere cosa è vero. Diglielo.