Intégration au Codebase (Codebase Onboarding)
Analysez systématiquement un codebase inconnu et produisez un guide d'intégration structuré. Conçu pour les développeurs qui rejoignent un nouveau projet ou qui configurent Claude Code dans un dépôt existant pour la première fois.
Quand l'utiliser
- Première ouverture d'un projet avec Claude Code
- Arrivée sur une nouvelle équipe ou un nouveau dépôt
- L'utilisateur demande "aide-moi à comprendre ce codebase"
- L'utilisateur demande de générer un CLAUDE.md pour un projet
- L'utilisateur dit "intègre-moi" ou "guide-moi dans ce dépôt"
Comment ça fonctionne
Phase 1 : Reconnaissance
Recueillez des signaux bruts sur le projet sans lire chaque fichier. Exécutez ces vérifications en parallèle :
1. Détection des manifests de paquets
→ package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle,
Gemfile, composer.json, mix.exs, pubspec.yaml
2. Identification du framework
→ next.config.*, nuxt.config.*, angular.json, vite.config.*,
django settings, flask app factory, fastapi main, rails config
3. Identification des points d'entrée
→ main.*, index.*, app.*, server.*, cmd/, src/main/
4. Aperçu de la structure des répertoires
→ 2 premiers niveaux de l'arborescence, en ignorant node_modules, vendor,
.git, dist, build, __pycache__, .next
5. Détection de la configuration et des outils
→ .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile,
docker-compose*, .github/workflows/, .env.example, configurations CI
6. Détection de la structure de tests
→ tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js,
pytest.ini, jest.config.*, vitest.config.*
Phase 2 : Cartographie de l'architecture
À partir des données de reconnaissance, identifiez :
Pile technologique
- Langage(s) et contraintes de version
- Framework(s) et bibliothèques principales
- Base(s) de données et ORM
- Outils de build et bundlers
- Plateforme CI/CD
Modèle architectural
- Monolithe, monorepo, microservices ou serverless
- Séparation frontend/backend ou full-stack
- Style d'API : REST, GraphQL, gRPC, tRPC
Répertoires clés Mappez les répertoires de premier niveau à leur objectif :
src/components/ → Composants UI React
src/api/ → Gestionnaires de routes API
src/lib/ → Utilitaires partagés
src/db/ → Modèles de base de données et migrations
tests/ → Suites de tests
scripts/ → Scripts de build et de déploiement
Flux de données Tracez une requête de l'entrée à la réponse :
- Où la requête entre-t-elle ? (routeur, gestionnaire, contrôleur)
- Comment est-elle validée ? (middleware, schémas, gardes)
- Où se trouve la logique métier ? (services, modèles, cas d'utilisation)
- Comment atteint-elle la base de données ? (ORM, requêtes brutes, repositories)
Phase 3 : Détection des conventions
Identifiez les motifs que le codebase suit déjà :
Conventions de nommage
- Nommage des fichiers : kebab-case, camelCase, PascalCase, snake_case
- Motifs de nommage des composants/classes
- Nommage des fichiers de test :
*.test.ts,*.spec.ts,*_test.go
Motifs de code
- Style de gestion des erreurs : try/catch, types Result, codes d'erreur
- Injection de dépendances ou imports directs
- Approche de gestion d'état
- Motifs asynchrones : callbacks, promesses, async/await, canaux
Conventions Git
- Nommage des branches à partir des branches récentes
- Style des messages de commit à partir des commits récents
- Workflow de PR (squash, merge, rebase)
- Si le dépôt n'a aucun commit ou seulement un historique superficiel (ex.
git clone --depth 1), sautez cette section et notez "Historique Git indisponible ou trop superficiel pour détecter les conventions"
Phase 4 : Génération des artefacts d'intégration
Produisez deux sorties :
Sortie 1 : Guide d'intégration
# Guide d'intégration : [Nom du projet]
## Aperçu
[2-3 phrases : ce que fait ce projet et à qui il sert]
## Pile technologique
<!-- Exemple pour un projet Next.js — à remplacer par la pile détectée -->
| Couche | Technologie | Version |
|--------|-------------|---------|
| Langage | TypeScript | 5.x |
| Framework | Next.js | 14.x |
| Base de données | PostgreSQL | 16 |
| ORM | Prisma | 5.x |
| Tests | Jest + Playwright | - |
## Architecture
[Diagramme ou description de la façon dont les composants se connectent]
## Points d'entrée clés
<!-- Exemple pour un projet Next.js — à remplacer par les chemins détectés -->
- **Routes API** : `src/app/api/` — gestionnaires de routes Next.js
- **Pages UI** : `src/app/(dashboard)/` — pages authentifiées
- **Base de données** : `prisma/schema.prisma` — source de vérité du modèle de données
- **Configuration** : `next.config.ts` — configuration build et runtime
## Carte des répertoires
[Répertoire de premier niveau → mappage d'objectif]
## Cycle de vie d'une requête
[Tracez une requête API de l'entrée à la réponse]
## Conventions
- [Motif de nommage des fichiers]
- [Approche de gestion des erreurs]
- [Motifs de test]
- [Workflow Git]
## Tâches courantes
<!-- Exemple pour un projet Node.js — à remplacer par les commandes détectées -->
- **Lancer le serveur de développement** : `npm run dev`
- **Exécuter les tests** : `npm test`
- **Exécuter le linter** : `npm run lint`
- **Migrations de base de données** : `npx prisma migrate dev`
- **Build pour la production** : `npm run build`
## Où chercher
<!-- Exemple pour un projet Next.js — à remplacer par les chemins détectés -->
| Je veux... | Regardez dans... |
|------------|------------------|
| Ajouter un point de terminaison API | `src/app/api/` |
| Ajouter une page UI | `src/app/(dashboard)/` |
| Ajouter une table de base de données | `prisma/schema.prisma` |
| Ajouter un test | `tests/` correspondant au chemin source |
| Modifier la configuration de build | `next.config.ts` |
Sortie 2 : CLAUDE.md de démarrage
Générez ou mettez à jour un CLAUDE.md spécifique au projet basé sur les conventions détectées. Si CLAUDE.md existe déjà, lisez-le d'abord et améliorez-le — conservez les instructions existantes spécifiques au projet et signalez clairement ce qui a été ajouté ou modifié.
# Instructions du projet
## Pile technologique
[Résumé de la pile détectée]
## Style de code
- [Conventions de nommage détectées]
- [Motifs détectés à suivre]
## Tests
- Exécuter les tests : `[commande de test détectée]`
- Motif de test : [convention de fichier de test détectée]
- Couverture : [si configuré, la commande de couverture]
## Build et exécution
- Développement : `[commande de développement détectée]`
- Build : `[commande de build détectée]`
- Lint : `[commande de lint détectée]`
## Structure du projet
[Répertoire clé → carte d'objectif]
## Conventions
- [Style de commit si détectable]
- [Workflow PR si détectable]
- [Motifs de gestion des erreurs]
Bonnes pratiques
- Ne lisez pas tout — la reconnaissance doit utiliser Glob et Grep, pas la lecture de chaque fichier. Lisez sélectivement uniquement pour des signaux ambigus.
- Vérifiez, ne devinez pas — si un framework est détecté à partir de la configuration mais que le code réel utilise quelque chose de différent, faites confiance au code.
- Respectez le CLAUDE.md existant — s'il en existe déjà un, améliorez-le plutôt que de le remplacer. Signalez ce qui est nouveau par rapport à ce qui existe.
- Restez concis — le guide d'intégration doit pouvoir être parcouru en 2 minutes. Les détails appartiennent au code, pas au guide.
- Signalez les inconnues — si une convention ne peut pas être détectée avec certitude, dites-le plutôt que de deviner. "Impossible de déterminer le runner de tests" est mieux qu'une réponse erronée.
Anti-patrons à éviter
- Générer un CLAUDE.md de plus de 100 lignes — restez concentré
- Lister chaque dépendance — mettez en évidence uniquement celles qui influencent la façon dont vous écrivez le code
- Décrire des noms de répertoires évidents —
src/n'a pas besoin d'explication - Copier le README — le guide d'intégration apporte un aperçu structurel que le README n'a pas
Exemples
Exemple 1 : Première fois dans un nouveau dépôt
Utilisateur : "Intègre-moi à ce codebase"
Action : Exécuter le workflow complet en 4 phases → produire le guide d'intégration + CLAUDE.md de démarrage
Sortie : Guide d'intégration imprimé directement dans la conversation, plus un CLAUDE.md écrit à la racine du projet
Exemple 2 : Générer un CLAUDE.md pour un projet existant
Utilisateur : "Génère un CLAUDE.md pour ce projet"
Action : Exécuter les phases 1-3, ignorer le guide d'intégration, produire uniquement le CLAUDE.md
Sortie : CLAUDE.md spécifique au projet avec les conventions détectées
Exemple 3 : Améliorer un CLAUDE.md existant
Utilisateur : "Mets à jour le CLAUDE.md avec les conventions actuelles du projet"
Action : Lire le CLAUDE.md existant, exécuter les phases 1-3, fusionner les nouvelles découvertes
Sortie : CLAUDE.md mis à jour avec les ajouts clairement signalés