Premier jour : 400 000 lignes que vous n'avez pas écrites
Vous arrivez sur un nouveau projet. On vous tend un dépôt Git de 400 000 lignes, écrit par sept personnes dont cinq sont parties. Pas de doc à jour, des noms de fichiers comme helper2_final_v3.php, et une réunion dans deux jours où on vous demandera « alors, tu peux ajouter le paiement Stripe ? ».
Avant, cet onboarding prenait une à deux semaines : ouvrir des fichiers au hasard, suivre des appels de fonction à la main, déranger les anciens. Aujourd'hui, l'IA fait office de collègue senior qui connaît déjà le projet et qui a une patience infinie pour vos questions de débutant.
Cette leçon parle de comprendre du code que quelqu'un d'autre a écrit. C'est différent de la leçon 3 (« Lire et comprendre le code IA ») qui parle de relire le code que l'IA vient de produire. Ici, personne ne se souvient pourquoi ce fichier existe.
Demander une visite guidée de l'architecture
Ne plongez pas dans le code ligne par ligne. Commencez par le haut : demandez à l'IA une carte mentale du projet. Pointez-la vers l'arborescence des dossiers et les fichiers de configuration (composer.json, package.json, routes), puis posez les bonnes questions :
- « Donne-moi une vue d'ensemble de l'architecture de ce projet en langage simple »
- « À quoi sert ce module et qui l'appelle ? »
- « Trace le flux depuis le formulaire de connexion jusqu'à la base de données »
- « Où est gérée l'authentification dans ce code ? »
L'IA répond comme un guide de musée : elle vous emmène d'abord voir les grandes salles avant les détails. Vous obtenez en cinq minutes ce qui aurait demandé une journée de lecture à l'aveugle.
# Donner à l'IA de quoi cartographier le projet
tree -L 2 -I 'node_modules|vendor'
cat composer.json package.json
cat routes/web.php # ou le fichier de routes équivalentTraduire le code legacy en langage humain
Le vrai cauchemar, ce sont les 200 lignes sans commentaire écrites un vendredi soir en 2017. Variables nommées $x, $tmp, $data2, conditions imbriquées sur cinq niveaux. L'IA excelle à traduire ce galimatias en explication claire.
Collez la fonction et demandez une explication en français, pas une réécriture. Vous voulez comprendre, pas encore modifier :
// Demandez : "Explique cette fonction ligne par ligne,
// en français, et dis-moi ce qu'elle renvoie."
function calc($a, $tmp, $f = 0) {
$r = 0;
foreach ($a as $i) {
if ($i['t'] == 1 && !$f) {
$r += $i['v'] * $tmp;
}
}
return $r;
}
// → L'IA : "Cette fonction additionne la valeur (v) des éléments
// de type 1, pondérée par un coefficient (tmp), en ignorant
// tout si le drapeau f est activé. C'est un calcul de total HT."Pour aller plus loin, demandez le graphe d'appels : « Quelles fonctions appellent calc() et lesquelles calc() appelle-t-elle ? » Vous reconstruisez la dépendance sans ouvrir dix fichiers.
« Qu'est-ce qui casse si je change ça ? »
La question la plus rentable quand on débarque sur du legacy. Avant de toucher une fonction, demandez à l'IA d'évaluer le rayon d'impact :
- « Qu'est-ce qui casserait si je modifiais la signature de cette fonction ? »
- « Quels fichiers dépendent de ce service ? »
- « Cette variable globale est-elle utilisée ailleurs ? »
L'IA repère les dépendances cachées bien plus vite qu'un grep manuel, surtout dans un code mal nommé. Mais attention à ne pas lui faire une confiance aveugle.
L'IA ne voit que ce que vous lui donnez. Si une dépendance vit dans un fichier que vous n'avez pas collé, elle ne la connaîtra pas, et elle peut halluciner une structure qui n'existe pas. Vérifiez toujours ses affirmations avec un vrai grep -r "nomFonction" ou la fonctionnalité « Find usages » de votre éditeur.
Nourrir l'IA, puis vérifier
Le bon réflexe sur un codebase inconnu tient en trois temps :
- Nourrir : donnez les bons fichiers : arborescence, config, le module concerné et ses voisins directs.
- Cartographier : demandez la vue d'ensemble, le flux, le graphe d'appels avant de plonger.
- Vérifier : recoupez chaque affirmation importante avec le code réel avant d'agir.
Règle d'or : utilisez l'IA pour comprendre vite, jamais comme source de vérité. Une explication de l'IA est une hypothèse à confirmer dans le code, pas un fait acquis.
Day one: 400,000 lines you did not write
You join a new project. Someone hands you a 400,000-line Git repo, written by seven people, five of whom have left. No up-to-date docs, file names like helper2_final_v3.php, and a meeting in two days where you will be asked "so, can you add Stripe payments?".
This onboarding used to take one to two weeks: opening random files, tracing function calls by hand, bothering the veterans. Today, the AI acts as a senior colleague who already knows the project and has infinite patience for your beginner questions.
This lesson is about understanding code someone else wrote. That is different from lesson 3 ("Reading and understanding AI code") which is about reviewing the code the AI just produced. Here, nobody remembers why this file exists.
Asking for a guided tour of the architecture
Do not dive into the code line by line. Start from the top: ask the AI for a mental map of the project. Point it at the folder tree and the config files (composer.json, package.json, routes), then ask the right questions:
- "Give me a high-level overview of this project's architecture in plain language"
- "What does this module do and who calls it?"
- "Trace the flow from the login form to the database"
- "Where is authentication handled in this code?"
The AI answers like a museum guide: it takes you to the big rooms before the details. You get in five minutes what would have taken a day of blind reading.
# Give the AI what it needs to map the project
tree -L 2 -I 'node_modules|vendor'
cat composer.json package.json
cat routes/web.php # or the equivalent routes fileTranslating cryptic legacy code into plain English
The real nightmare is the 200 uncommented lines written one Friday night in 2017. Variables named $x, $tmp, $data2, conditions nested five levels deep. The AI excels at translating this gibberish into a clear explanation.
Paste the function and ask for an explanation, not a rewrite. You want to understand, not modify yet:
// Ask: "Explain this function line by line,
// and tell me what it returns."
function calc($a, $tmp, $f = 0) {
$r = 0;
foreach ($a as $i) {
if ($i['t'] == 1 && !$f) {
$r += $i['v'] * $tmp;
}
}
return $r;
}
// → The AI: "This function sums the value (v) of type-1 items,
// weighted by a coefficient (tmp), ignoring everything if
// the flag f is set. It is a pre-tax total calculation."To go further, ask for the call graph: "Which functions call calc() and which ones does calc() call?" You rebuild the dependency map without opening ten files.
"What breaks if I change this?"
The most profitable question when landing on legacy code. Before touching a function, ask the AI to assess the blast radius:
- "What would break if I changed this function's signature?"
- "Which files depend on this service?"
- "Is this global variable used anywhere else?"
The AI spots hidden dependencies much faster than a manual grep, especially in poorly named code. But do not trust it blindly.
The AI only sees what you give it. If a dependency lives in a file you did not paste, it will not know about it, and it can hallucinate a structure that does not exist. Always verify its claims with a real grep -r "functionName" or your editor's "Find usages" feature.
Feed the AI, then verify
The right reflex on an unknown codebase comes in three steps:
- Feed — give the right files: the tree, the config, the module at hand and its direct neighbors.
- Map — ask for the overview, the flow, the call graph before diving in.
- Verify — cross-check every important claim against the real code before acting.
Golden rule: use the AI to understand fast, never as a source of truth. An AI explanation is a hypothesis to confirm in the code, not an established fact.
Collez ce prompt dans votre assistant après lui avoir donné l'arborescence et les fichiers de config du projet :
Tu es un développeur senior qui connaît ce projet par cœur. Je viens d'arriver dessus. À partir de l'arborescence et des fichiers de config que je t'ai donnés : 1) décris l'architecture en langage simple, 2) liste les modules principaux et leur rôle, 3) trace le flux d'une requête depuis la route jusqu'à la base de données. Termine par les 3 fichiers que je devrais lire en premier pour être opérationnel. Ne devine pas : si une info manque, dis-le et indique quel fichier me demander.
Vous héritez d'un projet inconnu. Rédigez le prompt que vous donneriez à l'IA pour vous y retrouver. Il doit demander une vue d'ensemble de l'architecture, tracer un flux précis, et exiger que l'IA signale ce qu'elle ne sait pas plutôt que de deviner.
Once the codebase is understood, how do you know if the AI answer really holds up? The next lesson, making the AI self-evaluate, teaches you to have it rate, doubt and justify its own output to reveal its weak spots.
Lesson 15: Making AI self-evaluate →