Chapitre 6.1 — Onboarder l’IA sur un repo

⏱️ TL;DR — Face à un repo inconnu, le mauvais réflexe est de faire tout lire à l’agent (contexte noyé, cher, inutile). Le bon réflexe : lui faire cartographier — comprendre la structure, les points d’entrée, les conventions apparentes — avant de toucher à quoi que ce soit. Des outils dédiés existent : l’agent Explore (recherche large en lecture seule qui renvoie une conclusion, pas des dumps), la skill zoom-out (carte de haut niveau), et /init pour amorcer un CLAUDE.md. On comprend puis on agit.

🎯 Objectifs

• Éviter la lecture brute d’un repo (anti-pattern coûteux).
• Faire cartographier le codebase par l’agent.
• Utiliser Explore, zoom-out, /init pour un onboarding rapide.
• Produire une compréhension exploitable avant d’agir.

Ne fais pas « lis tout le projet »

Le réflexe naïf : « lis tout le repo et dis-moi ce que ça fait ». Sur un projet réel, c’est :

• coûteux : des milliers de lignes entassées dans le contexte (1.3), qui le saturent avant même de commencer ;
• inefficace : l’agent noie l’essentiel (l’architecture) sous les détails (chaque util) ;
• inutile : tu n’as pas besoin qu’il connaisse tout, mais qu’il sache où sont les choses et comment c’est organisé.

Onboarder, ce n’est pas ingérer le code, c’est en construire une carte.

Cartographier : les bonnes questions

Demande à l’agent une carte, pas un résumé exhaustif :

« Cartographie ce repo pour moi, sans le lire ligne à ligne : (1) la structure des dossiers et ce que fait chaque zone, (2) les points d’entrée (routes, main, config), (3) la stack et les libs clés, (4) les conventions apparentes (nommage, organisation, patterns de data), (5) où je regarderais pour ajouter une feature de type X. Reste haut niveau, cite les fichiers plutôt que de les coller. »

Tu obtiens une compréhension structurée et bon marché — de quoi décider où intervenir, sans avoir tout chargé.

Les outils d’onboarding

Explore — la recherche large en lecture seule

L’agent Explore est fait pour ça : il balaie le repo (fichiers, conventions de nommage) et renvoie une conclusion, pas le contenu brut. Idéal pour « où est géré X ? », « comment sont organisés les composants ? » — il lit des extraits, localise, et te rend l’essentiel sans polluer ta session principale (c’est un subagent, contexte isolé — Partie 8).

« Utilise Explore pour trouver où l’authentification est gérée et comment les rôles sont vérifiés. Renvoie les fichiers clés et le flux, pas le code entier. »

zoom-out — la carte de haut niveau

La skill zoom-out demande explicitement à l’agent de prendre de la hauteur : une carte des modules pertinents, leurs responsabilités, leurs relations. Parfaite au tout début d’une reprise, quand tu veux le paysage avant les détails.

/init — amorcer la mémoire

Sur un repo sans CLAUDE.md, /init analyse le projet et génère une première base (stack, structure, scripts). Comme en 3.2, c’est un point de départ à tailler — mais sur un repo existant, il capture d’un coup beaucoup de contexte que tu affineras (6.2).

💡 Réflexe d’architecte — Onboarde en couches, du général au précis : d’abord le paysage (zoom-out), puis les zones qui t’intéressent (Explore), puis les fichiers exacts que tu vas toucher. Tu ne charges du détail que là où tu vas agir. C’est la gestion du contexte (5.2) appliquée à la découverte.

⚠️ Piège — Sauter l’onboarding et demander direct une modif (« ajoute la pagination ») sur un repo que l’agent ne connaît pas. Il va explorer dans l’urgence, mal, et risque de dupliquer un util existant ou d’ignorer une convention. Cinq minutes de cartographie évitent une modif à côté de la plaque.

De la carte à l’action

Une fois la carte en tête, tu agis avec la boucle habituelle (P5), mais tes prompts sont maintenant ancrables : tu sais quel fichier citer comme modèle, où placer le neuf, quelle convention suivre. L’onboarding a transformé un repo opaque en terrain balisé.

🧭 Sur TaskFlow — Imagine reprendre TaskFlow après trois mois (ou qu’un collègue le fasse). Grâce au CLAUDE.md versionné (P3), l’onboarding est déjà à moitié fait : l’agent recharge les conventions au démarrage. zoom-out complète avec l’état actuel du code. C’est le bénéfice composé d’avoir écrit la mémoire : la reprise est rapide *parce qu’*on a investi au kickoff.

✏️ Exercices

Exercice 1 — Cartographie, pas lecture. Prends un repo que tu connais mal. Demande la carte (les 5 questions ci-dessus). Vérifie qu’il cite des fichiers plutôt que d’en coller, et que tu sais maintenant où ajouter une feature.

Exercice 2 — Explore ciblé. Sur le même repo, lance un Explore sur une question précise (« où et comment les erreurs sont gérées ? »). Compare le coût/contexte avec « lis les fichiers d’erreur et montre-les ».

🧠 Quiz de révision

Chapitre suivant : Respecter les conventions existantes — faire adopter à l’agent des règles souvent non écrites.