Naviguer dans de grands codebases avec Claude Code et Codex

Quand on arrive dans un grand codebase, l’objectif initial n’est pas de tout comprendre. Le premier objectif est de fabriquer une carte : où le système démarre, quels dossiers sont générés, quels fichiers portent le risque métier, et quelles frontières de propriété demandent une validation humaine.

Claude Code et Codex sont très utiles pour cette lecture, à condition de garder l’enquête disciplinée. Coller des fichiers entiers, de longs logs et des centaines de résultats de recherche dans la conversation principale donne plus de texte, pas forcément plus de signal. C’est le gonflement du contexte : la conversation grandit pendant que la qualité de décision baisse.

Ce guide transforme le workflow que j’utilise pour les handoffs, les audits et la maintenance des articles ClaudeCodeLab en commandes et prompts copiables. Pour le comportement des outils, je m’appuie sur les documentations officielles : Claude Code common workflows, CLI reference, memory, Codex non-interactive mode et Codex AGENTS.md.

Commencer Par Une Carte Du Repo

Avant de demander à un agent d’expliquer le dépôt, réduisez vous-même la forme extérieure. rg signifie ripgrep. Il est rapide, respecte les règles d’ignore courantes et permet d’exclure les dossiers générés avant qu’ils ne polluent l’analyse.

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

Ensuite, demandez une carte en lecture seule. Les workflows officiels de Claude Code recommandent de commencer large puis de descendre vers des composants précis. La documentation Codex indique que codex exec s’exécute par défaut dans un sandbox en lecture seule, ce qui convient à une première synthèse.

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

Avec Claude Code, utilisez -p pour une réponse non interactive. La référence CLI le documente comme print mode.

claude -p "
Lecture seule. Construis une carte de ce codebase.
Réponds dans cet ordre :
1. Apps, packages et services
2. Entrypoints d'exécution, de test et de build
3. Dossiers générés et dossiers à ignorer
4. Points clés de AGENTS.md, CLAUDE.md, README et notes de design
5. Les 10 prochains fichiers à lire, avec une raison chacun
Propose seulement les éditions ou commandes ; ne les exécute pas.
"

Rechercher Par Couches

Un résultat de recherche n’est pas une compréhension. La recherche produit seulement des candidats. Utilisez cinq couches : structure, vocabulaire métier, références, configuration et historique.

# 1. Candidats d'entrypoint
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. Vocabulaire métier. Remplacez ces termes pour votre produit.
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. Appelants et références de la zone à modifier
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. Configuration et variables d'environnement
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. Historique : pourquoi ce design existe
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

Ne collez pas cent résultats dans l’agent. Regardez d’abord la forme, puis donnez un petit jeu de candidats à classer.

Tu es reviewer de navigation de codebase.
Classe ces résultats rg en : entrypoint d'implémentation, appelant, configuration, test et bruit.
Limite chaque classe aux 5 fichiers les plus importants à lire ensuite.
Pour chaque fichier choisi, donne une raison concrète.
Si c'est incertain, écris "nécessite une autre recherche" au lieu de deviner.

Esquisser Un Graphe De Dépendances

Avant d’installer un analyseur complet, un petit script Node peut donner assez de signal. Ce n’est pas un compilateur TypeScript. Il suit seulement les imports relatifs locaux, mais cela suffit souvent pour voir le rayon d’impact direct.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

Sauvegardez puis lancez-le.

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

Transformez ensuite la sortie en carte de risque.

À partir de ces direct importers, évalue le rayon d'impact d'un changement dans AuthService.ts.
Utilise high / medium / low.
High signifie authentification, billing, autorisation, persistance ou API publique.
Pour chaque classe, liste les tests et fichiers de configuration à lire avant d'éditer.

Tracer Depuis Les Entrypoints

Une liste de fichiers n’explique pas le comportement runtime. Pour un backend, tracez request, middleware, route, controller, service, repository, database. Pour un frontend, tracez route, loader, state, API client, component et analytics.

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

Demandez une table de flux, pas un paragraphe.

Angle	Bonne sortie	Sortie faible
Entrée	POST /login -> auth route -> AuthService.login	”Auth est important”
État	Cookie, session, DB, cache ou queue modifiés	Aucun changement d’état
Échec	Réponse d’erreur, log, audit, retry	Happy path seulement
Tests	Fichier de test existant et cas manquants	”Ajouter des tests”

Trace le flux login depuis l'entrypoint jusqu'à la persistance.
Retourne une table avec : ordre, fichier, fonction/classe, changement d'état, comportement en cas d'échec, tests à lire.
Ne remplis pas les trous avec des suppositions. Si une étape est inconnue, nomme le prochain fichier à inspecter.

Cartographier Propriété Et Risque

Dans un grand dépôt, la première question n’est pas “est-ce que ça tourne ?”, mais “à qui appartient cette frontière ?”. Les frontières peuvent être celles d’une équipe, de données, de release, de conformité ou de revenu.

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex lit officiellement AGENTS.md, donc il est utile d’y placer les règles du projet. Claude Code peut utiliser CLAUDE.md et memory pour raccourcir les sessions suivantes. Pour un modèle plus complet, voir CLAUDE.md Best Practices.

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

Utiliser Des Prompts D’Exploration En Lecture Seule

Pour la première exploration, gardez l’agent en mode conseil. Il faut une carte, des hypothèses et des inconnues avant les modifications.

Investigue en lecture seule. N'édite pas de fichiers, n'ajoute pas de dépendances, ne reformate pas le code et ne lance pas de tests.

Objectif :
Comprendre la portée d'implémentation et le risque de changement pour [nom de fonctionnalité].

Retourne :
1. Fichiers entrypoint
2. Modèles de données centraux
3. Dépendances directes et indirectes
4. Frontières de propriété
5. Carte de risque : high / medium / low
6. Fichiers à inspecter ensuite
7. Hypothèses non confirmées

Règles :
Marque les suppositions comme hypothèses.
Inclue les noms de fichier et les preuves.
Ne cite pas de grands corps de fichiers.

Les subagents Claude Code sont utiles quand l’exploration remplirait la conversation principale de lectures de fichiers. La documentation officielle explique qu’ils travaillent dans leur propre contexte et retournent seulement un résumé. Codex documente aussi les subagents pour l’exploration parallèle de codebases. Utilisez-les pour des tâches bornées, car ils consomment aussi des tokens. Voir Subagent Patterns.

Lance trois subagents en lecture seule :
1. Entrypoints API et frontières auth
2. DB schema et frontières migration
3. Routes UI et chemin de revenu

Chaque subagent peut lire au maximum 8 fichiers et doit retourner seulement ses conclusions finales.
Ensuite, l'agent parent fusionne doublons, conflits et inconnues.

Éviter Le Gonflement Du Contexte

La règle simple : séparez les preuves des décisions. Fichiers entiers, logs longs et cent résultats de recherche sont trop lourds. Filtrez d’abord, puis demandez une décision.

La compaction d’OpenAI est une fonctionnalité API, mais le principe s’applique ici : conserver le résumé nécessaire et supprimer le détail périmé.

Compresse l'enquête pour que la prochaine personne puisse continuer en moins de 300 mots.
Garde :
- Entrypoints confirmés
- Fichiers high risk
- Frontières à ne pas franchir
- Hypothèses non confirmées
- Prochaine commande à lancer

Supprime :
- Hypothèses déjà invalidées
- Logs longs
- Fichiers générés inutiles

Les notes de handoff comptent en développement comme en opérations de contenu. Pour des articles multilingues, notez les fichiers locale possédés. Pour une app, notez l’entrypoint tracé. Pour un bug, notez les hypothèses rejetées. Associez cela à Claude Code Testing Strategies et au guide approval et sandbox.

Trois Cas Concrets

Premier cas : handoff d’un SaaS. Le premier jour, cartographiez login, billing, admin et notifications. Trouvez les importers de AuthService et BillingService, puis tracez checkout de la route à la base de données. N’éditez pas encore. La sortie attendue est une carte de risque et un ordre de lecture.

Deuxième cas : migration legacy. Cherchez legacy, deprecated et migration avant de demander du code de remplacement. Demandez plutôt les risques de compatibilité. Migrations DB, APIs publiques, batch jobs et cron demandent une attention particulière, car le rollback coûte cher.

Troisième cas : un site de contenu et monétisation comme ClaudeCodeLab. Articles, composants CTA, liens internes, pages produit et traductions vivent dans des dossiers différents. Travaillez par slug. Demandez à l’agent de posséder un seul slug et d’utiliser les autres articles uniquement pour vérifier les liens.

Échecs Fréquents

• Faire confiance au README seul. Les vrais entrypoints dérivent souvent de la documentation ancienne.
• Traiter les résultats de recherche comme un flux d’exécution. Un hit est un candidat, pas une preuve.
• Laisser l’agent éditer avant de clarifier la propriété.
• Injecter dossiers générés, lockfiles, coverage ou dist dans la conversation.
• Donner aux subagents un périmètre trop large.
• Dire “corrige en sécurité” sans définir high / medium / low.

CTA Pour Les Équipes

La navigation dans un grand codebase touche aussi le revenu. Checkout, formulaires de leads, contenu payant, analytics et publicités sont derrière des frontières de risque. Une carte avant édition réduit les retours arrière.

Si votre équipe adopte Claude Code ou Codex, commencez par un modèle de repo map, des règles AGENTS.md/CLAUDE.md, des critères de review et des prompts d’exploration en lecture seule. En individuel, démarrez avec la cheat sheet gratuite. Pour une formation sur vos vrais dépôts, consultez Claude Code training and consulting.

Note De Vérification Terrain

Quand j’utilise ce workflow, les prompts d’implémentation suivants sont plus stables que lorsque je commence par coller de grands fichiers. Les artefacts les plus utiles sont la carte du repo, les résultats rg classés, une petite table de dépendances et la carte high / medium / low. Quand je saute ces étapes, les dossiers générés, anciens tests et modules d’autres équipes entrent dans la conversation. Avant publication, j’ai relu les commandes, prompts et script Node pour vérifier qu’ils étaient copiables et que la structure JavaScript était cohérente.