Écrire un talent

Construire un talent prescriptif, du talent minimal viable au talent structurel.

Un talent n'est pas de la documentation : c'est une expertise codifiée qui recentre l'agent sur les conventions d'un projet. La référence complète du schéma est dans Manifest et catalog/TALENT-STRUCTURE.md ; ce guide donne la trajectoire pratique.

Règle d'or

Si le LLM le sait déjà, ne l'écris pas. Un talent répond à « comment veut-on appliquer cette expertise dans ce projet ? », pas « qu'est-ce que le DDD ». Il est prescriptif, pas encyclopédique.

1. Partir du talent minimal viable

Le plus petit talent valide contient quatre fichiers :

talent-name/
├── manifest.yml          # id, name, version, type, status, summary, tags, agents, activation, requires/recommends
├── compact.md            # le but + les règles critiques
├── talent.md             # intention + quand (ne pas) appliquer
└── tests/prompt-tests.yml # ≥ 1 refus, 1 guidage, 1 non-déclenchement

Tout le reste s'ajoute selon le besoin (altitude). On n'écrit un fichier que s'il réduit une ambiguïté — jamais pour « compléter la structure ».

2. Soigner le `compact.md`

C'est le fichier le plus important : la version ultra-dense (300–800 tokens) toujours injectée, conçue pour survivre à la compaction. Structure type : But → Règles critiques → Ordre de raisonnement → À refuser. Pas de théorie.

3. Choisir le type

Type	Définition	Contenu propre
`atomic`	Brique précise et autonome (Value Object, Use Case, Port).	Resserré : `compact` + règles/workflow/checklist regroupés.
`composite`	Agrège des atomiques via `includes`.	Décrit quand les combiner, comment arbitrer, dans quel ordre — sans répéter les atomiques.

Un workflow.md est obligatoire pour les composites : leur ordre de raisonnement est leur valeur.

4. Typer les règles

Toutes les règles ne se valent pas. Trois niveaux dans rules.md :

rules:
  hard:        # severity: blocking — à respecter absolument
    - id: domain-no-infrastructure-dependency
      severity: blocking
      description: Le domaine ne dépend jamais de l'infrastructure.
  soft:        # severity: warning — signaler si enfreint
    - id: prefer-value-objects
      severity: warning
  stylistic:   # severity: info — appliquer quand pertinent
    - id: names-match-ubiquitous-language
      severity: info

Côté LLM : respecte les hard, signale les soft, applique les stylistic si pertinent.

5. Donner des exemples contrastés

Dans examples/<lang>.md, des paires mauvais / bon / pourquoi, courtes et contrastées — un fichier par langage déclaré dans languages. Le LLM apprend très bien ainsi.

6. Talents structurels (`enforceable: true`)

Pour un talent dont l'essence est structurelle (architecture, layering, règle de dépendance), exprime la structure en diagramme-as-code + contraintes machine-vérifiables. Une source unique pilote les deux usages :

constraints.yml ──┬──► injecté au LLM (spec structurelle dense)        [builder]
  (source unique) └──► conventions/<lang>.yml ──► config linter ──► CI [validator]

structure/model.md — diagramme Mermaid (texte, jamais image) montrant la direction autorisée des dépendances.
structure/constraints.yml — couches, règle de dépendance, imports interdits, mapping validateur (dependency-cruiser, ArchUnit, import-linter).

Voir Builder vs Validator et Validation.

7. Prouver le comportement

Un talent sans prompt-test qui passe n'est qu'un espoir. Écris au minimum un cas de refus, un de guidage, un de non-déclenchement. → Prompt-tests.