Onboarding développeur avec Claude Code : passer de plusieurs mois à 2 semaines

L’onboarding d’un nouvel ingénieur ne se limite pas à fournir un ordinateur. Il s’agit d’amener une personne de “je peux ouvrir le dépôt” à “je peux livrer un petit changement, vérifiable et conforme aux règles de l’équipe”. Les vrais freins sont souvent les questions de setup répétées, une grande base de code, des critères de revue flous et du savoir implicite non documenté.

Claude Code ne doit pas remplacer le mentor. Son rôle le plus utile est de créer un cadre sûr : instructions dans CLAUDE.md, script de setup reproductible, règles de permissions, checklist de première tâche, modèle de PR et lecture claire de la CI. En termes simples, la base de code est l’ensemble du code source, un PR est une demande de revue, et la CI est le système qui lance automatiquement tests et builds avant merge.

Comme Claude Code évolue, appuyez-vous sur la documentation officielle : Claude Code setup, CLI reference, memory et settings. Pour aller plus loin, consultez codebase navigation, code review et CLAUDE.md templates.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

1. Commencer par CLAUDE.md

CLAUDE.md est la mémoire de projet que Claude Code lit comme consigne partagée. Pour l’onboarding, écrivez des commandes, des limites et des règles d’escalade plutôt que des principes vagues.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

Le but n’est pas de faire de Claude Code un senior magique. Le but est de réduire le périmètre pour que le nouveau membre apprenne les standards de l’équipe tout en produisant un diff relisible.

2. Rendre le setup reproductible

Le premier blocage concerne souvent la version de Node, les dépendances, les variables locales, les données de test et la commande qui prouve que tout fonctionne. Un script transforme cela en chemin clair.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

Dans un projet npm classique, ce script est directement testable. Si vous utilisez pnpm, Yarn, Docker Compose ou Makefile, remplacez les commandes, mais gardez la même structure : setup, vérification, puis explication par Claude Code.

3. Encadrer les permissions

Claude Code peut lire des fichiers, rechercher dans le code, lancer des commandes et éditer si vous l’autorisez. C’est utile pour l’onboarding, mais risqué si .env est lu, si une commande destructive est lancée ou si le diff devient trop large.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

La première semaine, privilégiez lecture, recherche, diff, log et tests. Les éditions peuvent demander confirmation. Push, commit, deploy, publication et secrets restent hors du parcours.

4. Fixer la checklist du premier PR

Le premier PR est un exercice d’apprentissage. Bons candidats : ajouter un test sur un comportement existant, corriger un petit texte d’interface, améliorer un message d’erreur ou supprimer une duplication dans un dossier. Mauvais candidats : authentification, facturation, permissions, migrations, formatage global et mises à jour de dépendances.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

Ce flux couvre plusieurs cas concrets : setup autonome, lecture de la base de code, choix de première tâche et auto-revue avant PR.

5. Standardiser la demande de revue

Beaucoup de premiers PR reviennent parce que le reviewer ne voit pas ce qui a été vérifié. Le modèle force l’intention, la sécurité, la vérification et le focus de revue.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

Cela aide aussi le mentor : il voit si la revue porte sur le design, les tests, le comportement, les captures ou la compréhension du processus.

6. Montrer la CI dès le premier jour

CI signifie intégration continue. C’est le système qui exécute les vérifications avant merge. Un nouvel ingénieur doit apprendre à reproduire localement un échec, pas seulement voir un statut rouge.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Même avec un autre outil de CI, documentez les mêmes commandes. Demandez ensuite à Claude Code de lire un log en échec et de proposer la première commande locale à lancer.

Pièges courants

Premier piège : déléguer le jugement métier à Claude Code. Il peut inférer depuis le code et l’historique, mais les engagements clients, exceptions et contraintes de conformité restent humains.

Deuxième piège : choisir un premier PR trop grand. Visez moins de 150 lignes quand c’est possible, avec tests et rollback simple.

Troisième piège : exposer des secrets. Refusez .env, credentials et fichiers de production dans settings, et utilisez seulement des valeurs d’exemple dans les docs.

Quatrième piège : interdire les questions humaines. “Demande d’abord à Claude” ne fonctionne que si les deux premières semaines contiennent des points mentor fréquents.

CTA

Pour une équipe, standardisez ensemble CLAUDE.md, permissions, preuves de PR et CI. En solo, commencez par la cheatsheet gratuite. Pour des modèles réutilisables, consultez ClaudeCodeLab products. Pour formation, permissions et déploiement dans un dépôt réel, utilisez Claude Code training and consultation.

Résultat après essai

Dans les travaux d’articles ClaudeCodeLab et de petites corrections de code, l’amélioration la plus nette est venue du fait d’écrire les règles avant de demander l’implémentation. Avec CLAUDE.md, des permissions limitées, des commandes de vérification et un modèle de PR, le diff était beaucoup plus simple à relire. Quand Claude Code se trompait, les hypothèses et commandes conservées rendaient l’erreur facile à localiser.