Intégration dans la Base de Code (Codebase Onboarding)
Analysez systématiquement une base de code inconnue et produisez un guide d'intégration structuré. Conçu pour les développeurs qui rejoignent un nouveau projet ou configurent Claude Code pour la première fois dans un dépôt existant.
Quand l'utiliser
- Première ouverture d'un projet avec Claude Code
- Arrivée dans une nouvelle équipe ou un nouveau dépôt
- L'utilisateur demande "aide-moi à comprendre cette base de code"
- L'utilisateur demande de générer un CLAUDE.md pour un projet
- L'utilisateur dit "forme-moi" ou "guide-moi dans ce dépôt"
Comment ça fonctionne
Phase 1 : Reconnaissance
Recueillez les signaux bruts sur le projet sans lire chaque fichier. Exécutez ces vérifications en parallèle :
1. Détection des manifestes 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
→ Les 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 des 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 :
Tech Stack
- 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
Pattern d'Architecture
- 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 patterns déjà suivis par la base de code :
Conventions de Nommage
- Nommage des fichiers : kebab-case, camelCase, PascalCase, snake_case
- Patterns de nommage des composants/classes
- Nommage des fichiers de test :
*.test.ts,*.spec.ts,*_test.go
Patterns 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
- Patterns 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 PR (squash, merge, rebase)
- Si le dépôt n'a pas encore de commits ou seulement un historique superficiel (ex.
git clone --depth 1), ignorez cette section et notez "Historique Git indisponible ou trop superficiel pour détecter les conventions"
Phase 4 : Générer les Artefacts d'Intégration
Produisez deux sorties :
Sortie 1 : Guide d'Intégration
# Guide d'Intégration : [Nom du Projet]
## Vue d'Ensemble
[2-3 phrases : ce que fait ce projet et à qui il s'adresse]
## Tech Stack
<!-- Exemple pour un projet Next.js — remplacez par la stack 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 — remplacez 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 → correspondance d'objectif]
## Cycle de Vie d'une Requête
[Tracez une requête API de l'entrée à la réponse]
## Conventions
- [Pattern de nommage des fichiers]
- [Approche de gestion des erreurs]
- [Patterns de test]
- [Workflow Git]
## Tâches Courantes
<!-- Exemple pour un projet Node.js — remplacez 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 — remplacez 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 indiquez clairement ce qui a été ajouté ou modifié.
# Instructions du Projet
## Tech Stack
[Résumé de la stack détectée]
## Style de Code
- [Conventions de nommage détectées]
- [Patterns détectés à suivre]
## Tests
- Exécuter les tests : `[commande de test détectée]`
- Pattern de test : [convention de fichier de test détectée]
- Couverture : [si configuré, la commande de couverture]
## Build & 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]
- [Patterns de gestion des erreurs]
Bonnes Pratiques
- Ne lisez pas tout — la reconnaissance doit utiliser Glob et Grep, pas Read sur chaque fichier. Lisez sélectivement uniquement pour les 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. Indiquez ce qui est nouveau par rapport à l'existant.
- 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-Patterns à Éviter
- Générer un CLAUDE.md de plus de 100 lignes — restez concentré
- Lister chaque dépendance — ne mettez en évidence que celles qui façonnent la façon dont vous écrivez du 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 une perspective structurelle que le README n'a pas
Exemples
Exemple 1 : Première fois dans un nouveau dépôt
Utilisateur : "Forme-moi à cette base de code"
Action : Exécutez le workflow complet en 4 phases → produisez 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 CLAUDE.md pour un projet existant
Utilisateur : "Génère un CLAUDE.md pour ce projet"
Action : Exécutez les Phases 1-3, ignorez le Guide d'Intégration, produisez 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 : Lisez le CLAUDE.md existant, exécutez les Phases 1-3, fusionnez les nouvelles découvertes
Sortie : CLAUDE.md mis à jour avec les ajouts clairement marqués