Prompt-tests

Les prompt-tests sont le forcing function du projet : ils prouvent qu'un talent change réellement le comportement d'un agent. Un talent sans prompt-test qui passe n'est qu'un espoir, pas une garantie.

Emplacement

Chaque talent porte ses tests dans tests/prompt-tests.yml.

Schéma d'un test

id: grace.<domaine>.<talent>.prompt-tests   # identifiant global
talent: grace.<domaine>.<talent>            # talent sous test
description: >
  ce que la suite vérifie
tests:
  - name: <snake_case_explicite>            # un comportement par test
    input: |                                # le prompt envoyé à l'agent
      ...
    expected:
      severity: blocking | warning | info   # (optionnel) niveau attendu si violation
      must_mention:                         # notions qui DOIVENT apparaître
        - "..."
      must_not_mention:                     # notions qui ne doivent PAS apparaître
        - "..."
      ordered_hint:                         # (optionnel, non bloquant) ordre attendu
        - "..."

Sémantique des champs

Champ	Rôle	Bloquant ?
`must_mention`	l'agent doit aborder ces notions (matching souple, insensible à la casse)	oui
`must_not_mention`	l'agent ne doit pas valider/produire ces anti-patterns	oui
`severity`	niveau de criticité attendu quand l'agent signale une violation	oui si présent
`ordered_hint`	ordre de raisonnement souhaité ; indicateur de qualité	non

Principes de rédaction

Un comportement par test — pas de test fourre-tout.
Couvrir au minimum trois cas :
1. une violation à refuser ;
2. une bonne application à guider ;
3. un non-déclenchement — le talent ne doit pas s'imposer hors de son périmètre (une tâche CSS ne doit pas déclencher l'architecture hexagonale).
Le matching est sémantique et souple, pas une égalité stricte : on vérifie que la notion est traitée, pas une formulation exacte.

Exécution (dans ce dépôt)

Le runner livré avec la plateforme est platform/backend/prompt-test-runner.mjs. Il charge le tests/prompt-tests.yml d'un talent, exécute chaque cas avec le talent (compact.md + rules.md) en contexte système, et vérifie must_mention / must_not_mention.

cd platform/backend
# Dry-run : liste et valide les cas sans appeler le modèle (aucune clé requise).
GRACE_CATALOG=../../catalog node prompt-test-runner.mjs architecture/hexagonal

# Exécution réelle : nécessite une clé API Anthropic.
ANTHROPIC_API_KEY=sk-... GRACE_CATALOG=../../catalog node prompt-test-runner.mjs ddd/value-object

L'argument est le chemin relatif du talent dans catalog/talents/ (défaut : architecture/hexagonal). Modèle d'évaluation par défaut : claude-haiku-4-5 (override GRACE_EVAL_MODEL). Les cas sont aussi affichés sur la fiche talent du dashboard.

Exécution (cible CLI)

À terme, le CLI grace exposera la même suite :

grace test talents                          # toute la suite
grace test talents architecture.hexagonal   # un talent

Une suite devrait être rejouable sur plusieurs modèles (Claude, Codex…) pour mesurer la robustesse d'un talent indépendamment du harness.