Configurer un environnement de développement fiable avec Claude Code

Un nouvel ordinateur ou un dépôt fraîchement cloné ne devrait pas bloquer une demi-journée avant le premier changement utile. Les problèmes reviennent toujours: mauvaise version de Node.js, mélange entre npm et pnpm, .env incomplet, volumes Docker obsolètes et commandes locales absentes de la documentation. Claude Code accélère ces tâches, mais il doit travailler dans un cadre reproductible.

L’objectif n’est pas de laisser l’agent tout faire. L’objectif est que chaque développeur et chaque session Claude Code utilisent les mêmes instructions, le même gestionnaire de paquets, les mêmes règles pour les secrets et les mêmes commandes de vérification.

Gardez les sources officielles comme référence: Claude Code setup, settings, permissions et hooks. Pour continuer sur ClaudeCodeLab, lisez aussi démarrer avec Claude Code, bonnes pratiques CLAUDE.md et guide des hooks.

flowchart TD
  A["Vérifier les outils"] --> B["Figer Node et le gestionnaire de paquets"]
  B --> C["Créer dépendances et .env.example"]
  C --> D["Écrire les règles dans CLAUDE.md"]
  D --> E["Limiter les permissions dans settings.json"]
  E --> F["Bloquer les commandes dangereuses par hooks"]
  F --> G["Lancer doctor, env check et tests"]

Règles de base

Traitez l’environnement de développement comme du code de production. Une règle importante doit être versionnée. Un secret réel ne doit pas être lu par l’agent. Une commande qui peut supprimer des données ou publier du code doit demander une validation humaine.

Zone	Fichier ou commande	Rôle
Runtime	.nvmrc, packageManager, Corepack	Évite les écarts de Node et pnpm
Secrets	.env.example, .gitignore, permissions.deny	Garde les clés hors des prompts et commits
Mémoire projet	CLAUDE.md	Charge les consignes à chaque session
Permissions	.claude/settings.json	Contrôle lectures, Bash et mode par défaut
Hooks	.claude/hooks/*	Applique des garde-fous déterministes
Vérification	doctor, check:env, test	Remplace l’impression par une preuve

Script de bootstrap

Ce script cible Git Bash, WSL, macOS ou Linux. Il crée un petit projet TypeScript, valide les variables d’environnement, fixe pnpm, bloque la lecture des secrets et ajoute un hook PreToolUse.

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Node.js est requis"; exit 1; }
command -v claude >/dev/null || { echo "Claude Code CLI est requis"; exit 1; }

corepack enable
corepack prepare pnpm@9.15.4 --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@9.15.4",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Consignes du projet

## Configuration de l'environnement
- Utilise la version de Node indiquée dans `.nvmrc`.
- Utilise pnpm via Corepack. Ne bascule pas vers npm ou yarn.
- Copie `.env.example` vers `.env` en local, puis modifie les valeurs à la main.
- Ne lis, n'affiche et ne commit jamais `.env` ou des fichiers secrets.
- Avant de modifier le code, lance `pnpm run doctor` et `pnpm run check:env`.
- Après une modification, lance le test le plus ciblé et note le résultat.

## Règles de travail
- Commence par explorer et proposer un plan court.
- N'exécute aucune commande destructive ni déploiement sans accord humain explicite.
- Garde les changements de setup dans des fichiers reproductibles, pas seulement dans l'historique du terminal.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Commande dangereuse bloquée. Une personne doit vérifier l'objectif et la cible."
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

Sous Windows natif, vérifiez d’abord les outils:

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

Si pnpm --version échoue, corrigez Node et Corepack avant de toucher au dépôt. Si claude doctor signale un proxy, un certificat ou une authentification, conservez le message exact et demandez un diagnostic avec cette contrainte.

Prompt recommandé

claude -p "
Audite et complète la configuration de l'environnement de développement de ce dépôt.

Règles:
- Ne lis pas .env, .env.* ni les fichiers sous secrets/
- Respecte packageManager; ne remplace pas pnpm par npm ou yarn
- Ne supprime pas de volumes Docker et n'exécute pas git push

Autorisé:
- Lire README, package.json, CLAUDE.md et .claude/settings.json
- Exécuter pnpm install, pnpm run doctor, pnpm run check:env et pnpm test

Retourne un reçu court avec les commandes lancées, fichiers modifiés, échecs et étapes manuelles restantes.
"

Cas d’usage

Cas	Bénéfice
Prototype SaaS	Ajoute PostgreSQL et Redis avec Docker Compose sans perdre la reproductibilité
Dépôt d’équipe	Claude Code lit les consignes, exécute les checks autorisés et améliore l’onboarding
Site de contenu ou produit	Protège CTA, événements analytics, OGP et pages sensibles pour AdSense
Outil interne	Standardise seed de base, files d’attente, mocks et tests

Pour Docker, continuez avec Docker Compose. Pour le travail d’équipe, consultez collaboration Claude Code. Pour l’intégration continue, reliez ces commandes à CI/CD.

Échecs à éviter

Ne mélangez pas les gestionnaires de paquets. Si pnpm-lock.yaml existe, interdisez npm install. Écrivez cette règle dans CLAUDE.md et gardez packageManager dans package.json.

Ne laissez pas Claude Code lire .env. Le fichier à relire est .env.example; les valeurs réelles restent locales. Utilisez ensemble .gitignore et permissions.deny.

Attention aux volumes Docker. Un ancien volume peut masquer une migration correcte. Avant toute suppression, demandez à Claude Code d’expliquer la cible et le risque.

Évitez bypassPermissions sur la machine principale. Réservez-le aux conteneurs ou machines virtuelles isolées. Relisez aussi les hooks des dépôts non fiables avant de démarrer une session.

Checklist de reproductibilité

• claude --version et claude doctor passent
• .nvmrc ou .node-version existe
• package.json contient packageManager
• Un seul lockfile est présent
• .env.example est à jour et .env est ignoré
• CLAUDE.md décrit setup, interdits et vérifications
• .claude/settings.json bloque secrets, git push et commandes destructives
• Le reçu final contient commandes et résultats

CTA et résultat

Un environnement local instable peut casser liens d’achat, formulaires, analytics ou pages avec annonces. Pour transformer ce flux en système réutilisable, commencez par l’antisèche gratuite, explorez les produits ou organisez la pratique en équipe via la formation.

J’ai testé ce flux en créant le projet minimal, en installant les dépendances, en copiant .env.example, puis en lançant pnpm run doctor, pnpm run check:env et pnpm test. Les protections les plus utiles ont été l’interdiction de lire .env et le hook bloquant git push ou les commandes destructives. Dans le travail réel de Masa, les échecs de setup viennent surtout d’hypothèses non écrites.