Guide Claude Code pour Infrastructure Multi-Agents¶

Version: 1.0.0 Date: 2026-01-14 Statut: Guide pratique

Introduction¶

Ce guide compile les meilleures pratiques d'utilisation de Claude Code dans un contexte d'infrastructure multi-agents. Il s'adresse aux équipes qui souhaitent construire des systèmes robustes et maintenables avec Claude Code comme outil de développement principal.

1. Planification avant exécution¶

Principe fondamental¶

La planification systématique produit de meilleurs résultats que l'exécution immédiate. Avant de démarrer une implémentation, il est essentiel de structurer la demande.

Plan Mode¶

Claude Code propose un mode planification (EnterPlanMode) qui permet de : - Explorer le codebase - Concevoir l'approche technique - Obtenir une validation avant implémentation

Pratique recommandée : Utiliser le plan mode pour toute tâche non triviale. "Cela prend 5 minutes mais économise des heures de debugging."

Architecture explicite¶

Comparer : - ❌ "Build me an auth system" - ✅ "Build email/password authentication using the existing User model, store sessions in Redis with 24-hour expiry, and add middleware that protects all routes under /api/protected"

Plus l'architecture est explicite, moins il y a d'ambiguïté dans l'implémentation.

2. Configuration du projet : .clinerules¶

Rôle du fichier¶

Claude Code lit automatiquement le fichier .clinerules (ou les règles configurées dans les settings) au démarrage de chaque session. Ce fichier définit les contraintes et conventions du projet.

Bonnes pratiques¶

Garder court : Claude peut suivre environ 150-200 instructions simultanément, et le system prompt en utilise déjà ~50. Chaque instruction ajoutée entre en compétition pour l'attention.

Être spécifique au projet : Ne pas expliquer ce qu'est un dossier components/. Claude le sait. Documenter les spécificités :

# Commandes importantes
- Tests : `npm test -- --coverage`
- Build production : `npm run build:prod`
- Migration DB : `npm run migrate:up`

# Conventions crypto
- Utiliser SHA3-256 pour tous les hash probatoires (FIPS 202)
- AES-256-GCM obligatoire pour chiffrement (NIST SP 800-38D)

Expliquer le pourquoi : - ❌ "Use TypeScript strict mode" - ✅ "Use TypeScript strict mode because we've had production bugs from implicit any types"

Le contexte aide Claude à faire des choix éclairés dans des situations non anticipées.

Maintenir à jour : Chaque fois que vous corrigez Claude deux fois sur le même point, c'est un signal qu'il faut l'ajouter au fichier.

Format recommandé¶

"Un bon fichier de configuration ressemble à des notes que vous laisseriez pour vous-même si vous saviez que vous auriez une amnésie demain."

3. Gestion du contexte¶

Fenêtre de contexte¶

Claude Code offre une fenêtre de contexte de 200 000 tokens (Opus 4.5, Sonnet 4.5).

Dégradation de la qualité¶

"À partir d'une certaine utilisation du contexte, la qualité de sortie commence à se dégrader, même si le modèle n'est pas à 100% de capacité." Ce seuil varie mais se situe généralement entre 45% et 60%.

Stratégies de gestion¶

Scope des conversations : Une conversation = une fonctionnalité ou tâche. Ne pas utiliser la même conversation pour construire le système d'authentification ET refactorer la base de données.

Mémoire externe : Pour les tâches complexes, faire écrire les plans et progrès dans des fichiers réels (SCRATCHPAD.md, plan.md). Ces fichiers persistent entre les sessions et Claude peut les relire pour reprendre le contexte.

Reset ciblé : Quand le contexte devient problématique : 1. Copier les informations critiques du terminal 2. Utiliser /clear pour vider le contexte 3. Redonner uniquement les informations essentielles

Reconnaître les signes : Si une conversation part en vrille ou accumule du contexte non pertinent, /clear et recommencer est souvent plus efficace que d'essayer de corriger.

Modèle mental : Claude est stateless. Chaque conversation démarre avec uniquement ce que vous lui donnez explicitement.

4. Prompting efficace¶

Spécificité¶

Être explicite sur ce qui est attendu : - ❌ "Build an auth system" - ✅ "Build email/password authentication using this existing User model, store sessions in Redis, and add middleware that protects routes under /api/protected"

Contraintes négatives¶

Claude a des tendances. "Claude 4.5 aime particulièrement sur-architecturer : fichiers supplémentaires, abstractions non demandées, flexibilité non requise."

Si vous voulez quelque chose de minimal : "Keep this simple. Don't add abstractions I didn't ask for. One file if possible."

"Toujours vérifier ce que Claude produit pour éviter d'accumuler de la dette technique, surtout sur des tâches simples."

Contexte du pourquoi¶

Donner le contexte des contraintes change l'approche de Claude : - "We need this to be fast because it runs on every request" - "This is a prototype we'll throw away"

Principe fondamental¶

"La qualité de la sortie dépend de la qualité de l'entrée. Si la sortie est mauvaise avec un bon modèle, c'est que l'entrée était insuffisante."

5. Choix du modèle¶

Sonnet vs Opus¶

Sonnet : Plus rapide et moins coûteux. Excellence pour les tâches d'exécution où le chemin est clair : - Écrire du boilerplate - Refactoring basé sur un plan précis - Implémenter des fonctionnalités avec décisions architecturales déjà prises

Opus : Plus lent et plus coûteux. Meilleur pour : - Raisonnement complexe - Planification - Tâches nécessitant une réflexion profonde sur les trade-offs

Workflow hybride¶

Un pattern efficace : Utiliser Opus pour planifier et prendre les décisions architecturales, puis passer à Sonnet pour l'implémentation. Le fichier .clinerules garantit que les deux modèles opèrent sous les mêmes contraintes.

6. Skills : Enseigner des workflows spécifiques¶

Concept¶

Une skill est un fichier markdown qui enseigne à Claude comment faire quelque chose de spécifique à votre travail. Quand vous demandez quelque chose qui correspond au but d'une skill, Claude l'applique automatiquement.

Structure¶

Emplacement : - Utilisateur : ~/.claude/skills/skill-name/SKILL.md - Projet : .claude/skills/skill-name/SKILL.md

Format :

---
name: commit-messages
description: Generate commit messages following our team's conventions. Use when creating commits or when the user asks for help with commit messages.
---

# Commit Message Format

All commits follow conventional commits:
- feat: new feature
- fix: bug fix
- refactor: code change that neither fixes nor adds
- docs: documentation only
- test: adding or updating tests

Format: `type(scope): description`
Example: `feat(auth): add password reset flow`

Keep the description under 50 characters.

Principe architectural : Progressive Disclosure¶

Claude pré-charge uniquement le nom et la description de chaque skill installée (~100 tokens chacune). Les instructions complètes ne se chargent que quand Claude détermine que la skill est pertinente.

Conséquence : Vous pouvez avoir des dizaines de skills disponibles sans surcharger le contexte.

Fichiers de support¶

Vous pouvez ajouter des fichiers de référence dans le dossier de la skill. Claude ne les lira que si nécessaire.

Exemples d'usage¶

Les skills ne sont pas limitées au code : - Patterns de requêtes DB spécifiques au schéma - Formats de documentation API de l'entreprise - Templates de notes de réunion - Workflows personnels (planification de repas, réservations voyage)

Vérification¶

Pour voir les skills chargées : "What skills do you have available?" ou Settings → Capabilities → Skills

7. Subagents : Traitement parallèle avec contexte isolé¶

Concept¶

Un subagent est une instance Claude séparée avec : - Sa propre fenêtre de contexte (200K tokens) - Son propre system prompt - Ses propres permissions d'outils

Quand Claude délègue à un subagent, celui-ci opère indépendamment et retourne un résumé à la conversation principale.

Bénéfice principal¶

Le contexte principal reste propre. Les tâches complexes de recherche ou d'implémentation sont déléguées à un contexte frais, puis seuls les résultats pertinents remontent.

Subagents built-in¶

Explore : Agent rapide en lecture seule pour chercher et analyser le codebase. Claude délègue ici quand il doit comprendre le code sans faire de modifications. Peut spécifier le niveau de profondeur : quick, medium, very thorough.

Plan : Agent de recherche utilisé pendant le plan mode pour rassembler du contexte avant de présenter un plan. Investigue le codebase et retourne des résultats pour que Claude puisse prendre des décisions architecturales éclairées.

General-purpose : Agent capable pour des tâches complexes multi-étapes nécessitant exploration et action. Claude délègue ici quand la tâche requiert plusieurs étapes dépendantes ou un raisonnement complexe.

Créer des subagents personnalisés¶

Commande : /agents dans Claude Code pour voir tous les subagents disponibles et en créer de nouveaux.

Emplacement : - Utilisateur : ~/.claude/agents/agent-name.md - Projet : .claude/agents/agent-name.md

Structure :

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Invoke when checking for auth issues, injection risks, or data exposure.
tools: Read, Grep, Glob
---

You are a security-focused code reviewer. When analyzing code:

1. Check for authentication and authorization gaps
2. Look for injection vulnerabilities (SQL, command, XSS)
3. Identify sensitive data exposure risks
4. Flag insecure dependencies

Provide specific file and line references for each finding.
Categorize by severity: critical, high, medium, low.

Contrôle des permissions : Le champ tools définit ce que le subagent peut faire : - Lecture seule : Read, Grep, Glob - Implémentation : Write, Edit, Bash

Communication entre subagents¶

Important : Les subagents ne partagent pas de contexte directement. La communication suit le pattern délégation/retour :

L'agent principal identifie une tâche à déléguer
L'agent principal invoque le subagent avec un prompt spécifique
Le subagent s'exécute dans sa propre fenêtre de contexte
Le subagent retourne un résumé des résultats à l'agent principal
L'agent principal incorpore le résumé et continue

Le résumé est la clé : Un subagent bien conçu ne retourne pas tout son contexte. C'est pourquoi les descriptions et system prompts des subagents doivent être explicites sur le format de sortie.

Chaînage de subagents¶

Pour les workflows complexes, l'agent principal peut orchestrer :

Main Agent
 |── Délègue recherche à Explore subagent
 │   └── Retourne: "Found 3 relevant files: auth.py, middleware.py, routes.py"
 |── Délègue implémentation à custom implementer subagent
 │   └── Retourne: "Added password reset endpoint, updated 2 files"
 └── Délègue tests à custom test-runner subagent
     └── Retourne: "All 12 tests passing, coverage at 94%"

Chaque subagent obtient un contexte frais pour sa tâche spécifique. L'agent principal ne garde que les résumés, pas l'historique complet d'exploration. Cela évite la pollution du contexte.

Contrainte : Les subagents ne peuvent pas spawner d'autres subagents. Cela prévient l'imbrication infinie et garde l'architecture prévisible.

Patterns pratiques¶

Large refactoring : L'agent principal identifie tous les fichiers nécessitant des changements, puis lance un subagent par groupe logique. Chaque subagent gère son périmètre et retourne un résumé. L'agent principal n'a jamais besoin de garder le contexte complet de tous les fichiers simultanément.

Pipeline de code review : Créer trois subagents (style-checker, security-scanner, test-coverage), les exécuter en parallèle sur une PR. Chacun retourne ses résultats dans un format cohérent → l'agent principal synthétise en une seule review.

Tâches de recherche : Pour comprendre une partie non familière du codebase, déléguer à Explore avec des questions spécifiques. Il retourne une carte distillée des fichiers et patterns pertinents, gardant le contexte principal focalisé sur le travail d'implémentation.

8. MCP Connectors : Intégration d'outils externes¶

Concept¶

MCP (Model Context Protocol) est une façon standardisée pour les modèles IA d'appeler des outils et sources de données externes via une interface unifiée.

Au lieu de naviguer entre GitHub, Slack, Gmail, Drive, etc., Claude peut "parler" à tous ces services via l'interface Claude Code grâce à un serveur MCP.

Configuration¶

Ligne de commande :

# HTTP transport (recommandé pour serveurs distants)
claude mcp add --transport http <name> <url>

# Exemple: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Avec authentification
claude mcp add --transport http github https://api.github.com/mcp \
  --header "Authorization: Bearer your-token"

Interface web : Settings → Connectors → Find your server → Configure → Give permissions

Exemples d'usage¶

Implémenter des features depuis les issue trackers : "Add the feature described in JIRA issue ENG-4521"
Requêter les bases de données : "Find users who signed up in the last week from our PostgreSQL database"
Intégrer les designs : "Update our email template based on the new Figma designs"
Automatiser les workflows : "Create Gmail drafts inviting these users to a feedback session"
Résumer des threads Slack : "What did the team decide in #engineering about the API redesign?"

Valeur ajoutée¶

Un workflow qui nécessitait auparavant cinq changements de contexte (vérifier l'issue tracker, regarder le design, lire la discussion Slack, implémenter le code, mettre à jour le ticket) se fait maintenant en une seule session continue.

Connecteurs recommandés¶

GitHub : Gestion des repos, issues, PRs, recherche de code
Slack : Historique des channels, résumés de threads, recherche de messages
Google Drive : Accès aux documents pour référence pendant l'implémentation
PostgreSQL/Databases : Requêtes directes sans quitter Claude
Linear/Jira : Intégration de l'issue tracking

Vérification¶

Commande : /mcp dans Claude Code pour voir vos connexions MCP actuelles.

Sécurité¶

Les serveurs MCP tiers ne sont pas vérifiés par Anthropic. Pour les intégrations sensibles, vérifier le code source du serveur ou utiliser les connecteurs officiels des fournisseurs de service.

9. Déblocage et résolution de problèmes¶

Reconnaître les boucles¶

Parfois Claude boucle : il essaie la même chose, échoue, réessaie, échoue, et continue. Ou il implémente quelque chose de complètement faux avec confiance.

Instinct naturel : Continuer à pousser. Plus d'instructions, plus de corrections, plus de contexte.

Meilleure approche : Changer complètement d'approche.

Stratégies de déblocage¶

Clear la conversation : Le contexte accumulé peut être source de confusion. /clear donne un nouveau départ frais.

Simplifier la tâche : Si Claude lutte avec une tâche complexe, la découper en morceaux plus petits. Faire fonctionner chaque morceau avant de les combiner. "Si Claude lutte avec une tâche complexe, cela signifie que le plan mode était insuffisant."

Montrer au lieu d'expliquer : Si Claude continue de mal comprendre, écrire un exemple minimal vous-même. "Here's what the output should look like. Now apply this pattern to the rest." Claude est excellent pour comprendre les exemples de réussite.

Être créatif : Essayer un angle différent. Parfois la façon dont vous avez formulé le problème ne correspond pas bien à la façon dont Claude pense. Reformuler ("implement this as a state machine" vs "handle these transitions") peut débloquer la situation.

Méta-compétence¶

Reconnaître tôt quand vous êtes dans une boucle. Si vous avez expliqué la même chose trois fois et Claude ne comprend toujours pas, plus d'explications n'aideront pas. Changez quelque chose.

10. Construire des systèmes¶

Au-delà des tâches ponctuelles¶

Les équipes qui tirent le plus de valeur de Claude Code ne l'utilisent pas pour des tâches isolées. Elles construisent des systèmes où Claude est un composant.

Mode headless¶

Claude Code a un flag -p pour le mode headless. Il exécute votre prompt et retourne le résultat sans entrer dans l'interface interactive.

Conséquence : Vous pouvez le scripter, pipe la sortie vers d'autres outils, le chaîner avec des commandes bash, l'intégrer dans des workflows automatisés.

Exemples d'automatisation¶

Les entreprises utilisent cela pour : - Revues automatiques de PR - Réponses automatiques aux tickets support - Mises à jour automatiques de logging et documentation

Tout cela est loggé, auditable, et s'améliore avec le temps en fonction de ce qui fonctionne et ce qui ne fonctionne pas.

Boucle d'amélioration continue¶

Claude fait une erreur
Vous revoyez les logs
Vous améliorez le .clinerules ou les outils
Claude s'améliore la prochaine fois

Cet effet composé est puissant. Après des mois d'itération, les systèmes construits ainsi sont significativement meilleurs qu'au lancement - mêmes modèles, juste mieux configurés.

11. Application à ProbatioVault¶

Skills recommandées¶

crypto-standards : Règles cryptographiques (SHA3-256, AES-256-GCM, Argon2id, HKDF-SHA3-256)

commit-conventions : Format de commits avec co-authoring IA

test-coverage : Exigences 80% branches + tests contractuels TC-*

security-review : Checklist OWASP, zero-knowledge, RGPD

playwright-e2e : Tests E2E Web/PWA avec Page Object Model, multi-browsers, sélecteurs robustes

xcuitest-ios : Tests E2E iOS natifs avec XCUITest, simulateur, biométrie, accessibility identifiers

Subagents recommandés¶

specification-reviewer : Audit des specs (Agent Architect role)

implementation-planner : Création de plans détaillés (Agent Developer role)

acceptability-auditor : Vérification conformité (Agent Architect role)

qa-coordinator : Coordination stratégie qualité, quality gates, décision go/no-go (Agent QA role)

qa-unit-integration : Tests unitaires, intégration, contractuels TC-*, couverture, SonarQube (Agent QA Unit/Integration role)

qa-e2e-ihm : Tests E2E multi-plateformes (Playwright, XCUITest), parcours critiques (Agent QA IHM role)

security-scanner : Analyse sécurité (Agent Adversarial role)

infra-reviewer : Revue Terraform et CI/CD (Agent SRE role)

MCP Connectors prioritaires¶

GitLab : Issues, MRs, pipelines
Vault : Gestion des secrets
PostgreSQL : Accès direct à la base de données de dev
Slack (si utilisé) : Communication d'équipe

Workflow type ProbatioVault¶

Expression de besoin → Main agent (humain + Claude)
Spécification → Agent Architect + skill crypto-standards
Plan d'implémentation → Agent Developer (Opus plan mode)
Validation plan → Agent Architect + subagent security-scanner
Implémentation → Agent Developer (Sonnet) + skill test-coverage
Acceptabilité initiale → Agent Architect (contractuelle) + Agent QA (coordinateur)
Agent QA déclenche → subagent qa-unit-integration (tests techniques)
Agent QA déclenche → subagent qa-e2e-ihm (tests E2E) + skills playwright-e2e/xcuitest-ios
Agent QA consolide → décision go/no-go technique
Corrections → Agent Developer
Revue acceptabilité post-correction → Agent Architect + Agent QA (re-validation)
REX → Agent Developer + write to PD-XX-rex.md

Conclusion¶

La maîtrise de Claude Code pour une infrastructure multi-agents repose sur trois piliers :

Configuration : Skills, subagents, MCP connectors qui encodent vos patterns
Gestion du contexte : Savoir quand déléguer, quand clear, quand persister
Itération : Amélioration continue basée sur les logs et l'expérience

L'investissement initial dans la configuration (skills, agents, connexions) se rentabilise sur chaque tâche suivante. Le système s'améliore avec l'usage.

Annexes¶

Commandes utiles¶

# Voir les skills chargées
/skills

# Voir les agents disponibles
/agents

# Voir les connexions MCP
/mcp

# Clear le contexte
/clear

Fichiers de configuration clés¶

.clinerules                    # Règles du projet
.claude/skills/               # Skills projet
.claude/agents/               # Agents projet
~/.claude/skills/             # Skills utilisateur
~/.claude/agents/             # Agents utilisateur

Structure d'une skill type ProbatioVault¶

---
name: probatio-crypto-standards
description: Apply ProbatioVault cryptographic standards. Use when implementing crypto features or reviewing crypto code.
---

# Cryptographic Standards

## Hash Functions
- **SHA3-256** (FIPS 202) for all probatory hashes
- Never log full hashes (RGPD compliance)

## Encryption
- **AES-256-GCM** (NIST SP 800-38D) for all encryption
- Client-side encryption only (zero-knowledge principle)

## Key Derivation
- **Argon2id** (RFC 9106) for password derivation, 64 MiB minimum
- **HKDF-SHA3-256** for document key derivation

## HSM Operations
- **RSA 4096 bits minimum** for HSM operations
- AWS CloudHSM via VPN site-to-site

## Testing
- Use RFC test vectors for normalized functions
- All crypto services require unit tests
- Coverage ≥ 80% mandatory