Claude Code pour l'onboarding d'une base de code : utilisez des prompts Q&R pour cartographier modules, flux clés et risques, puis transformez les notes en un court document d'onboarding.
Lire des fichiers au hasard paraît lent parce que la plupart des bases de code ne sont pas organisées comme une histoire. Vous ouvrez un dossier, voyez dix noms qui semblent importants, cliquez sur l'un d'eux, et vous vous retrouvez dans des helpers, des configs et des cas limites. Après une heure, vous avez beaucoup de détails mais vous ne pouvez toujours pas expliquer comment l'application fonctionne.
Un meilleur objectif pour Claude Code pendant l'onboarding est de construire une carte mentale simple. Cette carte doit répondre à trois questions :
Un onboarding "suffisamment bon" en 1–2 jours n'est pas « Je peux expliquer chaque classe. ». C'est plutôt ceci :
Certaines choses peuvent attendre. Les refactors profonds, la compréhension parfaite de chaque abstraction et la lecture de vieux fichiers quasi abandonnés vous rapportent rarement les gains les plus rapides.
Considérez l'onboarding comme la construction d'une carte, pas la mémorisation des rues. Vos prompts doivent sans cesse vous ramener à : « Où suis-je dans le système, que se passe-t-il ensuite, et qu'est-ce qui pourrait mal tourner ici ? » Une fois que vous avez cela, les détails sont plus faciles à apprendre à la demande.
Avant de commencer à poser des questions, collectez les bases dont vous avez normalement besoin le premier jour. Claude Code fonctionne mieux quand il peut réagir à de vrais fichiers, de vraies configurations et un comportement réel que vous pouvez reproduire.
Commencez par l'accès et un run fonctionnel. Assurez-vous de pouvoir cloner le repo, installer les dépendances et lancer l'app (ou au moins une petite partie) en local. Si la configuration locale est difficile, obtenez l'accès à un environnement staging et à l'endroit où les logs vivent, afin de pouvoir vérifier ce que le code fait réellement.
Ensuite, trouvez les docs « source de vérité ». Cherchez ce que l'équipe met réellement à jour quand les choses changent : un README, une courte note d'architecture, un dossier ADR, un runbook ou une note de déploiement. Même si c'est désordonné, cela donne des noms de modules et de flux, ce qui rend les Q&A beaucoup plus précis.
Décidez de la portée tôt. Beaucoup de repos contiennent plusieurs apps, services et packages partagés. Choisissez des limites comme « seulement l'API et le worker de facturation » ou « seulement l'app web et son flux d'auth. » Une portée claire évite les détours sans fin.
Écrivez les hypothèses que vous ne voulez pas que l'assistant devine. Cela paraît anodin, mais ça évite des modèles mentaux erronés qui vous font perdre des heures plus tard.
Voici une check-list préparatoire simple :
Si quelque chose manque, capturez-le comme une question pour un coéquipier. Ne « contournez » pas le manque de contexte par des suppositions.
Une carte mentale est un petit ensemble de notes qui répondent : quelles sont les parties principales de cette app, comment communiquent-elles entre elles, et où ça peut mal tourner. Bien fait, l'onboarding devient moins une navigation de fichiers et plus la construction d'une image réutilisable.
Commencez par définir vos livrables. Vous voulez une liste de modules pratique, pas parfaite. Pour chaque module, capturez ce qu'il fait, qui en est propriétaire (équipe ou personne si vous le savez) et ses dépendances clés (autres modules, services, bases, APIs externes). Notez aussi les points d'entrée principaux : routes UI, endpoints API, jobs en arrière-plan et tâches planifiées.
Ensuite, choisissez quelques parcours utilisateurs qui comptent. Trois à cinq suffisent. Choisissez des flux qui touchent à l'argent, aux permissions ou aux modifications de données. Exemples : inscription et vérification par email, création d'un plan payant ou achat, action admin qui change l'accès utilisateur, et un flux critique utilisé quotidiennement par la majorité des utilisateurs.
Décidez comment vous allez étiqueter le risque avant de commencer à collecter les notes. Gardez des catégories simples pour pouvoir scanner plus tard. Un ensemble utile : sécurité, intégrité des données, disponibilité et coûts. Quand vous marquez quelque chose comme risqué, ajoutez une phrase expliquant pourquoi, plus ce qui prouverait que c'est sûr (un test, un log, une vérification de permission).
Utilisez un format cohérent pour pouvoir transformer les notes en doc d'onboarding sans tout réécrire :
Exemple : si Checkout appelle Billing qui écrit dans payments et invoices, marquez-le comme intégrité des données et coût. Notez ensuite où les retries ont lieu et ce qui empêche les doubles paiements.
Quand vous rejoignez un nouveau repo, vous voulez une orientation rapide, pas une compréhension parfaite. Ces prompts vous aident à construire une carte mentale en petites étapes sûres.
Commencez par donner à l'assistant l'arborescence du repo (ou un sous-ensemble collé) et demandez une visite. Gardez chaque tour focalisé, puis terminez par une question qui vous dit quoi lire ensuite.
1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
Un exemple concret : si vous cartographiez « l'utilisateur s'inscrit et crée son premier projet », demandez le handler de route API, la validation, l'écriture en DB, et tout job asynchrone qui envoie des emails ou provisionne des ressources. Puis relancez le flow trace pour « l'utilisateur supprime le projet » pour repérer des manques de nettoyage.
Pour garder les réponses actionnables, demandez des artefacts précis, pas seulement des résumés :
Le plus grand gain d'onboarding est de transformer des Q&A éparpillés en notes qu'un autre dev peut réutiliser. Si les notes ne font sens que pour vous, vous referez la même exploration plus tard.
Une structure simple vaut mieux qu'une longue page. Après chaque session d'exploration, enregistrez les réponses dans cinq artefacts compacts (un seul fichier ou doc suffit) : une table des modules, un glossaire, les flux clés, les inconnues et un registre des risques.
Voici un template compact que vous pouvez coller dans vos notes et remplir au fil de l'eau :
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
Gardez les flux courts volontairement. Exemple : 1) l'utilisateur se connecte, 2) le backend crée une session, 3) le client charge le dashboard, 4) l'API récupère les données, 5) l'UI rend et gère les erreurs. Si vous ne pouvez pas faire tenir un flux en cinq étapes, séparez-le (login vs chargement du dashboard).
Quand vous utilisez Claude Code, ajoutez une ligne à chaque réponse : « Comment testerais-je ça ? » Cette ligne transforme des notes passives en checklist à exécuter plus tard, surtout quand les inconnues et les risques se recoupent.
Si vous construisez sur une plateforme vibe-coding comme Koder.ai, ce type de prise de notes aide aussi à repérer où des changements générés pourraient avoir des effets secondaires. Les modules avec beaucoup de points de contact ont tendance à attirer les changements.
Le risque dans une base de code n'est rarement aléatoire. Il se concentre là où l'app décide qui vous êtes, modifie des données, parle à d'autres systèmes, ou exécute du travail en arrière-plan. Vous pouvez trouver la plupart de ces zones avec des questions ciblées et quelques recherches focalisées.
Commencez par l'identité. Demandez où l'authentification se passe (login, session, tokens) et où les décisions d'autorisation vivent (vérifications de rôle, feature flags, règles de propriété). Un piège courant est d'avoir des vérifications dispersées entre UI, handlers API et requêtes DB sans source de vérité unique.
Ensuite, mappez les chemins d'écriture. Trouvez les endpoints ou fonctions qui créent, mettent à jour ou suppriment des enregistrements, plus les migrations qui modifient les données au fil du temps. Incluez aussi les jobs en arrière-plan. Beaucoup de bugs mystérieux viennent de workers asynchrones qui écrivent des valeurs inattendues bien après la fin d'une requête.
Prompts qui font remonter les risques rapidement :
Vérifiez ensuite la configuration et la gestion des secrets. Cherchez les variables d'environnement, les fichiers de config runtime et les fallbacks par défaut. Les valeurs par défaut sont utiles, mais risquées quand elles masquent des mauvaises configurations (par exemple, utiliser une clé dev en production parce qu'une valeur manquait).
Un exemple rapide : dans un backend Go avec PostgreSQL, vous pouvez trouver un job "send email" qui retry en cas d'échec. S'il retry sans clé d'idempotence, les utilisateurs peuvent recevoir des emails en double. Si les échecs ne font qu'enregistrer un warning et qu'aucune alerte n'existe, cela casse silencieusement. C'est une zone à risque à documenter et tester tôt.
Utilisez un flux réel pour construire votre premier fil conducteur dans le système. Le login est un bon départ parce qu'il touche au routage, à la validation, aux sessions ou tokens, et aux lectures en base.
Scénario : une app React appelle une API Go, et l'API lit et écrit dans PostgreSQL. Votre objectif n'est pas de comprendre chaque fichier. C'est de répondre : « Quand un utilisateur clique sur Se connecter, quel code s'exécute ensuite, quelles données bougent, et qu'est-ce qui peut échouer ? » Voilà comment l'onboarding reste concret.
Commencez par l'UI et avancez, un saut à la fois. Demandez des noms de fichiers, des fonctions, et les formes des requêtes/réponses.
Après chaque réponse, écrivez une courte ligne dans votre carte mentale : "UI component -> API endpoint -> handler -> service -> DB query -> response." Incluez les noms, pas juste "une fonction".
Une fois le chemin identifié, vérifiez-le avec un petit test. Vous vérifiez que le chemin de code que vous avez cartographié est bien celui utilisé par l'app.
Surveillez les requêtes réseau dans les outils dev du navigateur (chemin, code de statut, corps de réponse). Ajoutez ou activez des logs serveur autour du handler et de l'appel DB (ID de requête si disponible). Interrogez PostgreSQL pour vérifier les changements attendus (pour le login, peut-être last_login_at, sessions, ou lignes d'audit). Forcez une erreur (mauvais mot de passe, champ manquant) et notez où le message d'erreur est créé et où il est affiché. Enregistrez les réponses attendues pour succès et échec (codes de statut et champs clés), afin que le prochain développeur puisse faire une vérification rapide.
Ce flux unique expose souvent les frontières de propriété : ce que l'UI fait confiance, ce que l'API impose, et où les erreurs disparaissent ou sont gérées deux fois.
Une fois que vous avez une carte mentale décente, figez-la dans une note de 1–2 pages. Le but n'est pas d'être complet. C'est d'aider le prochain développeur à répondre : c'est quoi cette app, où regarder en premier, et qu'est-ce qui casse le plus souvent ?
Si vous utilisez Claude Code, traitez ce doc comme le résultat de votre Q&A : clair, concret et facile à survoler.
Gardez le doc prévisible pour que les gens trouvent vite les infos. Une bonne structure :
Pour « Où les choses vivent », incluez des pointers comme "Auth commence dans X, la logique de session dans Y, les routes UI dans Z." Évitez de dumper un arbre complet. Ne gardez que ce que les gens toucheront.
Pour « Flux clés », écrivez 4–7 étapes par flux : déclencheur, controller ou handler, module central, appel base de données, et effet externe (email envoyé, état mis à jour, job en file). Ajoutez les noms de fichiers à chaque étape.
Pour les « Zones risquées », nommez le mode de défaillance et le check de sécurité le plus rapide (un test spécifique, un run smoke, ou un log à surveiller).
Terminez par une petite liste de premières tâches afin que quelqu'un puisse contribuer en sécurité :
Le moyen le plus rapide de gaspiller un assistant est de demander "une explication complète de tout le repo." Vous obtenez un long résumé qui paraît confiant mais reste vague. Au lieu de ça, choisissez une petite portion qui compte (un module + un flux utilisateur), puis élargissez.
Deuxième erreur fréquente : ne pas nommer les parcours importants. Si vous ne dites pas "checkout", "login" ou "édition admin", les réponses dérivent en discours d'architecture générique. Commencez chaque session avec un objectif concret : « Aidez-moi à comprendre le flux d'inscription de bout en bout, validation incluse, états d'erreur et où sont stockées les données. »
Un autre piège est de laisser l'assistant deviner. Quand quelque chose n'est pas clair, obligez-le à marquer l'incertitude. Demandez-lui de séparer ce qu'il peut prouver dans le code de ce qu'il infère.
Utilisez une règle simple dans vos notes : chaque affirmation doit être taguée parmi :
Les notes se dégradent aussi quand elles sont collectées sans structure. Un tas d'extraits de chat est difficile à transformer en carte mentale. Gardez un template cohérent : modules impliqués, point d'entrée, fonctions et fichiers clés, données touchées, effets secondaires, chemins d'erreur, et tests à exécuter.
Même avec Claude Code, considérez la sortie comme un brouillon. Vérifiez les flux clés dans l'app en fonctionnement, surtout les parties qui peuvent casser la production : auth, paiements, permissions, jobs en arrière-plan et migrations.
Un exemple pratique : si l'assistant dit "le reset de mot de passe envoie un email via X", confirmez-le en déclenchant un reset en dev et en vérifiant les logs ou le bac à sable email. Cette vérification évite de vous embarquer dans une histoire incorrecte.
Vous n'avez pas besoin de mémoriser le repo. Il faut avoir assez de confiance pour faire une modification sûre, déboguer un vrai problème et expliquer le système au suivant.
Avant de vous déclarer onboarded, assurez-vous de pouvoir répondre à ces questions sans deviner :
Si un point manque, faites un petit passage ciblé plutôt qu'une recherche large. Choisissez un flux, suivez-le jusqu'à la frontière de la base de données, puis arrêtez-vous et écrivez ce que vous avez appris. Quand quelque chose est flou, capturez-le comme une question, pas comme un paragraphe. "Où est créé le rôle X ?" est plus utile que "l'auth est confuse."
Un bon test final : imaginez qu'on vous demande d'ajouter une petite fonctionnalité derrière un flag. Si vous pouvez nommer les fichiers à toucher, les tests à lancer et les modes de défaillance à surveiller, vous êtes suffisamment onboardé pour contribuer de manière responsable.
Une carte mentale n'est utile que tant qu'elle reflète la réalité. Traitez-la comme un artefact vivant, pas comme une tâche ponctuelle. La façon la plus simple de la garder honnête est de la mettre à jour juste après les changements qui affectent le comportement.
Une routine légère vaut mieux que de grosses réécritures. Liez les mises à jour au travail que vous faites déjà :
Gardez le doc d'onboarding proche du code et versionnez-le avec la même discipline que le code. Les petits diffs sont lus. Les grosses réécritures sont souvent ignorées.
Quand les déploiements sont risqués, écrivez ce qui aiderait le prochain à récupérer vite : ce qui a changé, quoi surveiller, et comment revenir en arrière. Si votre plateforme prend en charge snapshots et rollback, ajoutez le nom du snapshot, la raison, et ce que signifie un état « bon » après la correction.
Si vous développez avec Koder.ai (koder.ai), le mode planning peut vous aider à rédiger une carte de modules et une note d'onboarding cohérente à partir de vos Q&A, et l'export du code source donne aux relecteurs un moyen clair de valider le résultat.
Enfin, définissez une check-list de passation que le prochain développeur peut suivre sans deviner :
Bien fait, Claude Code pour l'onboarding de base de code devient une habitude : chaque changement laisse derrière lui une carte plus claire pour la personne suivante.
Visez une carte mentale utilisable, pas une compréhension totale.
Un bon résultat en 1–2 jours :
Fournissez des éléments concrets pour qu'il pointe vers du vrai code au lieu de deviner :
Choisissez une tranche étroite avec des limites claires.
Une portée par défaut utile :
Notez explicitement ce qui est hors scope (autres services, modules legacy, fonctionnalités peu utilisées) pour éviter les digressions de l'assistant.
Commencez par les déclencheurs connus, puis avancez pas à pas :
Demandez des chemins de fichiers et noms de fonctions dans l'ordre, et terminez par : « Comment testerais-je ça rapidement ? »
Cherchez où le système prend des décisions ou change l'état :
Utilisez un système d'étiquetage simple et joignez une étape de vérification.
Exemple :
Contraignez l'assistant à séparer preuve et inférence.
Demandez-lui d'étiqueter chaque affirmation comme :
Quand quelque chose est inconnu, transformez-le en question pour un coéquipier (« Où est défini le rôle X ? ») au lieu de combler le vide par une supposition.
Gardez une note légère avec cinq sections :
Faites une vérification rapide et réelle :
Cela valide que le chemin que vous avez cartographié est bien celui utilisé par l'app.
Utilisez les fonctionnalités de plateforme pour réduire le blast radius et garder les changements relisables.
Bonnes pratiques :
Ensuite, demandez : « Qu'est-ce qui casse silencieusement, et comment le détecterions-nous ? »
Restez concis pour pouvoir mettre à jour au fur et à mesure que vous apprenez.
Ajoutez une ligne à chaque flux : « Comment testerais-je ça ? » pour en faire une checklist.
Cela fonctionne bien pour des tâches d'onboarding comme « ajouter un garde-fou », « renforcer une validation » ou « améliorer un chemin d'erreur ».