👥 Les agents spécialisés

Le concept

Par défaut, Claude Code est un généraliste. Il sait tout faire, mais sans directives spécifiques, il peut faire des choix incohérents : utiliser la mauvaise palette de couleurs, ranger un fichier au mauvais endroit, ou oublier une règle métier.

Les agents spécialisés résolvent ce problème. Chaque agent est briefé sur son domaine : quels fichiers il touche, quelles règles il suit, comment il vérifie son travail.

L'analogie : au lieu d'avoir un seul employé qui fait tout (cuisine, service, comptabilité, ménage), tu as un chef cuisinier, un serveur, un comptable, et un agent d'entretien. Chacun excelle dans sa spécialité et connaît ses règles.

Comment les créer

1. Crée le dossier

Crée un dossier .claude/commands/ à la racine de ton projet. Chaque fichier .md dans ce dossier devient automatiquement une commande slash.

ton-projet/
  .claude/
    commands/
      front.md       → /front (agent interface)
      back.md        → /back (agent logique métier)
      database.md    → /database (agent base de données)
      qa.md          → /qa (agent qualité)
      orchestrate.md → /orchestrate (chef de projet)

2. Structure d'un fichier d'agent

Chaque fichier répond à 4 questions :

1. Qui es-tu ? Le rôle et la spécialité
2. Sur quoi tu travailles ? Les fichiers et dossiers concernés
3. Quelles règles tu suis ? Les conventions spécifiques au domaine
4. Comment tu vérifies ? Les commandes de validation

Les 6 agents types pour un SaaS

Agent Frontend, /front

Gère tout ce qui est visible : pages, composants, layouts, design.

# /front - Agent Frontend

Tu es l'agent frontend. Tu gères les composants UI,
pages, layouts et le design system.

## Périmètre
- src/app/ (toutes les pages et layouts)
- src/components/ (composants réutilisables)
- src/app/globals.css (styles globaux)

## Palette
- Primary: #E8634A - boutons, liens actifs
- Background: #FFFBF7 - fond de page
- Ne JAMAIS utiliser de couleurs hors palette

## Règles
- Server Components par défaut
- shadcn/ui pour tous les composants de base
- Interface en français avec accents corrects
- Un composant par fichier, kebab-case

## Vérification
Après chaque modification : npm run typecheck && npm run lint

Agent Backend, /back

Gère la logique métier, les API, l'authentification.

# /back - Agent Backend

Tu es l'agent backend. Tu gères les Server Actions,
la logique métier, et les intégrations.

## Périmètre
- src/lib/actions/ (Server Actions)
- src/lib/validators/ (schémas Zod)
- src/app/api/ (API routes)
- src/middleware.ts

## Règles
- Toute mutation passe par un Server Action, pas une API route
- Validation Zod obligatoire sur chaque input
- Vérifier l'authentification dans chaque action
- Ne jamais exposer de clé API côté client

## Vérification
Après chaque modification : npm run typecheck && npm run lint

Agent Database, /database

Gère le schéma SQL, les migrations, la sécurité (RLS).

# /database - Agent Base de données

Tu es l'agent database. Tu gères le schéma PostgreSQL,
les migrations, et les policies RLS.

## Périmètre
- supabase/migrations/ (fichiers SQL numérotés)
- src/lib/types/database.types.ts (types auto-générés)

## Règles
- Toute modification → nouvelle migration SQL numérotée
- RLS activé sur chaque table, filtrage par organisation_id
- JAMAIS utiliser supabase db reset

## Vérification
npx supabase migration up --local
npx supabase gen types typescript --local > src/lib/types/database.types.ts
npm run typecheck

Agent IA, /ia

Gère l'intégration des APIs d'IA, les prompts, le streaming.

# /ia - Agent IA

Tu es l'agent IA. Tu gères l'intégration Claude API,
les prompts, et le streaming.

## Périmètre
- src/lib/ai/ (client, prompts, rate-limit)
- src/app/api/ai/ (endpoints IA)

## Règles
- Toujours côté serveur, JAMAIS exposer l'API key
- Streaming via Anthropic SDK
- Usage tracking dans ai_usage après chaque appel
- Rate limiting par plan utilisateur

Agent QA, /qa

Gère les tests, le lint, le typecheck.

# /qa - Agent Qualité

Tu es l'agent QA. Tu gères les tests et la qualité du code.

## Quality Gates
| Gate | Commande | Quand |
|------|----------|-------|
| TypeScript | npm run typecheck | Après chaque modification |
| Lint | npm run lint | Après chaque modification |
| Unit Tests | npm run test | Avant commit |
| Build | npm run build | Avant deploy |

## Règles
- Tests unitaires pour toute logique métier
- Pas de tests pour le boilerplate trivial
- Coverage minimum : 80% sur les modules critiques

Agent Orchestrateur, /orchestrate

Coordonne tous les autres agents. C'est le chef de projet.

# /orchestrate - Chef de projet

Tu supervises tous les agents et le workflow.

## Workflow
1. Lire le plan dans docs/plans/
2. Dispatcher les tâches aux agents
3. Tâches indépendantes → en parallèle
4. Tâches dépendantes → séquentielles
5. Vérifier typecheck + lint après chaque groupe

## Quality Gates
- TypeScript : 0 erreurs
- Lint : 0 erreurs
- Build : succès
- Tests : tous passent

Comment utiliser les agents

Tu tapes la commande slash dans le chat, suivie de ta demande :

/front Crée un composant de notification banner qui affiche un message temporaire en haut de la page, avec un bouton de fermeture et une animation de slide-in.

L'agent /front sait automatiquement qu'il doit :

• Travailler dans src/components/
• Utiliser la palette du projet
• Utiliser shadcn/ui
• Vérifier avec typecheck + lint après

Sans l'agent, tu aurais dû préciser tout ça dans ton prompt.

Quand utiliser quel agent

Créer tes propres agents

Tu n'es pas limité aux 6 agents ci-dessus. Crée des agents pour n'importe quel besoin récurrent :

• /email : pour générer des templates d'emails avec le bon ton
• /seo : pour optimiser les meta tags et le contenu
• /security : pour auditer les failles
• /deploy : pour les checklists de mise en production
• /content : pour générer du contenu marketing aligné sur ta marque

La règle : si tu répètes les mêmes instructions plus de 3 fois, crée un agent.

Au-delà des slash commands : les sub-agents

Les slash commands (/front, /back, etc.) sont tes workflows manuels, tu les tapes dans le chat. Mais Claude Code a un autre niveau de puissance : les sub-agents.

Un sub-agent est un "mini-Claude" que Claude dispatche automatiquement pour une tâche spécifique. Il explore, analyse, puis renvoie un résumé au contexte principal. La différence :

Exemple : quand tu utilises un workflow comme /code Ajouter une page profil, Claude lance automatiquement un sub-agent explore-codebase qui analyse le projet et renvoie un résumé. Le contexte principal reste propre.

Les sub-agents se créent dans ~/.claude/agents/ (un fichier .md par agent, avec son rôle et ses contraintes). Ce sont des agents read-only, ils ne modifient aucun fichier.