Créer un nouvel agent

Ce tutoriel explique comment créer un agent spécialisé et l'intégrer dans vos workflows.

Rappel : agent vs persona

	Persona	Agent
Contexte	Conversation principale	Sous-processus isolé
Interaction	Dialogue	Mission → rapport
Usage	Rôle dans un pipeline	Tâche ciblée autonome

Créez un agent quand : la tâche est autonome, ciblée, et ne nécessite pas de dialogue avec l'utilisateur.

Étape 1 : Définir la mission

Question	Réponse
Quelle tâche effectue l'agent ?	Ex: "Vérifier la conformité des migrations Alembic"
Quelles entrées reçoit-il ?	Ex: "Le dossier alembic/versions/"
Quelle sortie produit-il ?	Ex: "Rapport de conformité avec ✅/❌"
Quel modèle ?	haiku (lookup), sonnet (implem), opus (analyse)
Read-only ou peut modifier ?	Ex: read-only

Étape 2 : Choisir l'emplacement

Scope	Emplacement	Usage
Framework (partagé)	framework/agents/{name}.md	Agents réutilisables partout
Projet (local)	.claude/agents/{name}.md	Agents spécifiques au projet

Étape 3 : Écrire le fichier agent

Créez framework/agents/{name}.md ou .claude/agents/{name}.md :

---
name: migration-checker
role: Vérificateur de migrations
model: haiku
color: orange
description: |
  Vérifie la conformité et la sécurité des migrations de base de données.
  Utiliser quand : nouvelle migration créée, avant merge d'une migration.
allowed-tools: Read, Glob, Grep, Bash
---

Section Identité

## Identité

Tu es un agent spécialisé dans la vérification des migrations de base
de données. Tu analyses chaque migration pour détecter les risques de
downtime, perte de données, et incohérences.

Section Responsabilités

## Responsabilités

1. Lire toutes les migrations dans `alembic/versions/`
2. Vérifier chaque migration contre la checklist :
   - [ ] Pas de `DROP TABLE` sans backup
   - [ ] Pas de `ALTER TABLE` avec lock (utiliser CONCURRENTLY)
   - [ ] Fonction downgrade() présente et fonctionnelle
   - [ ] Pas de données hardcodées (seeds ≠ migrations)
   - [ ] Dépendances de révision correctes (pas de branches orphelines)
3. Produire un rapport structuré

Section Contraintes

## Contraintes

- **Read-only** : ne modifie aucune migration
- **Facts only** : rapporter ce qui est, pas ce qui devrait être
- **Pas de fix** : identifier les problèmes, pas les corriger
- **Scope strict** : uniquement les fichiers de migration

Section Format de sortie

## Format de sortie

\`\`\`markdown
# Migration Check Report

## Résumé
- Migrations analysées : {n}
- ✅ Conformes : {n}
- ❌ Non conformes : {n}

## Détails

### ✅ 001_create_users.py
Conforme. Downgrade présent. Pas de lock.

### ❌ 003_add_email_index.py
- 🔴 `CREATE INDEX` sans `CONCURRENTLY` → risque de lock en production
- 🟡 Pas de downgrade pour le DROP INDEX

## Recommandations
1. Migration 003 : utiliser `CREATE INDEX CONCURRENTLY`
2. Migration 003 : ajouter `op.drop_index()` dans downgrade()
\`\`\`

Étape 4 : Tester l'agent

Invoquez directement depuis Claude Code :

Lance l'agent migration-checker sur le dossier alembic/versions/

Ou via un skill qui l'appelle :

### Step 04 — Vérifier les migrations

Lancer l'agent `migration-checker` sur le dossier de migrations.
Si des findings 🔴 sont trouvés, retourner au step 03 pour corriger.

Étape 5 : Intégrer dans un skill

Pour qu'un skill lance votre agent, mentionnez-le dans un step :

### Step 03 — Validation automatique

Lancer les agents suivants en parallèle :
- `migration-checker` sur `alembic/versions/`
- `code-reviewer` sur les fichiers modifiés

Si les deux agents retournent ✅, passer au step suivant.
Sinon, lister les findings et retourner au step 02.

Exemples d'agents utiles

Agent	Modèle	Mission
migration-checker	haiku	Vérifier les migrations DB
api-tester	sonnet	Tester les endpoints avec curl
dependency-auditor	haiku	Vérifier les dépendances obsolètes/vulnérables
doc-generator	sonnet	Générer la documentation API
perf-profiler	sonnet	Analyser les performances

Bonnes pratiques

Modèle le plus léger possible

Utilisez haiku pour les agents de scan/lookup. Réservez sonnet pour ceux qui produisent du code ou de l'analyse complexe. opus uniquement pour l'architecture.

Output structuré

Définissez toujours un format de sortie précis. Un agent qui retourne du texte libre est difficile à exploiter dans un pipeline.

Scope étroit

Un agent doit faire une seule chose bien. Si votre agent fait 5 choses différentes, découpez-le en 5 agents.