Le guide Claude Code qui a tout changé pour moi

Un gagnant de hackathon Anthropic a rendu public son guide de configuration Claude Code hier, et je l’ai appliqué intégralement dans la foulée. J’y ai passé la journée entière, et la différence est bien réelle.

Le guide vient d’affaan (@affaanmustafa), qui utilise Claude Code au quotidien depuis 10 mois. En parcourant sa configuration, ma première réaction a été : « Mais qu’est-ce que je faisais depuis tout ce temps ? »

Le guide est disponible sous forme de dépôt GitHub, et son message central est limpide : pas plus, mais exactement ce qu’il faut.

La fenêtre de contexte de 200K est un mythe - le vrai chiffre, c’est 70K

La fenêtre de contexte de 200K tokens de Claude Code est un maximum théorique. Si vous chargez trop de serveurs MCP et de plugins, votre contexte utilisable tombe aux alentours de 70K.

L’approche d’affaan :

1. Configurer 14 serveurs MCP, mais n’en activer que 5 à 6 par projet.
2. Maintenir moins de 80 outils activés simultanément.

Sa configuration réelle inclut GitHub, Supabase, Vercel, Railway, la suite Cloudflare, ClickHouse et d’autres - 14 serveurs au total. Mais il désactive explicitement ceux qu’il n’utilise pas via disabledMcpServers. Depuis que j’ai adopté cette approche, la qualité des réponses s’est nettement améliorée.

Skills vs Hooks vs Sous-agents - tout repose sur la séparation des rôles

Ces trois concepts prêtent à confusion au départ, mais la distinction est fondamentale.

• Skills : Résident dans ~/.claude/skills. Lancent un workflow complet avec une seule commande comme /refactor-clean.
• Hooks : Automatisation événementielle. Formatage automatique avec Prettier après modification d’un fichier .ts, alerte sur les console.log, etc. Le plugin hookify permet de générer des hooks par simple conversation.
• Sous-agents : Résident dans ~/.claude/agents. Des rôles dédiés - planner, architect, tdd-guide, security-reviewer - qui prennent en charge les tâches déléguées.

affaan place ses hooks à trois points d’exécution - PreToolUse, PostToolUse et Stop - pour automatiser le formatage, la vérification de types et les audits de sécurité. Ce pattern a d’ailleurs été validé par Boris Cherny.

mgrep et les Git Worktrees changent la donne

Les conseils pratiques les plus marquants du guide :

mgrep

Plus précis que ripgrep, avec la recherche web intégrée. Une seule commande comme /mgrep 'function handleSubmit' parcourt simultanément les fichiers locaux et le web.

Git Worktrees

Quand on travaille sur plusieurs fonctionnalités en parallèle, on crée des checkouts indépendants et on lance Claude Code dans chacun. On peut aussi utiliser /fork pour embrayer une conversation. Le débat reste ouvert entre worktrees et clones de dépôts - les deux ont leurs avantages selon le workflow.

Zed Editor

Construit en Rust, donc il reste léger. Le panneau Agent suit les modifications de fichiers par Claude en temps réel, et CMD+Shift+R exécute des commandes personnalisées instantanément.

Des règles structurées pour la cohérence

Modularisez ~/.claude/rules par domaine de préoccupation :

• security.md - Aucun secret en dur dans le code
• coding-style.md - Immutabilité, conventions de structure de fichiers
• testing.md - Workflow TDD, couverture minimale de 80 %
• git-workflow.md - Format des messages de commit
• performance.md - Critères de sélection des modèles

Ajoutez des règles comme « ne jamais committer de console.log » ici, puis faites-les respecter avec un hook Stop qui audite vos modifications. Les erreurs disparaissent quand l’automatisation les intercepte avant qu’elles ne partent en production.

Les principes fondamentaux

affaan résume sa philosophie en cinq principes :

• Traiter la configuration comme du fine-tuning, pas comme de l’architecture. De petits ajustements ciblés valent mieux que de grands remaniements.
• La fenêtre de contexte est précieuse. Désactivez tout ce que vous n’utilisez pas activement.
• Exploiter l’exécution parallèle. Utilisez /fork et les worktrees pour faire tourner des agents en simultané.
• Automatiser le travail répétitif. Les hooks éliminent les étapes manuelles qui vous ralentissent.
• Limiter le périmètre des sous-agents. Donnez à chaque agent une responsabilité étroite et bien définie.

La surcharge de configuration est contre-productive. Ne garder actifs que les outils dont on a réellement besoin, c’est ça la vraie productivité. Retrancher est la partie la plus difficile pour la plupart des gens, et ce guide le rappelle avec force.

Une note personnelle : pour l’automatisation du navigateur, j’ai constaté que l’agent-browser de Vercel est nettement plus stable que Playwright et les outils similaires mentionnés dans le guide original. La vitesse et l’éventail de tâches qu’il gère sont d’un tout autre niveau.

La configuration complète est disponible sur le dépôt GitHub d’affaan. Plutôt que de la copier telle quelle, prenez le temps de comprendre le raisonnement derrière chaque choix et adaptez-le à votre propre workflow. C’est là que réside la vraie valeur.