Guide concret pour industrialiser Claude Code, étape par étape. Pas de théorie corporate, juste ce qui marche, tiré de 48 projets et 10 581 sessions dans mon lab.

1. Prérequis

Avant de commencer, il faut quatre choses :

1
Un projet avec git

N'importe quel projet versionne. Git est indispensable - Claude Code s'appuie dessus pour le diff, les commits, et le suivi des modifications.

2
Node.js ou un runtime pertinent

Node.js 18+, Rust, Python - le runtime de votre projet. Claude Code a besoin de pouvoir lancer build, tests et lint.

3
Claude Code CLI installé

npm install -g @anthropic-ai/claude-code puis claude dans votre terminal. C'est tout.

4
30 minutes devant vous

C'est le temps nécessaire pour le setup initial. Le reste se construit progressivement au fil des semaines.

2. Jour 1 : le CLAUDE.md minimal (30 min)

Le CLAUDE.md est le fichier le plus important. C'est le "prompt système" de Claude Code pour votre projet. Sans lui, Claude doit deviner votre stack, vos conventions, et vos commandes - et il se trompe souvent.

Template de départ

Créez un fichier CLAUDE.md à la racine de votre projet avec ce contenu adapté :

CLAUDE.md
# Mon Projet

## Stack
- Framework: [ex: NestJS 10, Angular 17, Nuxt 3]
- Langage: TypeScript strict
- Base de données: PostgreSQL 16
- Runtime: Node.js 20

## Commandes
- Build: `npm run build`
- Test: `npm run test`
- Lint: `npm run lint`
- Dev: `npm run dev`

## Conventions
- Commits conventionnels (feat/fix/docs/test/refactor)
- TypeScript strict, pas de `any`
- Tests obligatoires pour chaque feature
- Fichiers < 300 lignes

## Règles
- Toujours lancer les tests avant de commit
- Ne pas utiliser `any` en TypeScript
- Un commit = un changement logique
- Lire un fichier avant de le modifier

Pourquoi ces sections sont essentielles

Stack

Sans cette section, Claude utilise des patterns génériques. Avec elle, il génère du code idiomatique pour votre framework. J'ai observé 3x moins de corrections sur les projets avec une stack bien documentée.

Commandes

C'est la section la plus impactante de mon lab. Sans elle, Claude tente npm test alors que la commande est npm run test:backend. Avec elle, il lance la bonne commande du premier coup.

Règles

Claude a tendance à skipper les tests et à utiliser any si on ne lui dit pas explicitement de ne pas le faire. 3 règles impératives suffisent pour le cadrer.

3. Semaine 1 : permissions et workflow

Après quelques jours avec Claude Code, deux frictions apparaissent : il demande confirmation pour chaque commande, et il perd le contexte entre les sessions. Voici comment les résoudre.

3.1. Permissions auto-approuvées

Créez .claude/settings.local.json pour autoriser les commandes courantes sans confirmation :

.claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npx prettier --write *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ]
  }
}

3.2. session.md pour la persistance du contexte

Le problème : chaque nouvelle session Claude Code commence à zéro. Il ré-explore le projet, redécouvre le contexte, relit les fichiers. Coût : 15 à 20 minutes et environ 50K tokens perdus.

La solution : un fichier .claude/session.md lu au démarrage et mis à jour en fin de session.

.claude/session.md
# Session en cours

## État
- **Branche** : feat/auth-module
- **Phase** : Implémentation
- **Dernière session** : 2026-04-14 18:30

## Backlog actif
| # | Ticket | Priorité | Status |
|---|--------|----------|--------|
| 1 | Endpoint POST /auth/login | P0 | En cours |
| 2 | Guard JWT pour routes protégées | P0 | À faire |
| 3 | Tests unitaires auth | P0 | À faire |
| 4 | Refresh token endpoint | P1 | À faire |

## Décisions récentes
- JWT plutôt que sessions (stateless, scalable)
- Refresh tokens en base, pas en cookie

## Notes
- Le middleware CORS est déjà configuré
- Voir config dans src/config/auth.ts

Ajoutez cette instruction dans votre CLAUDE.md :

## Persistance
- Au démarrage : lire .claude/session.md
- En fin de session : mettre à jour session.md
  avec l'état courant, le backlog, et les décisions prises

3.3. La commande /autopilot

C'est la commande la plus utilisée dans mon lab, granit-golem, cas client multi-agent, timespot. Elle transforme Claude Code en agent autonome qui traite le backlog sans intervention.

.claude/commands/autopilot.md
# /autopilot - Cycle de maintenance autonome

## Instructions
Tu es en mode autonome. Exécute le workflow suivant en boucle :

1. **Lire** session.md pour connaître l'état courant
2. **Consulter** le backlog (tickets triés par priorité)
3. **Sélectionner** le ticket P0 le plus prioritaire
4. **Implémenter** en suivant TDD strict :
   - Écrire le test qui échoue (Red)
   - Écrire le code minimal pour passer (Green)
   - Refactorer si nécessaire
5. **Tester** : lancer la suite complète
6. **Commiter** : conventional commit, message descriptif
7. **Mettre à jour** session.md avec le travail effectué
8. **Répéter** avec le ticket suivant

## Contraintes
- Ne JAMAIS skipper les tests
- Si un test échoue, le fixer AVANT de continuer
- Commits atomiques (1 commit = 1 changement logique)
- /compact si le contexte dépasse 70%

## Arrêt
- Plus de tickets P0
- Erreur non résoluble
- Contexte à 90%

4. Semaines 2-4 : commandes personnalisées

Les commandes personnalisées sont des fichiers Markdown dans .claude/commands/. Le nom du fichier devient la slash command. C'est l'un des patterns les plus puissants que j'ai observés : chaque commande encode une procédure que Claude exécute de manière reproductible.

Les 3 commandes essentielles

/test-sweep qualité

Lance tous les tests, analyse les échecs, corrige automatiquement, produit un rapport.

# /test-sweep - Exécution et rapport de tests

## Instructions
1. Lancer TOUS les tests du projet
2. Analyser les résultats
3. Pour chaque échec :
   - Identifier la cause racine
   - Proposer un fix
   - Appliquer le fix
   - Re-lancer le test cible
4. Produire un rapport dans .claude/reports/
/triage organisation

Lit les tickets, les classe par priorité, P0 à P3, et met à jour le backlog dans session.md.

# /triage - Tri et priorisation

## Instructions
1. Lire tous les tickets (.claude/tickets/ ou issues)
2. Classer par priorité :
   - P0 : Bloquant, sécurité, perte de données
   - P1 : Bug fonctionnel, régression
   - P2 : Amélioration, refactoring
   - P3 : Nice-to-have, cosmétique
3. Mettre à jour session.md avec le backlog trié
/review review

Review structurée du diff courant avec checklist de vérification.

# /review - Code review structurée

## Instructions
1. Lire le diff (git diff main...HEAD)
2. Vérifier :
   - Tests présents et pertinents
   - Pas de any en TypeScript
   - Conventional commits respectés
   - Pas de secrets dans le code
3. Produire un rapport : OK / WARNING / BLOQUANT

Autres commandes utiles

Commande Usage Projets
/doc Génère la documentation technique d'un module granit-golem, timespot
/gitlab Opérations CI/CD, MR, pipeline, déploiement granit-golem, cas client multi-agent
/sprint-report Rapport de sprint avec métriques cas client multi-agent

5. Mois 2 : agents spécialisés

Les agents spécialisés sont des fichiers Markdown dans .claude/agents/ qui définissent un rôle, des compétences, et des règles spécifiques. Claude Code les utilise pour adapter son comportement selon le domaine.

Quand créer des agents

Je recommande les agents à partir de 3 domaines distincts dans le projet. Avant ça, un seul CLAUDE.md bien écrit suffit. Sur mes projets :

1-2 domaines

CLAUDE.md suffit. Pas besoin d'agents. Exemples : basalt-beholder (frontend seul), kotg (jeu de cartes).

3+ domaines

Les agents deviennent utiles. Exemples : granit-golem (Rust + TS + CI/CD + infra), cas client multi-agent (Angular + NestJS + specs + QA).

Template d'un agent

.claude/agents/senior-backend.md
# .claude/agents/senior-backend.md

## Rôle
Expert backend NestJS/TypeScript. Responsable de
l'implémentation des APIs, de la logique métier
et de la couche données.

## Compétences
- NestJS : modules, guards, interceptors, pipes
- TypeORM / Prisma : migrations, relations, queries
- Tests : Jest, supertest, fixtures

## Règles
- DDD strict : domain/ ne dépend de rien
- DTOs valides avec class-validator
- Pas de logique métier dans les controllers
- Coverage > 80% sur le domaine

## Workflow
1. Lire la spec dans .claude/inbox/backend/
2. Implémenter avec TDD
3. Écrire dans .claude/outbox/backend/ quand terminé

Exemple réel : granit-golem et ses 6 agents

Mon projet le plus avancé utilise 6 agents spécialisés. C'est le projet avec le meilleur ratio sessions/commits (1.13) et 0 rollbacks sur 552 commits.

Structure agents granit-golem
# granit-golem : 6 agents spécialisés

.claude/agents/
  senior-rust-dev.md       # 375 lignes - DDD, Axum, SQLx, Tokio
  senior-frontend-dev.md   # React, TypeScript, composants
  qa-tester.md             # Playwright, page objects, coverage
  pipeline-monitor.md      # GitLab CI, flaky tests, cache
  project-maestro.md       # Priorisation, dispatch, arbitrage
  devops-infra.md          # Docker, Traefik, monitoring

# Résultat mesure :
# - Ratio sessions/commits : 1.13 (quasi 1:1)
# - 552 commits en 2026
# - 0 rollbacks

6. Mois 3+ : MCP servers et plugins

Les MCP servers en bref

Les MCP, Model Context Protocol, servers exposent des outils externes à Claude Code via un protocole standardisé. Concrètement, ça permet à Claude Code d'interagir avec des systèmes externes, bases de données, APIs, outils de monitoring, directement depuis le terminal.

Configuration

~/.claude/.mcp.json
// ~/.claude/.mcp.json
{
  "summoner": {
    "command": "node",
    "args": ["~/lab/summoner/packages/mcp/dist/index.js"],
    "env": { "SUMMONER_URL": "http://localhost:7777" }
  },
  "grafana": {
    "command": "node",
    "args": ["~/lab/grafana-mcp/dist/index.js"],
    "env": { "GRAFANA_URL": "http://monitoring.local:3000" }
  }
}

// summoner : 40+ tools (projects, sessions, tasks, kanban)
//   -> Permet de lancer des sessions sur d'autres projets
//   -> Orchestration multi-projet depuis Claude Code

// grafana : dashboards, métriques, alertes
//   -> Vérification post-déploiement
//   -> Détection de régressions de latence

Exemples concrets de mon lab

Summoner - Orchestrateur

40+ outils pour gérer des projets, sessions et tâches. Permet à Claude Code de lancer des sessions sur d'autres projets, de consulter le kanban, et d'orchestrer du travail multi-projet.

projects sessions tasks kanban workflows

Grafana - Monitoring

Accès aux dashboards et métriques depuis Claude Code. Permet de vérifier les performances après un déploiement et de détecter les régressions de latence sans quitter le terminal.

dashboards métriques alertes logs

Plugins globaux

5 plugins sont actifs en permanence dans mon lab et s'appliquent à tous les projets :

rust-analyzer-lsp

Navigation et diagnostics Rust avant compilation

typescript-lsp

Détection des erreurs de types avant exécution

playwright

Screenshots, navigation, tests E2E depuis Claude Code

superpowers

Skills avancés : TDD, debugging, brainstorming, plans

frontend-design

Design frontend production-grade, pas du générique

7. Pipeline qualité

La qualité ne se décrète pas, elle se mesure et s'automatise. J'ai construit un pipeline complet dans mon lab que je détaille dans la page Pipeline qualité. Voici l'essentiel :

1
Pre-commit Lint + format + typecheck
2
Tests Unit + integration + E2E
3
SAST Analyse statique sécurité
4
Audit Dependencies + coverage
5
Deploy CI/CD + monitoring

Les hooks Claude Code permettent d'insérer des contrôles automatiques dans ce pipeline. Par exemple, auto-formater après chaque écriture de fichier, ou logger chaque commande Bash exécutée.

Exemple de hooks
// .claude/settings.local.json - Hooks
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\"",
        "description": "Auto-format après chaque écriture"
      }
    ],
    "Stop": [
      {
        "command": "date '+%Y-%m-%d %H:%M' >> .claude/session-timestamps.log",
        "description": "Tracker les fins de session"
      }
    ]
  }
}

8. Métriques de succès

J'ai mesuré l'efficacité de Claude Code sur mes projets. Voici les chiffres réels, pas des estimations, des données extraites de 10 581 sessions.

Ratio sessions/commits

C'est mon indicateur principal : combien de sessions Claude Code faut-il pour produire un commit ? Plus le ratio est bas, plus le workflow est efficace.

Projet Sessions Commits Ratio Contexte
granit-golem 622 552 1.13 CLAUDE.md 757 lignes, 6 agents
comrenov 635 269 2.36 11 agents, pipeline saga
cloud 831 159 5.23 IaC complexe, debug Ansible
siliceum-website 1 364 83 16.4 Refonte design - itération intensive

Coverage par projet

granit-golem
59% coverage
comrenov
47% coverage
iolite-ifrit
35% coverage

Corrélation CLAUDE.md et efficacité

Plus le CLAUDE.md est structuré et détaillé, meilleur est le ratio sessions/commits. Ce n'est pas une question de taille brute, c'est une question de précision des instructions.

757 lignes (granit-golem)
Ratio 1.13 - maximum d'efficacité
136 lignes (comrenov)
Ratio 2.36 - très bon
0 lignes (tordu-jardin)
416 sessions, 134 commits - pas de guide

9. Erreurs à éviter

J'ai fait toutes ces erreurs. Voici comment les éviter.

×

Commencer par le multi-agent

Ce que j'ai fait : Sur ce cas client multi-agent, j'ai configuré 4 agents, PMO, Tech, QA, Orchestrateur, dès le premier jour. Résultat : overhead énorme, communication inter-agents cassée, 3 jours perdus.
Ce qu'il fallait faire : Commencer avec un seul CLAUDE.md, ajouter des agents uniquement quand 3+ domaines sont clairement identifiés et que le mono-agent montre ses limites.
×

Utiliser /autopilot sans session.md

Le problème : Sans session.md, Claude Code ne sait pas où il en est. Il peut réimplémenter un ticket déjà fait, ou partir dans une direction opposée à la session précédente.
La solution : Toujours avoir un session.md à jour avant de lancer /autopilot. C'est la première instruction du fichier autopilot.md : "Lire session.md".
×

Skipper les quality gates

Le piège : "Le build passe, donc ça marche." Sur granit-golem, un build Rust OK masquait un bug de pattern matching qui n'a été attrapé que par les tests.
La règle : Build OK n'est pas test OK. Toujours lancer les tests avant de commit. Mettre la règle explicitement dans le CLAUDE.md.
×

Laisser le CLAUDE.md grossir sans structure

Le symptôme : Un CLAUDE.md de 500 lignes où les règles se contredisent, les sections sont redondantes, et Claude ne sait plus quoi prioriser.
La solution : Sections claires, Stack, Commandes, Conventions, Règles, Workflow. Factoriser les instructions répétées dans des agents ou des fichiers dédiés.

10. Checklist de maturité

Où en êtes-vous ? Cette checklist progressive correspond exactement aux étapes de ce guide.

1

Débutant

Jour 1
2

Opérationnel

Semaine 1
3

Productif

Mois 1
4

Avancé

Mois 2-3
5

Industriel

Mois 3+