Les agents spécialisés

Quatre outils qu'on appelle tous "agents"

Dans Claude Code, le mot "agent" recouvre quatre mécanismes différents. Les confondre fait perdre du temps et des tokens (un token, c'est l'unité de texte que le modèle lit et écrit, et sur laquelle tu es facturé).

Ce chapitre détaille les deux premiers, ceux que tu utiliseras tous les jours. Les workflows et les agent teams sont présentés en fin de chapitre, et détaillés au chapitre 18.

Les commandes spécialisées

Par défaut, Claude Code est un généraliste. Il sait tout faire, mais sans directives, il fait des choix incohérents : la mauvaise palette de couleurs, un fichier rangé au mauvais endroit, une règle métier oubliée.

Une commande spécialisée règle ça. Elle est briefée sur son domaine : quels fichiers elle touche, quelles règles elle suit, comment elle vérifie son travail.

Même logique que dans un resto : le chef connaît les règles de la cuisine, et personne ne lui demande de tenir la compta.

1. Crée le dossier

Crée un dossier .claude/commands/ à la racine de ton projet. Chaque fichier .md dedans devient une commande slash. Depuis janvier 2026, commandes et skills sont fusionnées : .claude/commands/front.md et .claude/skills/front/SKILL.md créent tous les deux /front. Le format skill (un dossier) sert quand tu veux embarquer des fichiers en plus du prompt.

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

2. Structure d'un fichier de commande

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 du domaine
4. Comment tu vérifies ? Les commandes de validation

Ajoute une description en frontmatter (le bloc entre --- en haut du fichier). C'est elle que Claude lit pour savoir quand proposer la commande. Sans elle, il prend la première ligne du fichier, rarement écrite pour ça. Le chapitre 8 montre le format exact.

Les 6 commandes types pour un SaaS

Frontend, /front

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

# /front - 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
- Jamais de couleur 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

Backend, /back

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

# /back - 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

Database, /database

Gère le schéma SQL, les migrations, la sécurité (RLS, les règles d'accès ligne par ligne de Postgres).

# /database - Base de données

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 de 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

IA, /ia

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

# /ia - Intégration 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 de clé API exposée
- Streaming via Anthropic SDK
- Usage tracking dans ai_usage après chaque appel
- Rate limiting par plan utilisateur

QA, /qa

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

# /qa - Qualité

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

Orchestrateur, /orchestrate

Coordonne le reste. C'est le chef de projet, et le seul de la liste qui a intérêt à lancer des subagents.

# /orchestrate - Chef de projet

Tu supervises l'exécution d'un plan.

## Workflow
1. Lire le plan dans docs/plans/
2. Tâches indépendantes → un subagent par tâche, en parallèle
3. Tâches dépendantes → séquentielles, dans la conversation principale
4. Vérifier typecheck + lint après chaque groupe

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

Utiliser une commande

Tu tapes la commande slash, 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.

/front sait déjà qu'il doit travailler dans src/components/, respecter la palette, passer par shadcn/ui et vérifier avec typecheck + lint. Sans la commande, tu aurais dû l'écrire dans ton prompt.

Tu n'es pas limité à ces 6. Un /email, un /deploy : crée une commande pour tout besoin récurrent. La règle : si tu répètes les mêmes instructions plus de 3 fois, ça mérite un fichier.

Les subagents

Un subagent fonctionne à l'envers d'une commande. Tu décris un objectif, Claude délègue.

Depuis la version 2.1.198 de Claude Code (1er juillet 2026), les subagents tournent en arrière-plan par défaut. Tu continues à parler à Claude pendant qu'ils bossent, et ils te notifient quand ils ont fini. Claude peut en lancer jusqu'à 20 en parallèle.

Créer un subagent

L'assistant interactif /agents a été supprimé en v2.1.198. Deux façons de faire aujourd'hui.

Le plus simple : demande-le à Claude.

"Crée un subagent explorer dans .claude/agents/ qui cartographie une zone du code et me renvoie la liste des fichiers clés avec une ligne d'explication chacun. Modèle haiku."

À la main : un fichier markdown dans .claude/agents/ (pour le projet) ou ~/.claude/agents/ (pour tous tes projets).

---
name: explorer
description: Cartographie une zone du code et renvoie les fichiers clés. À utiliser avant de modifier une partie du projet que tu ne connais pas.
model: haiku
---

Tu explores le code en lecture seule.
Renvoie la liste des fichiers pertinents, une ligne par fichier,
puis les 3 points d'attention avant de modifier cette zone.
Ne modifie aucun fichier.

La description compte autant que le prompt : c'est elle que Claude lit pour décider quand déléguer. Le champ model: choisit le modèle du subagent. Haiku suffit pour explorer, lire des logs ou chercher un fichier, et coûte bien moins cher qu'Opus.

L'outil Agent et l'isolation worktree

Pour lancer un subagent, Claude utilise l'outil Agent (il s'appelait Task dans les anciennes versions et les vieux tutos). L'option à connaître, c'est isolation: "worktree" : le subagent récupère son propre git worktree, une copie séparée du repo sur une branche dédiée. Depuis la v2.1.222 (début août 2026), cette isolation couvre aussi ses edits et ses commandes Bash.

Sans worktree, deux subagents qui écrivent sur app/page.tsx en même temps se marchent dessus. Avec, chacun a son bac à sable et tu merges à la fin.

Exemple : traduire 3 articles FR vers EN

Trois articles MDX, indépendants les uns des autres. Trois subagents en parallèle, chacun sur son worktree.

Ce que Claude envoie (pseudo-code) :

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

Agent({
  description: "Traduire article 2",
  prompt:
    "Traduis content/fr/article-2.mdx vers content/en/article-2.mdx. Mêmes règles : structure MDX, frontmatters, ton informel.",
  isolation: "worktree",
});

Agent({
  description: "Traduire article 3",
  prompt:
    "Traduis content/fr/article-3.mdx vers content/en/article-3.mdx. Mêmes règles : structure MDX, frontmatters, ton informel.",
  isolation: "worktree",
});

Les 3 tournent en arrière-plan. Chacun écrit son fichier dans son worktree, Claude récupère les résultats et merge. Toi, tu n'as tapé qu'une phrase : "Traduis ces 3 articles en parallèle, un subagent par article."

Le fork : un subagent qui hérite de ta conversation

• Claude le lance avec subagent_type: "fork" dans l'outil Agent.
• /subtask <tâche> : tu lances toi-même un subagent forké sur une tâche précise.
• /fork [prompt] : copie ta conversation dans une session de fond, avec son propre worktree. Tu continues ici, la copie avance de son côté.

Workflows et agent teams, en deux mots

Les workflows (depuis fin mai 2026) : tu ajoutes le mot-clé ultracode à ta demande ("ultracode: audit every API endpoint"). Claude écrit alors un script que Claude Code exécute en arrière-plan sur des dizaines, parfois des centaines de subagents. /workflows liste ceux qui tournent et permet de les sauvegarder dans .claude/workflows/ pour les relancer. Sur Pro, ça s'active dans /config, en taille réduite par défaut.

Les agent teams : plusieurs sessions Claude qui se coordonnent. C'est encore expérimental (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), et la doc d'Anthropic annonce environ 7 fois plus de tokens qu'une session standard quand les coéquipiers tournent en plan mode. À réserver aux gros chantiers.

Les deux, avec /goal, /loop et les routines, sont détaillés au chapitre 18.

Quand utiliser quoi

La règle : subagents quand les tâches sont indépendantes. Si elles dépendent l'une de l'autre, reste en séquentiel dans ta conversation.

Ce que ça coûte

Un subagent ne relit pas le cache de ta conversation. Il repart de zéro, et son cache ne dure que 5 minutes, même sur abonnement (ta conversation principale a droit à 1 heure). Seul le fork réutilise le cache du parent.

En pratique :

• Pour lire 50 fichiers ou des logs, un subagent haiku coûte moins cher que de tout charger dans ta session Opus, et ton contexte principal reste léger.
• Pour une petite tâche qui demande tout ton contexte, un fork est plus économique qu'un subagent à qui il faut tout réexpliquer.
• Lancer 20 subagents, c'est 20 contextes qui se remplissent. Tu gagnes du temps, ta consommation ne baisse pas pour autant.

Le détail des mécanismes de cache et de facturation est au chapitre 19.

Sources

• Changelog officiel de Claude Code
• Workflows, documentation Claude Code
• Gérer les coûts, documentation Claude Code
• Prompt caching dans Claude Code