Créer un Agent
Objectif
Concevoir des agents IA avec une discipline de « périmètre d'abord ». Avant d'écrire un prompt, une configuration ou une liaison d'outil, vous devez passer par un entretien de cadrage structuré. La profondeur de l'entretien dépend de la complexité de l'agent conçu.
Ce n'est pas un skill de rédaction de prompt. C'est un skill de validation du périmètre. Le livrable est une Spécification d'Agent validée — un plan qu'un autre IA ou humain peut utiliser pour construire l'agent correctement.
Chaque spécification d'agent définit 8 dimensions :
Archétype → Personnalité → Capacités → E/S → Écosystème → Mémoire → Cycle de Vie → Risques/Métriques
Règles de Fer
-
Périmètre avant construction — Pas de code, pas de prompt, pas de configuration d'outil tant que le périmètre n'est pas validé. Aucune exception.
Autorité de correction : s'applique à l'ébauche/les hypothèses de la spécification uniquement — Corrigez les hypothèses dans la spécification que l'utilisateur a oubliées (dépendance manquante, contradiction, risque de sécurité) directement, sans demander d'abord. Dites simplement ce que vous ajustez et pourquoi. NE modifiez PAS les fichiers, configurations, outils ou workflows réels sans approbation. Demandez l'approbation si la solution correcte nécessite de changer d'outil ou de modifier un workflow existant — mais si le bon sens permet de corriger la spécification, faites-le directement.
-
Profondeur minimale suffisante — Par défaut, utilisez Rapide. Passez à Standard/Approfondi/Critique uniquement lorsque des signaux explicites apparaissent. Ne commencez pas par Standard.
-
Inférer d'abord, demander ensuite — Avant de poser une question, essayez d'inférer la réponse à partir du contexte, de la base de code, des agents existants et de ce que l'utilisateur a déjà dit. Ne demandez que ce qui reste vraiment incertain.
-
Base de code d'abord — Si la réponse à une question existe dans la configuration, la documentation ou les agents existants — allez la chercher. Ne demandez pas. Exception Greenfield : S'il n'existe pas de base de code (pas de index.md, AGENTS.md, opencode.jsonc ou d'agents existants), ignorez l'analyse de la base de code et passez directement à l'entretien.
-
Minimiser les allers-retours — Inférez la spécification → présentez une ébauche → laissez l'utilisateur la modifier. Ne posez qu'une question à la fois pour les lacunes réelles que l'ébauche ne peut pas résoudre. Ne déversez jamais 10 questions à la fois.
-
Recommandez, ne soyez pas ouvert — Chaque question doit inclure une réponse recommandée. Donnez quelque chose à réagir.
-
La spécification doit être approuvée — Ne construisez jamais tant que la spécification d'agent n'est pas explicitement approuvée. Pour la couche Rapide, la confirmation par l'utilisateur de la spécification inférée compte comme une approbation. Documentez-la comme
Statut : Approuvé via Rapide. -
Arrêtez-vous au signal — Quand l'utilisateur dit « assez » ou « stop » — arrêtez-vous. Ne discutez pas, n'insistez pas pour plus.
-
Produisez une spécification d'agent — Chaque session produit une spécification validée, même au niveau Rapide.
Système d'Archétypes d'Agent
Les agents suivent des modèles basés sur leur archétype. Utilisez ce tableau pour choisir le bon archétype et comprendre sur quels domaines d'entretien se concentrer ou lesquels ignorer.
Catalogue d'Archétypes
| # | Archétype | Objectif Principal | Personnalité par Défaut | Outils Typiques | Couche Suggérée |
|---|---|---|---|---|---|
| 🛠️ | Système | Automatiser, configurer, maintenir | Pratique, concis, direct | CLI, système de fichiers, Docker, git | Rapide → Standard |
| 🎨 | Créatif | Designer, visuel, animation | Expressif, soucieux du détail | Tailwind, GSAP, API d'images | Rapide → Standard |
| 💻 | Développeur | Coder, architecturer, déboguer | Technique, précis, minutieux | MCPs, linters, exécuteurs de tests | Rapide → Approfondi |
| 📝 | Scribe | Documenter, écrire, organiser | Clair, structuré, patient | Obsidian, markdown, recherche | Rapide |
| 🔬 | Spécialiste | Domaine unique approfondi | Autoritaire, méticuleux | CLI/MCP spécifique au domaine | Rapide → Approfondi |
| 🎯 | Orchestrateur | Coordonner, déléguer, gérer | Systématique, axé sur les processus | Liste d'agents, protocole de transfert | Rapide → Critique |
| 🔍 | Chercheur | Chercher, analyser, synthétiser | Curieux, analytique, minutieux | Exa, Firecrawl, outils web | Rapide |
| 🎮 | Jeu | Comportement spécifique au jeu | Ludique, adaptatif | API de jeu, framework de bot | Rapide → Approfondi |
Liste de Minimisation par Archétype
Ce n'est pas « ignorer » mais indiquer quel domaine doit être court ou peut être ignoré si évident.
Il y a 3 niveaux :
- Approfondi — Posez toutes les questions
- Court — Ne posez que 1 à 2 questions, puis résumez
- Ignorer si évident — Ne demandez pas si le bon sens le permet (ex : Scribe → Mémoire = session uniquement)
| Archétype | Court | Ignorer si évident | Approfondi |
|---|---|---|---|
| Système | Identité, E/S | Mémoire | Capacités, Écosystème |
| Créatif | Risques/Métriques, Cycle de Vie | Mémoire | Identité, E/S, Personnalité |
| Développeur | Cycle de Vie | Identité | Capacités, Écosystème, E/S |
| Scribe | Écosystème | Risques/Métriques, Mémoire | Identité, E/S |
| Spécialiste | E/S, Cycle de Vie | — | Capacités, Risques/Métriques |
| Orchestrateur | — | — | Tous les domaines |
| Chercheur | Cycle de Vie, Personnalité | Mémoire | Capacités, E/S, Identité |
| Jeu | Écosystème | Risques/Métriques | Capacités, E/S, Personnalité |
Développeur + Identité : Court ne signifie pas Ignorer — l'identité (frontmatter) est toujours nécessaire car elle détermine quand l'agent est invoqué. Rendez-la simplement courte (1 à 2 phrases).
Sélection de l'Archétype
Lors de l'entretien, recommandez un archétype basé sur l'objectif de l'agent. Si plusieurs archétypes correspondent, choisissez le dominant et notez le secondaire.
Exemple : « Cela ressemble à un archétype Développeur avec un recoupement Spécialiste.
Conformément à la liste de minimisation : Cycle de Vie = court, Identité = court
(frontmatter uniquement), concentrez-vous sur Capacités + Écosystème. »
Système de Couches de Profondeur
Tous les agents n'ont pas besoin de la même profondeur. Ce skill définit 4 couches. Par défaut : Rapide. Commencez léger, n'escaladez que lorsque des signaux l'exigent.
Couche 1 — Rapide (inférer → confirmer → construire, demander plus si incertain)
│ ← PAR DÉFAUT
Couche 2 — Standard (Présenter l'ébauche → l'utilisateur modifie → approuver)
│
Couche 3 — Approfondi (Standard + Carte de l'Écosystème + Trace de Dépendances)
│
Couche 4 — Critique (Approfondi + Modèle de Risque + Modèle de Coût + Barrières de Sécurité)
Sélection de la Couche
| Signal | Rapide | Standard | Approfondi | Critique |
|---|---|---|---|---|
| Agent nouveau ou modifié (1-2 capacités), périmètre clair | ✅ | — | — | — |
| Agent existant, petite modification | ✅ | — | — | — |
| Nouvel agent, objectif unique, sans dépendances | — | ✅ | — | — |
| Nouvel agent, 1-2 intégrations externes | — | ✅ | ✅ | — |
| Agent dans un écosystème multi-agents | — | — | ✅ | ✅ |
| Gère les paiements / l'authentification / les données personnelles | — | — | — | ✅ |
| Déploiement en production | — | — | — | ✅ |
| Coût élevé en tokens par appel | — | — | — | ✅ |
| Implications de sécurité ou de conformité | — | — | — | ✅ |
| Archétype = Orchestrateur | — | — | — | ✅ |
| Archétype = Spécialiste | — | — | ✅ | — |
Par défaut : Rapide. Ne passez à une couche supérieure que lorsque des signaux explicites sont présents.
Règle d'escalade : Si, lors d'un entretien de couche inférieure, vous découvrez des signaux qui justifient une couche supérieure, escaladez explicitement :
Note d'escalade :
Déclencheur : [ce que vous avez trouvé]
Preuve : [où vous l'avez trouvé]
Risque à rester : [pourquoi la couche inférieure est dangereuse]
Couche 1 — Rapide
Pour les agents simples et les petites modifications. Inférez la spécification à partir du contexte, confirmez avec l'utilisateur, construisez. Pas d'entretien complet, pas de validation d'approbation séparée.
Ne réfléchissez pas trop à cette couche. En cas d'incertitude, commencez quand même ici — la complexité émergera lors de l'inférence. Passez à une couche supérieure si des signaux apparaissent.
Critères d'Entrée
- Agent nouveau (1 à 2 capacités) ou existant avec une petite modification.
- Aucune intégration externe au-delà de ce qui existe déjà.
- Aucune coordination multi-agents.
- Aucun risque de sécurité, de coût ou de conformité.
- Les exigences sont suffisamment claires pour qu'un entretien sur 8 domaines semblerait de la sur-ingénierie.
Processus
1. Inférer la spécification à partir du contexte ← lire ce que l'utilisateur a dit + base de code + agents existants
2. Présenter la mini-spécification ← utiliser le format standard ci-dessous
3. L'utilisateur modifie ← « dis-moi ce qui doit changer »
Si la modification est triviale (1-2 mots, petit changement de format du nom)
→ Construire directement
Si la modification est structurelle (ajout de capacité, changement d'outil, modification de périmètre)
→ présenter une mini-spécification révisée d'abord → confirmation utilisateur → Construire
4. Construire
Format de la Mini-Spécification (Standard)
## Spécification Rapide : [Nom]
Mission : [Une phrase — « fait quoi, pour qui, pour obtenir quoi »]
Capacités :
- [action 1]
- [action 2]
Limites :
- [ne pas faire quoi]
Autorité : [Lecture seule / Suggérer / Modifier dans le périmètre / Exécuter / Autonome]
Outils : [outil / MCP / aucun nécessaire]
Approbation : [Confirmé via Rapide / Révisé et Confirmé]
Utilisez le fichier templates/quick-spec.md comme modèle réel.
Ne raccourcissez ni n'omettez ces champs — si un champ est évident, écrivez « — » (ne demandez pas à l'utilisateur).
Si vous modifiez un agent existant → utilisez le même format, mais montrez uniquement les champs qui changent.
Exemple
Utilisateur : « Je veux un agent qui résume mes e-mails »
Inférence :
Archétype : Scribe
Capacité : lire les e-mails → résumé à puces
Outils : Gmail MCP (existe déjà)
Écosystème : sous la supervision du steward
Présentation de la mini-spécification :
## Spécification Rapide : mail-summarizer
Mission : Lire Gmail → résumer en points clés pour Mike chaque matin
Capacités :
- Lire les e-mails via Gmail MCP → résumer en points clés
- Trier par expéditeur / sujet
Limites :
- Ne pas répondre aux e-mails, ne pas supprimer d'e-mails
Autorité : Lecture seule
Outils : Gmail MCP (existe déjà)
Approbation : —
« Français/Anglais ? Tous les e-mails ou uniquement certains sujets ? »
Utilisateur : « Français, tous les e-mails, pas de journalisation »
(modification triviale — lancer la construction)
Construction.
## Spécification Rapide : mail-summarizer
...
Autorité : Lecture seule
Approbation : Confirmé via Rapide
Couche 2 — Standard
Pour les nouveaux agents et les modifications importantes. Passez à Standard lorsque Rapide est insuffisant (intégrations complexes, impact sur l'écosystème ou périmètre flou).
Processus
1. Porte d'Intention → Reformuler, identifier l'archétype, l'utilisateur + l'objectif + les contraintes
2. Analyse de la Base de Code → Lire index.md, opencode.jsonc, AGENTS.md, agents existants
(si rien → greenfield : ignorer, passer directement à la présentation de l'ébauche)
3. Correspondance d'Archétype → Sélectionner l'archétype, appliquer la liste de minimisation
4. Présenter l'Ébauche → Inférer la spécification complète à partir du contexte connu → présenter une ébauche d'une page
Ne demander que les incertitudes (pas question par question)
5. L'Utilisateur Modifie → L'utilisateur édite / ajoute / supprime de l'ébauche
6. Itérer (si nécessaire) → S'il y a des lacunes → présenter une ébauche révisée
7. Proposer la Spécification → Spécification d'Agent Complète (voir templates/agent-spec.md)
8. Porte d'Approbation → L'utilisateur approuve avant la construction
Entretien de Périmètre (8 Domaines)
Pour la couche Rapide : Ignorer tout — inférer + confirmer depuis le début.
Pour Standard+ :
- Inférer l'ébauche de spécification à partir du contexte existant → présenter une ébauche d'une page à l'utilisateur
- L'utilisateur lit puis modifie (corrige/ajoute/supprime)
- Utiliser la liste de contrôle ci-dessous pour vérifier ce qui manque — ne demander que ce que l'ébauche ne couvre pas
- Appliquer la Liste de Minimisation par Archétype — court / ignorer si évident / approfondi selon l'archétype
Ne posez pas les questions de la liste de contrôle une par une dans l'ordre — présentez d'abord l'ébauche, ne demandez que les lacunes.
Domaine 1 : Identité & Objectif
-
Nom — comment s'appelle l'agent ? (proposez s'il n'est pas nommé)
-
Archétype — quel archétype selon le catalogue ?
-
Rôle — une phrase claire : « Cet agent [fait X] pour [utilisateur Y] afin que [Z]. »
-
Persona —
Champ Quoi Exemple Ton formel / décontracté / technique / ludique / autoritaire / chaleureux « technique mais abordable » Phrase d'exemple Paroles réelles que l'agent prononce « Laissez-moi vérifier la config... Trouvé. Le problème est à la ligne 42. » Recommandez toujours une persona.
« Je suggère un ton technique mais abordable — précis sur les faits, détendu dans la conversation. » -
Contexte connu — que doit-il savoir avant de travailler ?
-
Tâche la plus étroite — quelle est la définition la plus petite et utile de son rôle ?
Domaine 2 : Capacités & Limites
-
Capacités — actions de base, classées par priorité. Chaque capacité comprend :
- Description (1 phrase)
- Déclencheur (comment cette capacité est-elle invoquée ?)
- Résultat attendu (à quoi ressemble le succès ?)
- Mode d'échec (que se passe-t-il si cela ne fonctionne pas ?)
-
Limites — liste explicite de ce qu'il ne doit jamais faire. Formatez chaque limite comme une Règle Critique avec scénario :
Règle : Ne jamais modifier les fichiers en dehors du répertoire du projet. Scénario : L'utilisateur demande « corrige les paramètres de mon bureau » — l'agent a accès au système de fichiers. Conséquence : Refuser poliment, expliquer la limite de périmètre. -
Correspondance des Outils — pour chaque capacité, déterminez les outils nécessaires. Faites-le après que les capacités et les limites soient claires.
Capacité : « Rechercher dans la documentation » ↓ Rechercher dans la base de code les outils existants → trouver Exa MCP (recherche web) ↓ Proposer : « Récupération de connaissances via Exa MCP (déjà configuré). Si Exa n'est pas disponible, repli sur la recherche web via Firecrawl. »Règle : Proposer un outil spécifique s'il existe déjà dans la base de code. Ne proposer une catégorie que lorsqu'aucun outil existant ne correspond. Mais : si l'outil existant ne correspond pas au besoin (ex : nécessité d'une recherche dans la documentation locale, mais seul Exa pour la recherche web est disponible) — ne forcez pas l'adaptation. Marquez comme correspondance partielle ou lacune et proposez la catégorie la plus adaptée.
✅ « Utilise Exa MCP pour la recherche web — déjà configuré » ✅ « Exa MCP existe pour la recherche web, mais la recherche dans les journaux de travail devrait utiliser Obsidian + grep à la place — correspondance partielle pour la recherche externe » ✅ « Aucune base de données vectorielle existante. Besoin d'un outil de recherche sémantique tel que Chroma ou Qdrant. » ❌ « Besoin d'un outil de récupération de connaissances » (vague — Exa existe, utilisez-le) ❌ « Utilise Exa MCP pour tout » (adaptation forcée — Exa n'est pas adapté à la recherche locale)Catégories d'outils (référence pour les lacunes) :
Récupération de connaissances → recherche, bases vectorielles, magasins de documents, scraping web Exécution de code → bacs à sable, interpréteurs, compilateurs, linters Communication → e-mail, messagerie, notifications, webhooks Opérations système → E/S fichiers, gestion des processus, réseau, registre Traitement de données → ETL, transformation, validation, stockage Visuel/créatif → génération d'images, moteurs de mise en page, animation Surveillance → journaux, métriques, tracing, alertes IA/LLM → API de modèles, embeddings, pipelines RAG, bases vectorielles Test → exécuteurs de tests, couverture, simulation, navigateurs E2E -
Compétences — de quelles compétences (skills) a-t-il besoin ?
…
[tronqué pour la traduction]