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.

Sub-agents autonomes : paralléliser le travail

Les agents via commands/ sont déclenchés par toi : tu tapes /front, ça part. Un sub-agent autonome, c'est l'inverse : tu décris un objectif, Claude délègue à un ou plusieurs agents qui bossent en parallèle, chacun dans son propre contexte isolé.

La différence en une ligne :

• Command-agent (/front) : toi tu pilotes, l'agent exécute ta demande précise.
• Sub-agent autonome : Claude dispatche plusieurs agents qui tournent en parallèle, chacun avec sa mémoire, ses fichiers, son résultat.

Le tool Task et les worktrees

Pour lancer un sub-agent, Claude utilise le tool Task. L'option clé, c'est isolation: "worktree" : chaque sub-agent récupère son propre git worktree, une copie séparée du repo sur une branche dédiée. Résultat : deux agents peuvent modifier le même fichier sans conflit, puisqu'ils travaillent dans des dossiers différents.

Sans worktree, deux agents qui écrivent sur app/page.tsx en même temps se mangent la laine sur le dos. Avec worktree, chacun a son sandbox, tu merges à la fin.

Quand utiliser quoi

La règle : sub-agent quand les tâches sont indépendantes. Si elles se marchent dessus, reste sur du séquentiel via commande.

Exemple concret : traduire 3 articles FR vers EN

Tu as 3 articles MDX à traduire. Chacun est indépendant du suivant. Parfait pour 3 sub-agents en parallèle, chacun sur son worktree.

Pseudo-code du dispatch :

Task({
  description: "Traduire article 1",
  prompt:
    "Traduis content/fr/article-1.mdx vers content/en/article-1.mdx. Garde la structure MDX et les frontmatters. Respecte le ton informel.",
  isolation: "worktree",
});

Task({
  description: "Traduire article 2",
  prompt:
    "Traduis content/fr/article-2.mdx vers content/en/article-2.mdx. Même règles.",
  isolation: "worktree",
});

Task({
  description: "Traduire article 3",
  prompt:
    "Traduis content/fr/article-3.mdx vers content/en/article-3.mdx. Même règles.",
  isolation: "worktree",
});

Les 3 tournent en parallèle, chacun écrit son fichier dans son worktree. À la fin, Claude merge les résultats dans le contexte principal. Temps divisé par 3 si tu avais fait ça en séquentiel.