Agents & sous-agents

Un sous-agent est une instance de Claude Code lancée avec sa propre fenêtre de contexte, éventuellement un prompt système spécialisé et un sous-ensemble d'outils. On délègue à un sous-agent pour :

• Protéger le contexte principal : une recherche qui produirait beaucoup de bruit (lecture de dizaines de fichiers) reste dans le sous-agent ; seul le résumé final remonte à la conversation principale.
• Spécialiser le comportement : un agent "Explore" en lecture seule, un agent "code-reviewer" avec un prompt orienté qualité, etc.
• Paralléliser : plusieurs sous-agents indépendants peuvent travailler en même temps sur des sous-tâches distinctes.

Un sous-agent se définit dans .claude/agents/ :

---
name: code-reviewer
description: Relit un diff pour des bugs, des problèmes de sécurité et de la dette technique.
tools: Read, Grep, Glob, Bash
model: inherit
---
Tu es un relecteur de code exigeant. Pour chaque diff, identifie :
1. Les bugs probables et cas limites non gérés.
2. Les failles de sécurité (injection, XSS, secrets en dur).
3. Les opportunités de simplification, sans sur-ingénierie.

On l'invoque ensuite via l'outil Task/Agent (subagent_type: "code-reviewer"), ou indirectement via une commande comme /review.

Un sous-agent peut tourner :

• en avant-plan, bloquant la conversation jusqu'à son retour (utile quand son résultat est nécessaire pour continuer) ;
• en arrière-plan (run_in_background), pour du travail indépendant dont le résultat n'est pas immédiatement bloquant ;
• dans un worktree git isolé (isolation: "worktree"), pour travailler sur une copie du repo sans risquer le répertoire de travail principal.

Un nouvel appel d'agent démarre sans mémoire de la conversation en cours : tout le contexte nécessaire doit être inclus explicitement dans le prompt de délégation.

Un sous-agent ne voit que ce qu'on lui donne. Un bon prompt de délégation :

• explique l'objectif et pourquoi la tâche est nécessaire ;
• donne les chemins de fichiers, noms de fonctions, contraintes déjà identifiées ;
• précise le format de réponse attendu (court résumé, liste, etc.) ;
• évite de déléguer la compréhension : ne demandez pas « corrige le bug », mais détaillez ce que vous savez déjà du bug et ce qu'il reste à vérifier.

Une consigne vague produit un travail générique ; un brief précis produit un travail exploitable directement.

Pour une tâche découpée en plusieurs étapes, une liste de tâches explicite (créée avec TaskCreate, mise à jour au fil de l'avancement) rend le travail vérifiable : chaque étape passe de « à faire » à « en cours » puis « terminée » au fur et à mesure, plutôt que de rester une intention implicite.

Un sous-agent lancé en arrière-plan ne bloque pas la conversation : le travail continue de votre côté, et vous êtes notifié automatiquement quand il se termine, sans avoir besoin de revenir vérifier régulièrement. Pour suivre en direct la sortie d'un processus long déjà lancé (un build, un déploiement), l'outil Monitor permet de s'y attacher et de recevoir chaque nouvelle ligne comme un événement.

Règle importante : tant qu'un agent en arrière-plan n'a pas renvoyé de résultat, il ne faut ni l'inventer ni le prédire ; le résultat n'existe que lorsqu'il arrive réellement.

Au-delà d'une délégation ponctuelle, un agent peut être reprogrammé pour se réveiller plus tard ou tourner à intervalle régulier :

• Une boucle (par exemple via une compétence de type /loop) réexécute un même prompt à intervalle fixe, ou laisse l'agent choisir lui-même son propre rythme entre deux passages selon ce qu'il attend (un déploiement qui prend quelques minutes n'a pas besoin d'être revérifié toutes les 10 secondes).
• Un agent planifié (cron) se déclenche à un horaire ou une récurrence définie à l'avance, indépendamment d'une conversation en cours : utile pour une veille régulière ou une tâche de maintenance périodique.

Différence avec les hooks (module suivant) : un hook réagit à un événement du cycle de vie de l'agent (avant/après un outil, fin de session...), tandis que la planification se déclenche sur le temps qui passe, avec ou sans événement associé.