Claude Code pour l'onboarding d'une base de code : prompts pour cartographier votre application

Ce que vous cherchez à apprendre (et ce qui peut attendre)

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 :

• Quels sont les modules principaux ?
• Quels sont les flux clés déclenchés par les utilisateurs ?
• Où sont les zones à risque qui peuvent casser la production ou causer des bugs ?

Un onboarding "suffisamment bon" en 1–2 jours n'est pas « Je peux expliquer chaque classe. ». C'est plutôt ceci :

• Vous pouvez nommer les 5–8 modules qui comptent et ce que chacun couvre.
• Vous pouvez tracer 2–3 flux utilisateurs réels de bout en bout (depuis l'entrée UI ou API jusqu'à la base et retour).
• Vous connaissez les principaux risques (paiements, auth, écritures de données, jobs en arrière-plan) et où ils se trouvent.
• Vous pouvez effectuer un petit changement en toute sécurité parce que vous savez quoi tester et qui demander.

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.

Travail préparatoire : obtenir du contexte sans tout balayer

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 :

• Confirmer l'accès au repo, les permissions requises et comment lancer les tests.
• Collecter les notes d'installation d'environnement (env vars, seeds, feature flags) et où voir les logs et métriques.
• Identifier les fichiers de vérité actuels (README, notes d'architecture, ADRs, runbooks).
• Définir ce qui est dans le scope et explicitement hors scope pour cette passe d'onboarding.
• Définir des règles de sécurité : ne jamais coller de secrets, clés API, tokens, données clients privées ou logs de production avec des détails sensibles.

Si quelque chose manque, capturez-le comme une question pour un coéquipier. Ne « contournez » pas le manque de contexte par des suppositions.

La carte mentale : quoi capturer en explorant

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 :

• Modules : but, points d'entrée, dépendances, propriétaire
• Flux clés : déclencheur, étapes, données écrites, points de défaillance
• Données : tables ou collections touchées, champs importants, contraintes
• Risques : catégorie, impact pire scénario, comment monitorer, comment rollback
• Questions ouvertes : ce que vous ignorez encore, qui interroger

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.

Prompts pas-à-pas Q&A pour explorer une base de code

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 :

• Chemins de fichiers et noms de fonctions
• Hypothèses et inconnues clairement identifiées
• Dépendances formulées comme « Si je change X, qu'est-ce qui casse ? »
• Une petite tâche de lecture à faire en 10 minutes

Comment capturer les réponses pour qu'elles restent utiles

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.

Trouver rapidement les zones risquées (sans lire chaque fichier)

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 :

• "List every place that enforces permissions for [resource X]. Which one is the final gate?"
• "Show the full path for writing [table/entity X]: API handler -> service -> DB call. Where are validations?"
• "What external integrations exist (payments, email, webhooks, third-party APIs)? Where are retries and timeouts set?"
• "Where can work run twice (queues, goroutines, cron)? What makes it idempotent?"
• "What can break silently, and how would we notice (logs, metrics, alerts, dashboards)?"

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.

Exemple pas-à-pas : cartographier un flux utilisateur réel

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.

Cartographiez le flux du navigateur à la base

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.

• "Find the React route or page for the login screen. What component renders it, and what action fires on submit?"
• "Where is the API client call made (fetch/axios/etc.)? What exact URL path, method, headers, and body does it send?"
• "On the Go side, where is the handler for that path registered? Show the router setup and the handler function."
• "Inside the handler, where does input validation happen (frontend, backend, both)? What rules exist, and where do errors get formatted?"
• "What database query runs for login? Point to the repository/SQL file, list touched tables/columns, and note any transactions or locks."

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".

Confirmez avec un petit run

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.

Transformer la carte mentale en un court doc d'onboarding

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.

Une structure simple en 1–2 pages

Gardez le doc prévisible pour que les gens trouvent vite les infos. Une bonne structure :

• But : ce que l'app fait, qui l'utilise, et ce que signifie « terminé »
• Résumé d'architecture : services majeurs, magasins de données, et comment les requêtes traversent le système
• Comment lancer : prérequis, la commande unique pour démarrer, et la commande pour lancer les tests
• Où les choses vivent : les dossiers qui importent, plus les 5–10 fichiers qui servent de points d'entrée
• Flux clés et risques : traces courtes des parcours importants, plus ce qu'il faut valider après des changements

Rendez-le actionnable, pas académique

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é :

• Modifier un texte ou une règle de validation sur une écran bien contenu
• Ajouter un petit test unitaire autour d'un helper délicat identifié
• Corriger un bug peu risqué avec un repro clair et un résultat attendu
• Ajouter un garde-fou : meilleur message d'erreur, vérification d'entrée, ou timeout
• Demander qui gère les déploiements en production et qui contacter pour les questions de domaine

Erreurs courantes et comment les éviter

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.

Gardez les inconnues visibles (pour pouvoir les résoudre)

Utilisez une règle simple dans vos notes : chaque affirmation doit être taguée parmi :

• Confirmé dans le code
• Confirmé en faisant tourner l'app
• Hypothèse (à vérifier)
• Inconnu (contexte manquant)

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.

Ne traitez pas les sorties comme des vérités absolues

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.

Check-list rapide avant de dire « je suis onboarded »

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 :

• Pouvez-vous expliquer les cinq zones de code les plus importantes et ce que chacune possède (par exemple : UI, couche API, jobs en arrière-plan, accès aux données, intégrations) ?
• Pouvez-vous parcourir deux parcours utilisateurs à forte valeur de bout en bout, et pointer le premier fichier ou la première fonction qui déclenche chaque parcours ?
• Pouvez-vous montrer où l'authentification est appliquée, et où les rôles ou permissions sont définis et vérifiés ?
• Pouvez-vous nommer les écritures DB les plus risquées (argent, permissions, suppression, transitions d'état), et décrire comment tester chaque changement en toute sécurité ?
• Pouvez-vous donner à un nouveau développeur une courte note d'onboarding lisible en moins de 10 minutes pour qu'il sache par où commencer ?

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.

Prochaines étapes : garder la carte à jour et faciliter les passations

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à :

• Après chaque fonctionnalité : mettez à jour la liste des modules et les flux principaux touchés
• Après chaque incident : ajoutez le déclencheur, l'impact et l'endroit exact de la correction
• Après chaque refactor risqué : notez ce qui a changé et ce qui reste compatible
• Avant une release : revérifiez les 3 zones à risque principales et testez les chemins
• Une fois par mois : supprimez les notes obsolètes et confirmez les propriétaires des modules clés

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 :

• Que lire en premier (2–3 fichiers ou docs) et pourquoi
• Que lancer en local (commandes, env vars, données seed)
• Que vérifier (un happy path et un cas d'échec)
• Où sont les bords tranchants (modules risqués, tests instables, configs délicates)
• Qui contacter pour quoi (propriétaires des flux clés)

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.