01 - Comprendre du code inconnu#

Tomber dans un repo qu on ne connait pas est la situation la plus couteuse en temps du metier ; c est aussi celle ou l IA fait gagner le plus.

Temps de lecture : 12 min | Niveau : Debutant

Ce que tu sauras faire apres#

• Cartographier un repo inconnu en moins de 30 minutes au lieu de deux jours.
• Poser au modele les memes questions que tu poserais a un collegue senior.
• Retracer un flux de donnees de la source jusqu au dashboard.
• Eviter le piege numero 1 : le modele qui decrit du code qu il n a jamais ouvert.

La strategie : du large vers le precis#

La documentation officielle de Claude Code donne l ordre exact :

"Start with broad questions, then narrow down to specific areas" -- Common workflows

Concretement, quatre niveaux, dans cet ordre :

Ne saute jamais du niveau 1 au niveau 4. Tu obtiendras une reponse plausible mais hors contexte.

Le piege a eviter d abord : le code invente#

Un modele peut decrire du code qu il n a jamais lu. La doc Anthropic donne la parade, sous forme d instruction a coller dans le prompt :

"Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering." -- Prompting best practices

Template garde-fou (a coller une fois, en debut de session) :

Regle pour toute cette session : ne parle jamais d un fichier que tu n as pas
ouvert. Si tu as besoin d un fichier, lis-le avant de repondre. Si tu n es pas
sur, ecris "je n ai pas verifie" plutot que d affirmer.

Niveau 1 - La vue d ensemble#

AVANT / APRES#

Mauvais prompt :

explique moi ce projet

Pourquoi c est mauvais : le modele ne sait pas ce qui t interesse. Il va te resservir le README, ou pire, deviner.

Prompt ameliore :

Donne-moi une vue d ensemble de ce repo. Structure ta reponse ainsi :
1. A quoi sert le projet, en 3 phrases
2. Les 5 dossiers les plus importants et leur role
3. Comment on lance le projet en local (commandes exactes)
4. Comment on lance les tests (commande exacte)
5. Les 5 termes metier specifiques au projet, avec leur definition

Lis les fichiers avant de repondre. Si une info n est nulle part, ecris
"non trouve" au lieu de deviner.

Pourquoi c est mieux :

• tu imposes un plan, donc une reponse comparable d un projet a l autre ;
• tu demandes des commandes exactes, donc verifiables en 10 secondes ;
• tu autorises le "non trouve", ce qui reduit l invention. Microsoft appelle ca "give the model an out" : "respond with 'not found' if the answer isn't present" (Prompt engineering techniques).

Template - Vue d ensemble#

Contexte : je viens d arriver sur ce repo, je ne le connais pas.
Mon metier : [DEVELOPPEUR / DATA ENGINEER / DATA ANALYST].
Ma mission sur ce repo : [TA_MISSION_EN_UNE_PHRASE]

Donne-moi :
1. Le but du projet en 3 phrases
2. Les [NOMBRE] dossiers les plus importants et leur role
3. Les commandes exactes pour : installer, lancer, tester
4. Le glossaire des termes metier specifiques au projet
5. Les 3 fichiers que je devrais lire en premier pour ma mission

Lis les fichiers avant de repondre. Ecris "non trouve" si l info est absente.

Niveau 2 - L architecture et les conventions#

La doc Claude Code propose ces questions telles quelles :

• explain the main architecture patterns used here
• what are the key data models?
• how is authentication handled?

Elle ajoute deux conseils : "Ask about coding conventions and patterns used in the project" et "Request a glossary of project-specific terms".

Template - Architecture#

Cartographie l architecture de ce projet.
Limite-toi a ce perimetre : [DOSSIER_OU_MODULE_A_ETUDIER]

Reponds en 4 parties :
1. SCHEMA : un diagramme en texte (ASCII) des composants et des fleches
   entre eux
2. ENTREES / SORTIES : d ou viennent les donnees, ou vont-elles
3. CONVENTIONS : nommage, structure des dossiers, gestion des erreurs,
   gestion de la configuration et des secrets
4. POINTS SENSIBLES : les 3 endroits ou une modification est risquee, et
   pourquoi

Pour chaque affirmation, cite le fichier et la ligne qui la justifient.
Si tu n as pas trouve de quoi justifier, ecris "non trouve".

Deux lignes de ce template font tout le travail.

Limite-toi a ce perimetre. Sans elle, le modele part lire tout le repo et remplit sa memoire de travail pour rien (voir plus bas, "Garder ta session propre").

cite le fichier et la ligne. Demander une citation reduit l invention. Microsoft le formule ainsi : "If you instruct the model to cite the source material when it makes statements, those statements are much more likely to be grounded."

Exemple reel - un projet Python / Airflow#

Sortie typique attendue sur un repo dags/ + plugins/ + dbt/ :

SCHEMA
  [API fournisseur] --extract--> [S3 raw]
        |                            |
        |                     dags/ingest_sales.py
        v                            v
  [Postgres staging] <--load-- [dbt/models/staging]
        |
        v
  [BigQuery marts] --> [Looker Studio]

ENTREES / SORTIES
  - Entree : API REST fournisseur (dags/ingest_sales.py, ligne 42)
  - Sortie : table BigQuery marts.fct_sales (dbt/models/marts/fct_sales.sql)

CONVENTIONS
  - Un DAG par source, nomme ingest_<source>.py
  - Les identifiants passent par les Airflow Connections, jamais en dur
  - Tout modele dbt a un test unique + not_null sur sa cle primaire

POINTS SENSIBLES
  - dags/ingest_sales.py:88 : aucun retry sur l appel API
  - plugins/hooks/custom_s3.py:15 : chemin S3 construit par concatenation

Niveau 3 - Comprendre un composant#

Template - Comprendre une fonction ou un module#

Fichier : @[CHEMIN/DU/FICHIER.py]
Fonction ou classe : [NOM]

Explique-moi ce code comme a un developpeur competent mais nouveau sur le
projet :

1. A quoi ca sert, en une phrase
2. Les entrees : type, format attendu, exemple concret de valeur
3. La sortie : type, format, exemple concret
4. Les effets de bord (ecriture fichier, appel reseau, modification d etat)
5. Les cas limites deja geres
6. Les cas limites NON geres
7. Qui l appelle dans le repo

Ne devine rien : ouvre les fichiers necessaires.

Le point 6 est celui qui a le plus de valeur : c est la que se cachent tes futurs bugs.

Niveau 4 - La question de niveau ligne#

La doc Claude Code liste les questions a poser "comme a un ingenieur senior" :

• What does async move { ... } do on line 134 of foo.rs?
• What edge cases does CustomerOnboardingFlowImpl handle?
• Why does this code call foo() instead of bar() on line 333?

Version francaise reutilisable telle quelle :

Dans @[CHEMIN/FICHIER], ligne [NUMERO] : pourquoi le code fait
[CE_QU_IL_FAIT] plutot que [ALTERNATIVE_QUI_TE_SEMBLE_EVIDENTE] ?
Regarde l historique git du fichier si ca aide a repondre.

L astuce de l historique git vient de la page Best practices de Claude Code, qui compare :

Le cas data : retracer un flux de donnees#

Les quatre niveaux ci-dessus servent a comprendre du code. Cette section est un cas a part : elle sert a suivre une donnee, pas une fonction. C est le besoin numero un en data engineering : d ou vient cette colonne ?

La doc officielle donne le prompt de base : trace the login process from front-end to database. Adapte-le a la data.

Template - Tracer un flux (lineage)#

Trace le parcours complet de la donnee [NOM_DE_LA_COLONNE_OU_METRIQUE]
dans ce repo.

Pour chaque etape, donne :
- le fichier et la ligne
- la transformation appliquee, en une phrase
- le nom que porte la donnee a cette etape

Format : une liste numerotee, de la source brute a la consommation finale.

Termine par une section RISQUES : les endroits ou cette donnee peut devenir
NULL, se dupliquer, ou changer de type.

Exemple - flux revenue_eur sur un projet Airflow + dbt#

1. dags/ingest_orders.py:56   API -> JSON brut, champ "amount" (string, USD)
2. dags/ingest_orders.py:71   ecriture S3 raw/orders/dt=YYYY-MM-DD/
3. dbt/models/staging/stg_orders.sql:12
                              CAST(amount AS NUMERIC) -> amount_usd
4. dbt/models/intermediate/int_orders_eur.sql:8
                              amount_usd * fx_rate -> revenue_eur
5. dbt/models/marts/fct_sales.sql:24
                              SUM(revenue_eur) GROUP BY day -> revenue_eur

RISQUES
- etape 3 : le CAST echoue si "amount" contient une virgule decimale
- etape 4 : fx_rate vient d une table mise a jour la veille -> NULL le jour J
- etape 5 : pas de deduplication, un re-run du DAG double les lignes

Ce bloc RISQUES, tu peux le coller directement dans ton ticket ou ta note de recette.

Garder ta session propre#

Explorer un repo remplit vite le contexte du modele. La doc Claude Code est explicite :

"Exploring a large codebase fills your context with file reads. Delegate the exploration so only the findings come back."

Deux reflexes :

1. Deleguer a un sous-agent. Un subagent est un assistant qui travaille dans sa propre fenetre de contexte et ne te renvoie que le resume. Prompt : use a subagent to investigate how our auth system handles token refresh (Subagents).
2. Repartir a zero entre deux sujets avec /clear. La doc nomme l echec classique "the kitchen sink session" et donne le correctif : "/clear between unrelated tasks".

Autre echec nomme dans la doc : "The infinite exploration. You ask Claude to 'investigate' something without scoping it. Claude reads hundreds of files, filling the context." Donc cadre toujours ton exploration : un dossier, un flux, une question.

Ta routine des 30 premieres minutes#

1. Coller le garde-fou "ne parle pas d un fichier que tu n as pas ouvert".
2. Niveau 1 : vue d ensemble + glossaire.
3. Niveau 2 : architecture + conventions + points sensibles.
4. Ecrire un NOTES.md avec ce que tu retiens (le fichier 06 donne le template).
5. Niveau 3 ou 4 : seulement sur le composant de ta mission.
6. Si ta mission touche a une table ou a une metrique : le template de flux de donnees.

A retenir#

• Toujours du large vers le precis : vue d ensemble, architecture, composant, ligne.
• Impose un plan de reponse numerote : tu obtiens des reponses comparables et verifiables.
• Demande fichier + ligne en justification, et autorise explicitement "non trouve".
• Pour un flux de donnees, demande la liste des etapes ET la liste des endroits ou ca casse.
• Delegue l exploration a un sous-agent, et fais /clear entre deux sujets sans rapport.

Sources#

• Claude Code - Common workflows
• Claude Code - Best practices
• Claude Code - Subagents
• Anthropic - Prompting best practices
• Microsoft Learn - Prompt engineering techniques
• GitHub Docs - Prompt engineering for GitHub Copilot Chat
• SWE-agent/SWE-agent - traces pas a pas d un agent qui explore un depot inconnu, dans trajectories/demonstrations/