Vérités de terrain : ancrer les agents IA dans la réalité

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Les agents IA sont remarquablement capables. Ils savent raisonner, synthétiser et générer. Mais ils ont une faiblesse fondamentale : ils inventent des choses. Pas par malveillance, mais avec assurance. Un agent peut inventer des paramètres d’API qui n’existent pas, référencer des configurations qui n’ont jamais été définies, ou appliquer des schémas issus de ses données d’entraînement qui contredisent votre architecture réelle.

La parade habituelle est de « donner plus de contexte à l’agent ». Mais le contexte peut être contradictoire. La documentation dérive par rapport à l’implémentation. Les commentaires mentent. Même le code peut induire en erreur quand on le lit sans comprendre l’intention.

Il nous fallait quelque chose de plus explicite. Quelque chose qui ne puisse être ni ignoré ni mal interprété. Quelque chose qui ancre les agents dans une réalité vérifiable.

Nous les appelons les Vérités de terrain.

Qu’est-ce qu’une vérité de terrain ?

Une vérité de terrain est un énoncé de fait explicite et versionné que les agents doivent respecter. Ce n’est pas de la documentation. Ce n’est pas un commentaire. C’est une entité de premier ordre dans le système, dotée de :

• Un identifiant unique (comme GT-MAG-015 ou GT-MAG-036)
• Un statut de cycle de vie (actuelle, provisoire ou obsolète)
• Une portée (à l’échelle de la plateforme, spécifique à un package, ou liée à un domaine)
• Des preuves (chemins de fichiers, URL ou références qui étayent l’énoncé)
• Des consignes pour l’agent (instructions explicites à faire ou à éviter)

Voici un exemple tiré de notre plateforme d’intelligence du code 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

Ce n’est pas de la prose. C’est un contrat. Quand un agent rencontre cette vérité de terrain, il sait :

1. Le comportement par défaut est déterministe (résultats vides, pas de suppositions floues)
2. Il existe des paramètres spécifiques (find_similar, exact_match) au comportement défini
3. Des preuves existent dans des fichiers précis, vérifiables
4. L’énoncé a été vérifié à une date précise

L’anatomie d’un registre de vérités de terrain

Les vérités de terrain vivent dans des registres YAML sous ai_assets/reference/ground_truths.yaml. Chaque package ou domaine peut avoir son propre registre. La structure est la suivante :

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

Le registre inclut des métadonnées sur la collection elle-même, une configuration de rendu pour la génération de documentation, et les énoncés eux-mêmes. Chaque énoncé suit un schéma strict validé par des modèles 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

Comment les agents accèdent aux vérités de terrain

Les vérités de terrain sont exposées via plusieurs canaux :

1. Documentation rendue

La commande orkestra sync transforme les registres YAML en markdown lisible :

uv run orkestra sync

Cela génère des fichiers GROUND_TRUTHS.md qui sont inclus dans le contexte de l’agent. Le rendu regroupe les énoncés par statut et par catégorie :

## 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. Recherche en ligne de commande

Les agents disposant d’un accès shell peuvent rechercher des vérités de terrain de manière programmatique :

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 fonction de recherche note les correspondances sur plusieurs champs avec une pertinence pondérée :

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. Composition du contexte

Quand les agents sont générés à partir de définitions YAML, leur contexte peut référencer des registres de vérités de terrain :

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

Cela garantit que les vérités de terrain pertinentes sont chargées avant que l’agent ne commence à travailler.

Catégories de vérités de terrain

En parcourant nos registres, les vérités de terrain se regroupent en plusieurs schémas :

Principes produit

Des contraintes sur ce que le produit est et n’est pas :

« Maguyva est en lecture seule vis-à-vis des dépôts des utilisateurs ; le seul actif non reconstructible est le cache d’embeddings payant. » (GT-MAG-001)

Frontières architecturales

Où vivent les responsabilités, et pourquoi :

« Les frontières entre pipeline et Maguyva sont intentionnelles : pipeline est réutilisable, Maguyva porte la logique propre au code, et le CQRS sépare les écritures des étapes des lectures du serveur. » (GT-MAG-006)

Règles anti-hallucination

Des mandats explicites qui gardent les contrats d’outils déterministes plutôt qu’inférés :

« La correspondance floue de symboles est optionnelle via find_similar=true. Le comportement par défaut renvoie des résultats vides pour les symboles inexistants ; exact_match=true impose une correspondance stricte et désactive tous les repli flous. » (GT-MAG-015)

Portes de qualité

Des standards à maintenir :

« Les modifications de l’infrastructure partagée (post_filters.py, extracteurs de relations, handlers partagés) DOIVENT être validées face à TOUS les langages pris en charge, via une génération complète du manifeste, avant tout commit. Une validation sur un seul langage est insuffisante pour du code partagé. » (GT-MAG-036)

Schémas de code

Des exigences d’implémentation :

« Utilisez asyncio.to_thread() pour le travail lié au CPU dans des contextes asynchrones ; le schéma déprécié loop.run_in_executor() ne doit pas être utilisé dans du nouveau code. » (GT-MAG-018)

Le cycle de vie d’une vérité de terrain

Les vérités de terrain ne sont pas statiques. Elles évoluent selon un cycle de vie défini :

Provisoire

Une vérité proposée, en cours d’évaluation. L’énoncé est enregistré mais peut changer :

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

Actuelle

Une vérité vérifiée que les agents doivent respecter. Les preuves ont été validées :

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

Obsolète

Une vérité qui ne s’applique plus. Conservée à titre de référence historique, avec un pointeur vers ce qui l’a remplacée :

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

Pourquoi pas simplement de la documentation ?

La documentation sert un autre objectif. Elle explique. Elle enseigne. Elle peut être vague, utiliser des qualificatifs comme « généralement » ou « typiquement ».

Les vérités de terrain ne peuvent pas être vagues. Ce sont des assertions. Elles s’appliquent, ou elles ne s’appliquent pas.

Considérez la différence :

Documentation : « L’API renvoie généralement des résultats vides quand un symbole n’est pas trouvé, bien que la correspondance floue puisse être activée dans certaines configurations. »

Vérité de terrain : « Le comportement par défaut renvoie des résultats vides pour les symboles inexistants ; exact_match=true impose une correspondance stricte et désactive tous les replis flous. »

La première est utile pour les humains qui apprennent le système. La seconde est exploitable pour les agents qui prennent des décisions.

Consignes pour l’agent : à faire et à éviter

Certaines vérités de terrain incluent des consignes explicites pour l’agent :

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

Cela lève toute ambiguïté. Un agent qui lit cela sait non seulement ce qui est vrai, mais aussi quelles actions cette vérité implique.

Vérification et maintenance

Les vérités de terrain demandent de la maintenance. Nous suivons :

• last_verified : la date à laquelle quelqu’un a confirmé que l’énoncé tient toujours
• evidence : les fichiers qui étayent l’énoncé (leur existence peut être vérifiée)
• source : d’où vient la vérité (inspection en CLI, revue d’architecture, apprentissage post-incident)

Une vérité de terrain dont les dates de vérification sont anciennes ou dont les liens de preuve sont rompus est un signal à investiguer. Soit la vérité est toujours valide et a besoin d’être revérifiée, soit la réalité a changé et la vérité doit être mise à jour.

Exemples réels tirés de la production

Frontière de sécurité

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

Cette vérité de terrain empêche une catégorie de fausses « améliorations de sécurité » qui casseraient le produit.

Précision au moment de l’extraction

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

Cela vient d’une expérience douloureuse. Des agents corrigeaient des packs de langage défaillants en ajoutant des filtres réservés au validateur, qui faisaient paraître le harnais de test plus vert, alors que l’extracteur Maguyva en production continuait d’émettre les mauvaises arêtes. La règle force les corrections à revenir dans le vrai chemin : configuration YAML, requêtes, ou handlers.

Filtrage multi-niveaux

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

Cela empêche les agents d’ajouter des filtres au mauvais endroit, une erreur courante qui a provoqué des régressions de précision.

Intégration avec le système d’orchestration

Les vérités de terrain sont une couche parmi d’autres d’un système de contexte plus large :

1. Décisions architecturales (ADR) — enregistrent pourquoi nous avons choisi l’approche A plutôt que B
2. Vérités de terrain — énoncent ce qui est définitivement vrai en ce moment
3. Schémas de domaine — décrivent comment bien faire les choses
4. Anti-schémas — décrivent ce qu’il faut éviter, et pourquoi

Un agent qui travaille dans le système a accès aux quatre. Les vérités de terrain fournissent l’ancrage factuel, tandis que les décisions expliquent l’historique, les schémas guident l’implémentation, et les anti-schémas préviennent des pièges.

Mesurer l’impact

Depuis l’introduction des vérités de terrain, nous avons observé :

• Moins de cycles « corriger la correction hallucinée »
• Une prise de décision plus assurée des agents quand les faits sont clairs
• De meilleures revues de PR, parce que les attentes sont explicites
• Un temps d’intégration réduit pour les nouveaux agents (et les nouveaux humains)

L’investissement dans la maintenance des vérités de terrain se traduit par moins de débogage et des frontières système plus claires.

Pour commencer

Pour ajouter une vérité de terrain à votre système :

1. Créez un ground_truths.yaml dans le répertoire ai_assets/reference/ de votre package
2. Définissez les métadonnées et la configuration de rendu
3. Ajoutez les énoncés en suivant le schéma
4. Exécutez uv run orkestra sync pour générer la documentation
5. Incluez le registre dans la composition du contexte de l’agent

Commencez par les faits qui provoquent le plus de confusion, ou les contraintes les plus souvent violées. Ce sont vos vérités de terrain les plus précieuses.

Conclusion

Les agents IA vont halluciner. C’est leur nature. Mais nous pouvons créer des environnements où l’hallucination est contrainte, où certains faits ne sont pas négociables, où les agents peuvent confronter leurs suppositions à une réalité vérifiée.

Les vérités de terrain ne sont pas une solution complète. Elles demandent de la maintenance. Elles peuvent devenir obsolètes. Elles ajoutent une charge au processus de développement.

Mais elles apportent quelque chose de précieux : un vocabulaire partagé de faits auquel humains et agents peuvent tous deux faire confiance. Dans un monde où les agents participent de plus en plus au développement logiciel, ce socle commun devient essentiel.

L’alternative, ce sont des cycles sans fin d’agents commettant des erreurs avec assurance et d’humains les corrigeant. Les vérités de terrain brisent ce cycle en rendant les corrections explicites et durables.

Vos agents méritent de savoir ce qui est vrai. Dites-le-leur.