Claude Code est l'un des outils les plus puissants pour le développement assisté par IA, mais sans les bonnes pratiques, il tourne en rond. Il consomme du contexte inutilement, modifie des fichiers qu'il ne devrait pas toucher, et produit du code que personne ne vérifie. L'équipe HumanoAI a partagé ses 11 techniques de terrain, affinées après des mois d'utilisation quotidienne. Ces techniques se structurent autour de quatre piliers : Contexte, Contrôle, Accélération et Vérification.
Analyser pour progresser : la commande /insights
La première technique est la plus contre-intuitive. Avant de chercher à être plus productif, il faut comprendre où l'on perd du temps. La commande /insights analyse les sessions passées de Claude Code et génère un rapport d'amélioration.
La commande /insights identifie les points de friction récurrents : les boucles où l'agent répète la même erreur, les moments où le contexte manque, les patterns qui fonctionnent bien. Le résultat est un ensemble de recommandations que vous pouvez directement importer dans votre fichier CLAUDE.md.
L'idée est simple mais puissante : plutôt que de deviner ce qui freine votre workflow, laissez Claude analyser ses propres échecs. Ces recommandations s'accumulent et affinent progressivement votre fichier CLAUDE.md, qui finit par refléter exactement vos conventions d'équipe.
Nourrir l'agent : documentation structurée et Context7
Un agent IA sans contexte est un stagiaire sans briefing. La deuxième famille de techniques concerne la qualité et l'efficacité du contexte fourni à Claude Code.
documentation comme contexte
L'équipe HumanoAI structure son contexte autour de quatre fichiers clés :
- PRD (Product Requirements Document) : le "quoi" du projet, les objectifs fonctionnels
- architecture.md : les décisions techniques, la structure du code, les dépendances
- decision.md : l'historique des choix techniques et leurs justifications
- feature.json : un format optimisé pour la consommation de tokens
Le format JSON pour les features est un choix délibéré. Le JSON compacte mieux l'information : plus de détails par token consommé. Il inclut une clé passes qui permet de suivre l'état d'avancement de chaque fonctionnalité :
{
"features": [
{
"id": "auth-oauth2",
"description": "OAuth2 authentication flow",
"status": "in-progress",
"passes": {
"implementation": true,
"tests": false,
"review": false
},
"dependencies": ["user-model", "session-store"],
"acceptance_criteria": [
"User can login via Google OAuth",
"Tokens refresh automatically",
"Failed auth returns 401"
]
}
]
}context7 mcp : de la documentation à jour
Même avec une bonne documentation projet, Claude Code peut générer du code basé sur des API obsolètes. La raison : ses connaissances de formation ont une date de coupure. Le serveur MCP Context7 résout ce problème en fournissant la documentation à jour des bibliothèques utilisées dans votre projet.
Au lieu de deviner la signature d'une fonction, Claude Code interroge Context7 et obtient la documentation actuelle. Résultat : moins de décalages entre les versions, moins de corrections manuelles, un code plus fiable dès la première génération.
point clé : le contexte est le carburant
Un agent Claude Code avec un CLAUDE.md bien rédigé, des fichiers de contexte structurés et un accès à Context7 ne produit pas simplement "un meilleur code". Il produit du code qui respecte vos conventions dès la première passe, réduisant les allers-retours de correction.
Contrôler l'agent : hooks, strict mode et garde-fous
Le contexte dit à l'agent quoi faire. Les garde-fous lui disent quoi ne pas faire. Sans contraintes explicites, un agent IA prendra des raccourcis dangereux : il modifiera vos tests pour les faire passer, il supprimera un fichier de config plutôt que de résoudre un conflit.
hooks avec codes de sortie
Les hooks Claude Code interceptent les actions de l'agent avant leur exécution. Le système repose sur les codes de sortie Unix :
- Exit 0 : l'action est autorisée, l'agent continue
- Exit 2 : l'action est bloquée, l'agent doit trouver une alternative
L'application concrète la plus utile : protéger les fichiers de test. Si vous pratiquez le TDD, vos tests représentent la spécification. Un agent ne doit jamais les modifier pour faire passer son code. Voici un hook pre-tool-use qui bloque toute écriture dans les fichiers de test :
#!/bin/bash
# .claude/hooks/protect-tests.sh
# Hook pre-tool-use : bloque l'ecriture dans les fichiers de test
# Les hooks Claude Code recoivent du JSON via stdin
input=$(cat)
TOOL_NAME=$(echo "$input" | jq -r '.tool_name')
FILE_PATH=$(echo "$input" | jq -r '.tool_input.file_path // empty')
# Verifier si l'outil est une operation d'ecriture
if [[ "$TOOL_NAME" == "Write" || "$TOOL_NAME" == "Edit" ]]; then
# Verifier si le fichier cible est un fichier de test
if [[ "$FILE_PATH" == *".test."* || "$FILE_PATH" == *".spec."* || "$FILE_PATH" == *"__tests__"* ]]; then
echo "BLOQUE: Modification de fichier de test interdite." >&2
echo "Adaptez votre code pour satisfaire le test existant." >&2
exit 2 # Erreur bloquante
fi
fi
exit 0 # Autoriser toutes les autres operationsLe code de sortie 2 est la clé. Il ne se contente pas de signaler une erreur : il force l'agent à changer d'approche. L'agent ne peut pas ignorer un exit 2.
typescript strict mode comme garde-fou passif
Activer le mode strict de TypeScript ("strict": true dans tsconfig.json) déplace la détection des erreurs du runtime vers le compile-time. Pour un agent Claude Code, c'est une différence majeure : au lieu de découvrir un bug au moment de l'exécution (souvent tard dans le processus), il voit l'erreur immédiatement dans le terminal.
Les agents IA s'appuient massivement sur les logs d'erreur du terminal pour corriger leur code. Plus ces erreurs sont précoces et précises, moins l'agent tourne en rond. Le mode strict est un investissement unique qui améliore durablement chaque session.
user stories comme critères d'acceptation
Les user stories complètent les hooks : définissez-les avant l'implémentation. L'équipe HumanoAI rédige ses user stories pour décrire comment l'utilisateur interagit avec le système, pas comment le système fonctionne en interne. Cela donne à Claude Code un objectif vérifiable plutôt qu'une description technique.
Accélérer sans perdre le contrôle : Git worktrees et MCP CLI
Une fois le contexte et les garde-fous en place, la question devient : comment paralléliser le travail de plusieurs agents sans créer le chaos ?
git worktrees : des agents vraiment isolés
La différence entre les branches et les worktrees est physique, pas logique. Quand vous créez une branche, les agents partagent le même répertoire de travail. Quand l'agent A modifie un fichier, l'agent B voit la modification. C'est une source de conflits permanente.
Les git worktrees créent des répertoires distincts liés au même dépôt. Chaque agent travaille dans son propre répertoire, avec son propre état de fichiers. Il n'y a aucun risque de collision :
# Creer un worktree pour chaque agent
git worktree add ../projet-feature-auth feature/auth
git worktree add ../projet-feature-api feature/api
# Agent 1 travaille dans ../projet-feature-auth
# Agent 2 travaille dans ../projet-feature-api
# Aucun conflit de fichier possible
# Fusionner les resultats quand les agents terminent
git merge feature/auth
git merge feature/api
# Nettoyer les worktrees
git worktree remove ../projet-feature-auth
git worktree remove ../projet-feature-apiSur les projets avec 3 à 5 agents en parallèle, cette approche élimine les conflits de fichiers. Chaque agent a son espace de travail complet, son propre contexte de fichiers, et les résultats se fusionnent proprement via git merge.
mcp cli experimental mode : réduire le poids du contexte
Chaque serveur MCP connecté à Claude Code injecte ses schémas d'outils dans la fenêtre de contexte. Avec plusieurs MCPs, ces schémas consomment une quantité significative de tokens avant même que l'agent ne commence à travailler.
Le mode MCP CLI expérimental supprime ces schémas de la fenêtre de contexte. Les outils MCP sont chargés à la demande, uniquement quand l'agent en a besoin. Le gain est double : moins de tokens consommés et une fenêtre de contexte dédiée au code plutôt qu'aux définitions d'outils. (Note : cette fonctionnalité a depuis évolué vers le MCP Tool Search officiel, qui s'active automatiquement quand les MCPs occupent plus de 10% du contexte.)
Vérifier le travail de l'agent : tests adversariaux et browser testing
Un agent ne peut pas auditer son propre code de manière fiable. L'équipe HumanoAI sépare production et validation avec trois mécanismes complémentaires.
agents adversariaux en parallèle
Le principe est emprunté à la recherche scientifique : séparer la production de l'information de sa validation. Un premier agent effectue la recherche et produit un draft. Un second agent, indépendant, reçoit ce draft et le vérifie systématiquement.
Les deux agents communiquent entre eux. L'agent vérificateur peut poser des questions, demander des sources, contester des affirmations. Ce dialogue produit un résultat de qualité supérieure à ce qu'un seul agent pourrait générer, même avec plus de contexte.
En pratique, cette technique fonctionne particulièrement bien pour :
- La revue de code : un agent écrit, un autre review
- La documentation : un agent rédige, un autre vérifie l'exactitude
- L'architecture : un agent propose, un autre cherche les failles
browser testing : trois approches comparées
Pour les applications web, la vérification ne peut pas se limiter au code. Il faut tester le rendu. L'équipe HumanoAI a évalué trois outils de test navigateur pour Claude Code :
| outil | méthode | tokens consommés | cas d'usage |
|---|---|---|---|
| Claude Chrome Extension | Accès direct au DOM et à la console | Elevé (DOM complet) | Debug interactif, inspection détaillée |
| Puppeteer MCP | Navigateur headless isolé | Moyen | Tests automatisés, captures d'écran |
| Vercel Agent Browser | Arbre d'accessibilité | -93% de tokens (vs DOM complet) | Validation rapide, tests légers |
La différence de consommation de tokens est frappante. Le Vercel Agent Browser utilise l'arbre d'accessibilité plutôt que le DOM complet. Résultat : une réduction de 93% des tokens par rapport à Playwright MCP. Pour les validations fréquentes, c'est un choix pragmatique qui préserve la fenêtre de contexte pour le travail réel.
Prédire les défaillances avant qu'elles n'arrivent
La dernière technique est peut-être la plus surprenante. Après que le code a passé les tests unitaires, les tests d'intégration et la revue adversariale, l'équipe demande à Claude de prédire où l'application pourrait échouer.
Le prompt est direct : "Analyse cette base de code et identifie les scénarios de défaillance que les tests actuels ne couvrent pas." L'agent examine le code avec une perspective différente de celle de l'implémentation. Il cherche les cas limites, les interactions non testées entre composants, les hypothèses implicites dans le code.
Le résultat de cette analyse est significatif. L'équipe HumanoAI rapporte que cette technique a identifié 18 problèmes qui avaient passé avec succès toutes les couches de tests précédentes. Ce ne sont pas des bugs critiques en majorité, mais des failles dans la couverture : des cas limites oubliés, des erreurs de gestion d'état, des vulnérabilités dans le traitement des entrées.
limites de l'analyse prédictive
Cette technique ne remplace pas les tests formels. Elle les complète. Les 18 problèmes identifiés par l'équipe HumanoAI sont des pistes à investiguer, pas des bugs confirmés. Chaque problème potentiel doit être validé manuellement avant correction. L'analyse prédictive est un filet de sécurité supplémentaire, pas un remplacement des pratiques de test établies.
4 Techniques à Retenir
Contexte structuré
CLAUDE.md, PRD, architecture.md, feature.json et Context7 MCP forment l'écosystème de contexte. Un agent bien nourri produit du code conforme dès la première passe.
Garde-fous explicites
Les hooks avec exit code 2, le mode strict TypeScript et les user stories définissent les limites. L'agent sait ce qu'il ne doit pas faire autant que ce qu'il doit faire.
Parallélisation isolée
Les git worktrees et le MCP CLI expérimental permettent de lancer plusieurs agents sans conflits et sans gaspillage de tokens. L'accélération est réelle, pas théorique.
Vérification multi-couche
Agents adversariaux, browser testing et analyse prédictive créent trois niveaux de vérification indépendants. La confiance se construit par la redondance.
Appliquez ces techniques à votre équipe
Besoin d'accompagnement pour intégrer Claude Code dans vos workflows DevOps ? Parlons de votre contexte.
Échangeons sur LinkedIn