Carte de codebase existant avec Claude Code : workflow sûr en 45 minutes

Quand vous introduisez Claude Code dans un codebase existant, le premier livrable ne devrait pas être un diff. Ce devrait être une carte. Une repo map indique où l’application démarre, quels dossiers comptent, quelles zones ne doivent pas être touchées aujourd’hui, comment vérifier un changement et ce que la personne suivante doit savoir. Sans cette carte, une session utile peut dériver vers un nettoyage trop large, des refactors secondaires ou des changements difficiles à relire.

Ce guide propose un workflow de 45 minutes pour lire un dépôt avant de l’éditer. La documentation officielle Claude Code overview explique que Claude Code peut lire un codebase, modifier des fichiers et exécuter des commandes. Cette puissance rend les limites initiales indispensables.

Pour aller plus loin, lisez aussi les premiers prompts pour codebase existant, le guide des permissions Claude Code et le template de départ CLAUDE.md.

La repo map en 45 minutes

Réservez 25 minutes à l’exploration en lecture seule, 10 minutes à la carte, 5 minutes au choix d’une première tâche sûre et 5 minutes à la revue du plan. Ne cherchez pas un document d’architecture parfait. Il vous faut une carte de travail pour réaliser un changement petit, réversible et vérifiable.

flowchart TD
  A["Inventaire en lecture seule"] --> B["Trouver les points d'entrée"]
  B --> C["Séparer zones sûres et risquées"]
  C --> D["Choisir un premier patch"]
  D --> E["Fixer les commandes de preuve"]
  E --> F["Écrire repo-map.md"]

Un point d’entrée est l’endroit où l’application commence : route, handler API, bootstrap serveur, commande CLI, tâche planifiée ou loader de contenu. Une zone risquée est tout endroit où une petite erreur touche la confiance ou les revenus : authentification, paiement, suppression, configuration de production, secrets, déploiement, analytics et tags publicitaires.

Étape 1 : inventaire en lecture seule

Commencez avec des commandes qui décrivent le dépôt sans le modifier. Sur Windows PowerShell, ce bloc suffit pour un premier passage.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Repérez la stack, la documentation, les dossiers générés, les caches et les changements non commités. Si le working tree est dirty, identifiez à qui appartiennent les changements avant de demander une édition. C’est le geste le plus simple pour éviter d’écraser le travail d’autrui.

Le premier prompt doit rendre la limite explicite.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

La phrase Do not edit files yet maintient Claude Code en mode exploration jusqu’à ce qu’un plan relisible existe.

Étape 2 : écrire repo-map.md

Ne laissez pas la découverte uniquement dans le chat. Écrivez un petit repo-map.md que la prochaine session pourra réutiliser. La documentation officielle memory explique que CLAUDE.md peut stocker des instructions persistantes, mais une première exploration mérite souvent un document séparé. Les règles durables pourront ensuite migrer vers CLAUDE.md.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

Ce n’est pas une architecture complète. C’est un garde-fou pour le premier changement utile.

Étape 3 : renforcer avec les permissions

Les instructions aident, mais elles ne remplacent pas l’application de règles. La documentation permissions décrit allow, ask et deny. Pour une première session dans un dépôt existant, autorisez lecture et checks sûrs, demandez confirmation avant build ou édition, et refusez push, commandes destructrices et secrets.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

Ce JSON est un point de départ. Votre projet peut ne pas avoir npm run test, ou nécessiter un autre chemin éditable. L’important est de décider ce que vous refusez avant d’élargir ce que vous autorisez.

Étape 4 : choisir un premier patch sûr

Une fois la carte prête, choisissez une tâche petite, réversible et facile à vérifier. Trois cas fonctionnent particulièrement bien.

Le premier est la correction d’un CTA de contenu. Par exemple, vérifiez qu’un article populaire mène naturellement vers produits et formation. Un seul fichier de contenu suffit souvent, avec build et preview comme preuve.

Le deuxième est l’ajout de commandes de vérification dans README ou CLAUDE.md. Documenter build, test, lint et preview réduit le coût des futures sessions sans changer le comportement de l’application.

Le troisième est un changement de texte ou de format de date sur un écran. Limitez le patch à un ou deux fichiers et vérifiez par test, capture ou preview locale. Authentification, paiement, permissions et suppression attendront.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

Ce prompt transforme une demande large en patch relisible.

Étape 5 : vérifier la carte

Une repo map est du texte, mais on peut vérifier ses sections minimales. Sauvegardez ceci comme check-repo-map.js.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

Le script est simple, mais il force chaque session à laisser le même minimum de contexte.

Erreurs fréquentes

La première erreur est une demande trop large : “refactorise l’app” ou “améliore la qualité”. La parade consiste à préciser lecture seule, nombre maximal de fichiers, zones interdites et commandes de preuve.

La deuxième est de mélanger les artefacts générés dans la carte. dist, .astro, .next, coverage et node_modules gonflent la vue sans forcément aider. Excluez-les sauf s’ils sont précisément la cible à inspecter.

La troisième est de sous-estimer les services externes. Email, webhooks de paiement, tags publicitaires, analytics et CRM peuvent avoir peu de code mais un fort impact business. Lisez d’abord, éditez dans une tâche séparée.

La quatrième est de s’arrêter au build. Un build peut passer alors que le mobile, les blocs de code, les CTA ou les liens internes sont cassés. Pour un site de contenu, ouvrez la preview et inspectez le corps, les blocs de code, /products/ et /training/.

Checklist de revue

Angle	À vérifier	Mauvais signal
Diff	Seuls les fichiers demandés changent	Formatage massif incident
Entrée	Le chemin de chargement est compris	Fichier jamais utilisé
Risque	Auth, paiement, suppression, prod intacts	Secrets ou deploy modifiés
Preuve	Commande ou check manuel présent	”Probablement bon” seulement
Funnel	CTA et liens internes naturels	Liens produit plaqués
Handoff	Risques restants écrits	La prochaine session refait l’enquête

Cette checklist ne sert pas à se méfier de Claude Code. Elle rend le travail répétable.

Inclure les chemins de revenus

Pour un site comme ClaudeCodeLab, la carte doit aussi contenir les chemins de monétisation. Quels articles attirent le trafic ? Où le lecteur voit-il un téléchargement, un produit ou une page de consultation ? Les modèles prêts à l’emploi sont dans la bibliothèque de produits. Pour le déploiement en équipe, les permissions et les opérations de contenu, consultez la formation Claude Code.

Quand les chemins de revenus sont dans la carte, un petit CTA n’est plus seulement une retouche de texte. Vous vérifiez aussi liens internes, pages produit, formulaires, analytics et annonces. Un code correct ne génère pas de revenus si le lecteur ne voit pas l’étape suivante.

Résumé

Utilisez les 45 premières minutes avec Claude Code pour cartographier le codebase, pas pour le réécrire. Faites l’inventaire, trouvez les entrées, marquez les zones risquées, choisissez une tâche sûre, fixez les preuves et laissez repo-map.md. Ensuite seulement, faites un petit changement dans un ou deux fichiers.