Configuration de Claude Code dans VS Code : créer un starter CLAUDE.md multi-stack modulaire

La plupart des configurations Claude Code commencent par un seul fichier CLAUDE.md qui essaie de tout couvrir. Cela fonctionne bien pour les petits projets mono-stack. Mais si vous travaillez sur plusieurs stacks technologiques, ce fichier grossit en un amas d’instructions surchargé qui gaspille du contexte et dilue les directives dont Claude a réellement besoin pour la tâche en cours.

Dans ce tutoriel, vous allez construire une configuration Claude Code modulaire pour VS Code qui s’adapte à la stack sur laquelle vous travaillez. Au lieu d’un seul fichier massif, vous créerez un routeur CLAUDE.md léger soutenu par des règles conditionnelles, des subagents spécialisés, des hooks d’automatisation et des templates de prompts réutilisables. À la fin, vous disposerez d’un répertoire .claude/ portable que vous pourrez installer dans n’importe quel projet.

Le starter complet est disponible sur InkByteStudio/claude-code-vscode-multistack-starter. Vous pouvez suivre le tutoriel étape par étape ou cloner le dépôt et l’utiliser comme référence.

Ce que vous allez construire

Voici la structure complète que vous allez créer :

.claude/
  rules/
    common.md          # unconditional - always loaded
    testing.md         # unconditional
    git.md             # unconditional
    security.md        # unconditional
    laravel.md         # conditional - paths frontmatter
    react-next.md      # conditional
    python-fastapi.md  # conditional
    node-express.md    # conditional
    docker-devops.md   # conditional
    sql.md             # conditional
  agents/
    laravel-architect.md
    react-ui.md
    python-api.md
    node-backend.md
    devops-reviewer.md
    sql-investigator.md
  hooks/
    session-start.sh
    post-edit-check.sh
  prompts/
    bugfix.md
    refactor.md
    code-review.md
    onboarding.md
  settings.json
CLAUDE.md
scripts/
  detect-stack.sh
  install-local.sh

L’architecture suit un modèle à deux niveaux. Les règles inconditionnelles (common, testing, git, security) se chargent à chaque session et fournissent des directives de base. Les règles conditionnelles par stack utilisent le frontmatter paths pour se charger uniquement lorsque Claude lit ou modifie des fichiers correspondant à des patterns glob spécifiques. Cela signifie qu’une session Python ne voit que les règles Python, une session Laravel ne voit que les règles Laravel, et le contexte reste léger.

Pourquoi le modulaire l’emporte sur le monolithique

Un CLAUDE.md monolithique pour un projet à six stacks peut faire 400 à 600 lignes. Dans une session où vous ne modifiez que des fichiers Python, 80 % de ces instructions sont du bruit. Le chargement conditionnel change l’équation :

• Monolithique : environ 400 lignes chargées à chaque session
• Modulaire (session Python uniquement) : environ 80 lignes (règles partagées plus python-fastapi.md)
• Modulaire (session Laravel plus Docker) : environ 120 lignes (règles partagées plus laravel.md plus docker-devops.md)

Moins de bruit signifie un meilleur signal, ce qui signifie des réponses plus précises. Cela signifie aussi que chaque responsable de stack maintient son propre fichier au lieu que tout le monde se batte sur un seul document partagé.

Étape 1 : Initialiser Claude Code dans VS Code

Ouvrez votre projet dans VS Code et assurez-vous que l’extension Claude Code est installée et authentifiée. Exécutez la commande /init depuis le chat Claude Code pour générer un CLAUDE.md par défaut à la racine de votre projet.

Le fichier par défaut sera un point de départ basique. Vous le remplacerez entièrement à l’étape suivante, mais exécuter /init d’abord garantit que Claude Code reconnaît le projet et que le répertoire .claude/ est créé.

Vous devriez maintenant avoir un fichier CLAUDE.md à la racine de votre projet et un répertoire .claude/.

Étape 2 : Créer le routeur CLAUDE.md

Remplacez le CLAUDE.md par défaut par un guide de projet léger qui agit comme un routeur. Au lieu de contenir toutes vos règles, il décrit le projet à haut niveau et importe les règles inconditionnelles en utilisant la syntaxe @.

Créez CLAUDE.md à la racine de votre projet :

# Claude Code Project Guide

This repository is a multi-stack starter configuration for Claude Code in VS Code.

## How this repo works

- **Unconditional rules** in `.claude/rules/` (common, testing, git, security)
  load every session.
- **Stack-specific rules** in `.claude/rules/` use `paths` frontmatter to load
  only when you touch matching files.
- **Subagents** in `.claude/agents/` handle focused tasks like architecture
  review, UI work, or SQL investigation.
- **Hooks** in `.claude/settings.json` run lightweight automation on session
  start and after edits.
- **Prompts** in `.claude/prompts/` provide reusable workflow templates for
  common tasks.

## Stack detection

Identify the active stack from the repository structure before making changes.

Common stack indicators:
- Laravel/PHP: `composer.json`, `artisan`, `routes/`, `app/`, `config/`
- React/Next.js: `package.json`, `next.config.*`, `app/`, `pages/`,
  `src/components/`
- Python/FastAPI: `pyproject.toml`, `requirements.txt`, `app/`, `main.py`
- Node/Express: `package.json`, `server.js`, `src/`, `routes/`
- Docker/DevOps: `Dockerfile`, `docker-compose.yml`, `.github/workflows/`
- SQL/Data: migration files, schema dumps, reporting queries, ETL scripts

## Default behavior

- Explain the plan before major edits.
- Prefer the smallest useful diff.
- Reuse existing patterns before adding new abstractions.
- Do not add dependencies unless there is a clear reason.
- Update docs when behavior changes.

## Imported rules (always loaded)

@.claude/rules/common.md
@.claude/rules/testing.md
@.claude/rules/git.md
@.claude/rules/security.md

## Prompt helpers (available on demand)

@.claude/prompts/bugfix.md
@.claude/prompts/refactor.md
@.claude/prompts/code-review.md
@.claude/prompts/onboarding.md

Vous devriez maintenant avoir un CLAUDE.md propre et lisible qui décrit la structure du projet et importe les règles partagées sans contenir de détails spécifiques à une stack.

Étape 3 : Ajouter les règles inconditionnelles

Créez quatre fichiers de règles dans .claude/rules/ qui se chargent à chaque session. Ils couvrent les préoccupations transversales qui s’appliquent quelle que soit la stack sur laquelle vous travaillez.

Créez .claude/rules/common.md :

# Common Rules

- Match the project's existing naming, folder, and formatting conventions.
- Prefer explicit code over clever code.
- Do not rewrite unrelated files.
- Preserve comments that explain business logic.
- Keep functions and classes cohesive and focused.
- Prefer configuration over hardcoding where the project already supports it.
- When changing behavior, note user-visible impact.
- Use 2-space indentation for JS/TS/JSON, 4-space for Python/PHP unless the
  project uses something else.
- Follow the existing import style and module organization.

Créez .claude/rules/testing.md :

# Testing Rules

- Run only the most relevant tests first.
- Prefer one file, one suite, or one command over full-suite runs.
- If adding logic, add or update tests when the project already has test
  coverage in that area.
- If tests are missing, suggest the smallest useful test addition.
- Report what was run, what passed, and what was not verified.
- Use the stack-appropriate test runner:
  - PHP/Laravel: `php artisan test --filter=...` or `./vendor/bin/phpunit`
  - React/Next.js: `npm test -- <name>` or `npx vitest run <name>`
  - Python: `pytest -k ...` or `uv run pytest`
  - Node/Express: `npm test -- <name>` or `npm run test:unit`

Créez .claude/rules/git.md :

# Git Rules

- Keep changes scoped to the task.
- Summarize changed files in plain language.
- Use conventional commit style: `type(scope): description`
  - Types: feat, fix, refactor, test, docs, chore, ci, perf
- Call out migrations, config changes, and any manual deployment steps.
- Suggest focused branch names: `type/short-description`
  (e.g., `fix/auth-redirect`, `feat/user-export`).
- Never force-push to main or shared branches without explicit approval.

Créez .claude/rules/security.md :

# Security Rules

- Never expose secrets, tokens, or private keys in code or logs.
- Never commit `.env`, credentials, or key files.
- Avoid logging sensitive values (passwords, tokens, PII).
- Validate input boundaries on API and DB changes.
- Sanitize user input before rendering (prevent XSS) or querying
  (prevent SQL injection).
- Flag auth, permission, or data exposure risks clearly.
- For destructive shell or SQL operations, explain scope before execution.
- Run `npm audit`, `pip audit`, or `composer audit` when adding dependencies.

Ces quatre fichiers n’ont pas de frontmatter paths, ce qui signifie que Claude les charge de manière inconditionnelle à chaque session.

Vous devriez maintenant avoir quatre fichiers de règles dans .claude/rules/ couvrant les standards de codage, la philosophie de test, les conventions git et les garde-fous de sécurité.

Étape 4 : Ajouter les règles conditionnelles par stack

Les règles conditionnelles sont l’endroit où l’approche modulaire porte ses fruits. Chaque fichier de règle de stack inclut un bloc paths dans son frontmatter YAML qui indique à Claude de le charger uniquement lors de la lecture ou de la modification de fichiers correspondant à ces patterns glob.

Voici le fichier de règles Laravel complet comme exemple principal. Créez .claude/rules/laravel.md :

---
paths:
  - "**/*.php"
  - "**/routes/**"
  - "**/app/**"
  - "**/database/migrations/**"
  - "**/resources/views/**"
---

# Laravel / PHP Guidance

## Architecture
- Prefer existing Laravel conventions before custom patterns.
- Keep controllers thin.
- Put reusable business logic in services, actions, or domain classes
  if that pattern already exists.
- Use Form Requests for request validation when appropriate.
- Prefer Eloquent scopes, relationships, and query builders over
  duplicated query logic.

## Database
- Treat migrations as review-sensitive changes.
- Prefer additive schema changes unless a breaking change is intentional.
- For large updates, think about indexing, chunking, locking, and
  rollback impact.

## Commands
- `php artisan test --filter=...`
- `php artisan route:list`
- `php artisan migrate --pretend`
- `composer test`
- `./vendor/bin/phpunit`

## Review checklist
- Validation correct?
- Auth/authorization preserved?
- N+1 or query performance issues?
- Migration safety reviewed?
- API response shape consistent?

Créez maintenant les cinq fichiers de règles de stack restants. Chacun suit le même schéma : le frontmatter paths en haut, puis les directives spécifiques à la stack.

Créez .claude/rules/react-next.md avec ces paths :

---
paths:
  - "**/*.tsx"
  - "**/*.jsx"
  - "**/components/**"
  - "**/pages/**"
  - "**/next.config.*"
---

Incluez des directives sur la conception de composants, la gestion d’état, les frontières serveur/client de Next.js, les conventions de style et une checklist de revue couvrant l’accessibilité, les états de chargement et la justesse des types.

Créez .claude/rules/python-fastapi.md avec ces paths :

---
paths:
  - "**/*.py"
  - "**/requirements*.txt"
  - "**/pyproject.toml"
---

Incluez des directives sur la conception d’API, la validation, les patterns asynchrones et une checklist de revue couvrant les type hints, l’alignement des schémas et la gestion des erreurs.

Créez .claude/rules/node-express.md avec ces paths :

---
paths:
  - "**/server/**"
  - "**/routes/**/*.js"
  - "**/routes/**/*.ts"
  - "**/middleware/**"
  - "**/server.js"
  - "**/app.js"
---

Incluez des directives sur la structure des routes, les middleware, la gestion des erreurs et une checklist de revue couvrant la validation, l’authentification et la sécurité des logs.

Créez .claude/rules/docker-devops.md avec ces paths :

---
paths:
  - "**/Dockerfile*"
  - "**/docker-compose*.yml"
  - "**/compose*.yml"
  - "**/.github/workflows/**"
  - "**/nginx/**"
---

Incluez des directives sur les modifications de conteneurs, les pipelines CI/CD, la sécurité pour les changements impactant la production et une checklist de revue couvrant la reproductibilité des builds, la gestion des secrets et les plans de rollback.

Créez .claude/rules/sql.md avec ces paths :

---
paths:
  - "**/*.sql"
  - "**/migrations/**"
  - "**/seeds/**"
  - "**/seeders/**"
---

Incluez des directives sur la conception de requêtes, la sécurité des instructions UPDATE et DELETE, les considérations de performance et une checklist de revue couvrant la gestion des null, la duplication de jointures et la stratégie de rollback.

Vous devriez maintenant avoir six fichiers de règles conditionnelles dans .claude/rules/, chacun avec un frontmatter paths qui limite son chargement.

Étape 5 : Créer les subagents

Les subagents sont des agents spécialisés définis dans .claude/agents/ avec leurs propres system prompts, accès aux outils et sélection de modèle. Ils sont utiles pour les tâches multi-étapes où une perspective ciblée est bénéfique.

Créez .claude/agents/laravel-architect.md :

---
name: laravel-architect
description: Laravel architecture specialist for Eloquent models, migrations,
  API resources, Form Requests, service patterns, and routing.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
maxTurns: 25
---

You are a Laravel-focused engineering subagent.

## Priorities
- Follow Laravel conventions already present in the repo.
- Keep controllers thin. Push logic into services, actions, or domain classes.
- Recommend safe migration patterns. Prefer additive schema changes.
- Call out validation, auth, and query performance risks.
- Prefer focused diffs and small follow-up steps.

## When reviewing code
- Check for N+1 queries and suggest eager loading where needed.
- Verify Form Request validation covers edge cases.
- Confirm authorization checks are in place.
- Look for missing indexes on frequently queried columns.

## When writing code
- Use Eloquent relationships and scopes over raw queries.
- Follow existing factory and seeder patterns for test data.
- Keep route definitions clean and grouped logically.
- Use Laravel's built-in helpers before adding custom utilities.

Créez les cinq agents restants dans .claude/agents/ en suivant le même schéma :

• react-ui.md — Spécialiste UI React et Next.js. Focus sur la structure des composants, le flux d’état, l’accessibilité et le style. Définissez model: sonnet, maxTurns: 20.
• python-api.md — Spécialiste Python et FastAPI. Focus sur la conception d’endpoints, les modèles Pydantic, les patterns asynchrones et la sûreté des types. Définissez model: sonnet, maxTurns: 25.
• node-backend.md — Spécialiste Node.js et Express. Focus sur les middleware, la gestion des erreurs, l’organisation des routes et les patterns asynchrones. Définissez model: sonnet, maxTurns: 25.
• devops-reviewer.md — Spécialiste Docker et DevOps. Focus sur les Dockerfiles, les pipelines CI/CD, la revue d’infrastructure et la sécurité. Définissez model: sonnet, maxTurns: 20.
• sql-investigator.md — Spécialiste SQL et bases de données. Focus sur l’optimisation de requêtes, la revue de schéma, la sécurité des migrations et l’analyse de données. Définissez model: sonnet, maxTurns: 20.

Chaque agent inclut un champ description qui indique à Claude quand suggérer de lui déléguer une tâche. Le champ tools contrôle les outils auxquels l’agent a accès. Le champ maxTurns limite le nombre d’étapes que l’agent peut effectuer avant de rendre le contrôle.

Vous devriez maintenant avoir six fichiers d’agents dans .claude/agents/, un par stack.

Étape 6 : Configurer les hooks

Les hooks sont des scripts shell légers qui s’exécutent automatiquement à des moments spécifiques du cycle de vie de Claude Code. Créez la configuration des hooks et les scripts.

Créez .claude/settings.json :

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-check.sh",
            "timeout": 60
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

La variable $CLAUDE_PROJECT_DIR se résout vers la racine du projet, donc les chemins fonctionnent quel que soit le répertoire de travail courant.

Créez .claude/hooks/session-start.sh :

#!/usr/bin/env bash
# Runs on SessionStart via .claude/settings.json
# Detects active stacks and checks environment readiness.

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DETECT_SCRIPT="$SCRIPT_DIR/../../scripts/detect-stack.sh"

if [ -x "$DETECT_SCRIPT" ] || [ -f "$DETECT_SCRIPT" ]; then
  stacks_json=$(bash "$DETECT_SCRIPT" 2>/dev/null || echo '{"stacks": []}')
  stacks_list=$(echo "$stacks_json" | grep -o '"[^"]*"' \
    | grep -v stacks | grep -v detected_at | tr -d '"' \
    | paste -sd', ' -)
  if [ -n "$stacks_list" ]; then
    echo "Detected stacks: $stacks_list"
  else
    echo "No specific stack detected. Check project files manually."
  fi
else
  echo "No specific stack detected. Check project files manually."
fi

# Check for missing .env
if [ -f .env.example ] && [ ! -f .env ]; then
  echo "Warning: .env.example exists but .env is missing. Copy and configure it."
fi

exit 0

Créez .claude/hooks/post-edit-check.sh :

#!/usr/bin/env bash
# Runs after Edit/Write tool use via .claude/settings.json
# Performs lightweight lint checks based on the edited file type.

INPUT=$(cat)
if command -v jq &>/dev/null; then
  FILE=$(echo "$INPUT" | jq -r '.file_path // empty' 2>/dev/null)
else
  FILE=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
    | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi

if [ -z "$FILE" ]; then
  exit 0
fi

EXT="${FILE##*.}"

case "$EXT" in
  php)
    if command -v php &>/dev/null; then
      php -l "$FILE" 2>&1 || true
    fi
    ;;
  py)
    if command -v ruff &>/dev/null; then
      ruff check "$FILE" 2>&1 || true
    elif command -v python3 &>/dev/null; then
      python3 -m py_compile "$FILE" 2>&1 || true
    fi
    ;;
  ts|tsx|js|jsx)
    if command -v npx &>/dev/null; then
      npx eslint "$FILE" --no-error-on-unmatched-pattern 2>&1 || true
    fi
    ;;
  sql)
    echo "SQL file edited: $FILE -- review before executing."
    ;;
esac

exit 0

Rendez les deux scripts de hooks exécutables :

chmod +x .claude/hooks/session-start.sh .claude/hooks/post-edit-check.sh

Vous devriez maintenant avoir deux scripts de hooks et un settings.json qui les connecte aux événements de cycle de vie SessionStart et PostToolUse.

Étape 7 : Construire le script de détection de stack

Le script de détection de stack analyse les fichiers marqueurs à la racine du projet et produit un objet JSON listant les stacks détectées. Le hook de démarrage de session appelle ce script pour donner à Claude un contexte immédiat sur le projet.

Créez scripts/detect-stack.sh :

#!/usr/bin/env bash
# Standalone stack detection script.
# Outputs detected stacks as JSON for use by other tools.

stacks=()

{ [ -f artisan ] || [ -f composer.json ]; } && stacks+=("laravel")
{ [ -f next.config.js ] || [ -f next.config.mjs ] || [ -f next.config.ts ]; } \
  && stacks+=("react-next")
[ -f package.json ] && grep -q '"react"' package.json 2>/dev/null \
  && stacks+=("react")
{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } \
  && stacks+=("python-fastapi")
[ -f package.json ] && { [ -f server.js ] || [ -f app.js ]; } \
  && stacks+=("node-express")
{ [ -f Dockerfile ] || [ -f docker-compose.yml ] || [ -f compose.yml ]; } \
  && stacks+=("docker-devops")

# Check for SQL-heavy projects
sql_count=$(find . -maxdepth 3 -name "*.sql" 2>/dev/null | head -5 | wc -l)
[ "$sql_count" -gt 0 ] && stacks+=("sql")

# Output as JSON
json="["
for i in "${!stacks[@]}"; do
  [ "$i" -gt 0 ] && json+=","
  json+="\"${stacks[$i]}\""
done
json+="]"

echo "{\"stacks\": $json, \"detected_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

Rendez-le exécutable :

chmod +x scripts/detect-stack.sh

Voici comment le script associe les fichiers marqueurs aux identifiants de stack :

ID de stack	Fichiers marqueurs	Logique de détection
laravel	artisan, composer.json	L’un des fichiers existe
react-next	next.config.js, .mjs, .ts	N’importe quel fichier de config existe
react	package.json avec "react"	React dans les dépendances
python-fastapi	pyproject.toml, requirements.txt	L’un des fichiers existe
node-express	package.json + server.js/app.js	Fichier package plus point d’entrée
docker-devops	Dockerfile, docker-compose.yml, compose.yml	N’importe quel fichier de config existe
sql	Fichiers *.sql jusqu’à 3 niveaux	Au moins un fichier SQL trouvé

L’exécution du script produit une sortie comme celle-ci :

{
  "stacks": ["laravel", "docker-devops", "sql"],
  "detected_at": "2026-04-01T12:00:00Z"
}

Vous devriez maintenant avoir un script de détection de stack fonctionnel qui produit du JSON propre.

Étape 8 : Ajouter les templates de prompts

Les templates de prompts sont des workflows réutilisables stockés dans .claude/prompts/. Ils sont disponibles à la demande lorsque vous avez besoin d’une approche structurée pour une tâche courante.

Créez .claude/prompts/bugfix.md :

# Bugfix Workflow

Use this prompt when diagnosing and fixing a bug.

## Steps

1. **Describe the bug**: What is the expected behavior vs. actual behavior?
2. **Reproduce**: Find or write a minimal reproduction. If tests exist,
   write a failing test first.
3. **Diagnose**: Trace the code path. Check logs, error messages, and recent
   changes. Narrow down to the root cause before proposing a fix.
4. **Fix**: Apply the smallest change that addresses the root cause.
   Do not refactor unrelated code.
5. **Verify**: Run the failing test (or the narrowest relevant test suite)
   to confirm the fix. Run lint and typecheck.
6. **Document**: Note what caused the bug, what the fix does, and any
   follow-up work needed.

## Checklist before committing
- [ ] Root cause identified (not just symptoms addressed)
- [ ] Fix is scoped to the bug (no unrelated changes)
- [ ] Test covers the failure case
- [ ] Existing tests still pass
- [ ] No regressions introduced

Créez trois autres templates de prompts dans .claude/prompts/ :

• refactor.md — Un workflow de refactoring structuré : identifier la cible, évaluer l’impact, planifier des étapes incrémentales, exécuter une étape à la fois, vérifier que les tests passent à chaque étape et documenter la motivation dans le message de commit.
• code-review.md — Une checklist de revue de code couvrant la sécurité (secrets, injection, authentification), la justesse (cas limites, chemins d’erreur), la performance (N+1, async, pagination), la lisibilité (nommage, diffs ciblés) et les tests (couverture, assertions significatives). Classez les constats en Critique, Avertissement ou Suggestion.
• onboarding.md — Un workflow d’intégration projet : explorer la structure des répertoires, identifier la stack, trouver les points d’entrée, documenter les commandes de build et d’exécution, cartographier l’architecture, vérifier les conventions et produire un document de synthèse.

Vous pouvez invoquer n’importe quel template de prompt pendant une session Claude Code avec /nom-du-prompt ou en le référençant avec @.claude/prompts/nom.md.

Vous devriez maintenant avoir quatre templates de prompts couvrant les workflows de développement les plus courants.

Étape 9 : Créer le script d’installation

Le script d’installation copie l’ensemble de la configuration dans un projet existant. Cela rend le starter portable entre tous vos dépôts.

Créez scripts/install-local.sh :

#!/usr/bin/env bash
# Install this Claude Code starter config into an existing project.
# Usage: ./scripts/install-local.sh [target-directory]

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_DIR="$(dirname "$SCRIPT_DIR")"
TARGET="${1:-.}"

# Resolve to absolute path
TARGET="$(cd "$TARGET" && pwd)"

echo "Claude Code Multi-Stack Starter Installer"
echo "==========================================="
echo ""
echo "Source: $REPO_DIR"
echo "Target: $TARGET"
echo ""

# Check if .claude/ already exists
if [ -d "$TARGET/.claude" ]; then
  echo "Warning: $TARGET/.claude/ already exists."
  read -rp "Overwrite existing config? (y/N): " confirm
  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
    echo "Aborted."
    exit 0
  fi
fi

# Copy .claude/ directory
echo "Copying .claude/ config..."
mkdir -p "$TARGET/.claude"
cp "$REPO_DIR/.claude/settings.json" "$TARGET/.claude/settings.json"
cp -r "$REPO_DIR/.claude/rules" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/agents" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/hooks" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/prompts" "$TARGET/.claude/"

# Copy CLAUDE.md if it doesn't exist
if [ -f "$TARGET/CLAUDE.md" ]; then
  echo "CLAUDE.md already exists in target. Skipping (review manually)."
else
  cp "$REPO_DIR/CLAUDE.md" "$TARGET/CLAUDE.md"
  echo "Copied CLAUDE.md"
fi

# Make hook scripts executable
chmod +x "$TARGET/.claude/hooks/"*.sh 2>/dev/null || true

# Detect stacks
echo ""
echo "Detecting stacks in target project..."
cd "$TARGET"
stacks_output=$("$REPO_DIR/scripts/detect-stack.sh" 2>/dev/null \
  || echo '{"stacks": []}')
echo "$stacks_output"

# Summary
echo ""
echo "Installation complete."
echo ""
echo "Next steps:"
echo "  1. Review CLAUDE.md and adjust for your project"
echo "  2. Remove stack rules you don't need from .claude/rules/"
echo "  3. Remove agents you don't need from .claude/agents/"
echo "  4. Customize .claude/settings.json hooks"
echo "  5. Open the project in VS Code and start Claude Code"

Rendez-le exécutable :

chmod +x scripts/install-local.sh

Pour installer le starter dans un projet existant :

./scripts/install-local.sh /chemin/vers/votre/projet

Le script copie le répertoire .claude/, préserve tout CLAUDE.md existant, rend les hooks exécutables et lance la détection de stack sur le projet cible.

Vous devriez maintenant avoir un script d’installation fonctionnel capable de déployer la configuration dans n’importe quel projet.

Étape 10 : Tester la configuration

Choisissez un projet existant qui utilise au moins une des stacks supportées. Installez la configuration en utilisant le script d’installation ou en copiant les fichiers manuellement. Puis vérifiez que chaque composant fonctionne.

Vérifiez que les règles inconditionnelles se chargent. Démarrez une nouvelle session Claude Code et demandez à Claude de décrire ses règles actives. Les quatre règles inconditionnelles (common, testing, git, security) devraient être présentes.

Vérifiez que les règles conditionnelles se déclenchent. Demandez à Claude de lire ou de modifier un fichier correspondant à l’un des patterns de stack. Par exemple, ouvrez un fichier .php dans un projet Laravel. Les règles Laravel devraient s’activer. Ouvrez un fichier .tsx et les règles React devraient s’activer à la place.

Vérifiez que les subagents sont disponibles. Demandez à Claude de lister les agents disponibles ou essayez de déléguer une tâche à un agent spécifique comme laravel-architect.

Vérifiez que le hook de démarrage de session s’exécute. Démarrez une nouvelle session et vérifiez si Claude rapporte les stacks détectées. Vous devriez voir une sortie comme “Detected stacks: laravel, docker-devops”.

Vérifiez que le hook post-edit se déclenche. Demandez à Claude de modifier un fichier et vérifiez si la vérification de lint s’exécute automatiquement après la modification.

Si tout fonctionne, la configuration est prête pour une utilisation quotidienne.

Personnalisation

Le starter est une fondation, pas un produit fini. Voici comment l’adapter :

Supprimez les stacks inutilisées. Supprimez les fichiers de règles et d’agents pour les stacks que vous n’utilisez pas. Une équipe exclusivement Python peut supprimer laravel.md, react-next.md, node-express.md et leurs agents correspondants.

Personnalisez les règles inconditionnelles. Ajustez common.md, testing.md, git.md et security.md pour correspondre aux conventions de votre équipe. Elles se chargent à chaque session, donc gardez-les concises et pertinentes.

Ajoutez de nouvelles stacks. Copiez un fichier de règle conditionnelle existant, mettez à jour le frontmatter paths pour correspondre aux patterns de fichiers de votre nouvelle stack et mettez à jour les directives. Par exemple, pour ajouter le support Rust :

---
paths:
  - "**/*.rs"
  - "**/Cargo.toml"
---

Puis ajoutez un bloc de détection correspondant dans detect-stack.sh :

[ -f Cargo.toml ] && stacks+=("rust")

Et optionnellement créez un agent rust-systems.md dans .claude/agents/.

Ajustez les timeouts des hooks. Si vos outils de lint sont lents, augmentez les valeurs de timeout dans settings.json. Le hook de démarrage de session est par défaut à 30 secondes et le hook post-edit à 60 secondes.

Problèmes courants de configuration

Les règles de stack se chargent à chaque session

Symptômes : Claude fait référence aux règles Laravel alors que vous modifiez des fichiers Python, ou toutes les règles de stack apparaissent actives quel que soit le contexte de travail.

Cause probable : Le frontmatter paths est absent du fichier de règle de stack, ou la syntaxe YAML est invalide.

Correction : Ouvrez le fichier de règle et vérifiez qu’il commence par un bloc paths valide entre les délimiteurs ---. Recherchez les erreurs de syntaxe YAML comme des guillemets manquants, une indentation incorrecte ou un --- de fermeture manquant.

Les hooks ne s’exécutent pas

Symptômes : Pas de sortie de détection de stack au démarrage de session. Pas de vérification de lint après les modifications.

Cause probable : Les scripts de hooks ne sont pas exécutables, le chemin dans settings.json est incorrect ou la variable $CLAUDE_PROJECT_DIR ne se résout pas correctement.

Correction : Exécutez chmod +x .claude/hooks/*.sh. Vérifiez que settings.json utilise le bon format de chemin avec $CLAUDE_PROJECT_DIR. Vérifiez que le répertoire scripts existe et contient detect-stack.sh.

Stack non détectée

Symptômes : Le hook de démarrage de session rapporte “No specific stack detected” alors que le projet utilise clairement une stack supportée.

Cause probable : Les fichiers marqueurs ne sont pas à la racine du projet. Dans un monorepo, le fichier artisan de Laravel pourrait être dans backend/ au lieu de la racine.

Correction : Déplacez les fichiers marqueurs à la racine, ajoutez des liens symboliques ou modifiez detect-stack.sh pour vérifier les dispositions courantes de monorepo comme packages/, apps/ ou services/.

Le hook post-edit rapporte des erreurs

Symptômes : Des erreurs de lint apparaissent après chaque modification, même pour des problèmes sans rapport.

Cause probable : L’outil de lint rapporte des problèmes préexistants dans le fichier, pas des problèmes causés par la modification.

Correction : Corrigez les problèmes de lint préexistants ou ajustez le hook post-edit pour ne rapporter que les erreurs sur les lignes modifiées. En solution rapide, vous pouvez aussi commenter des vérifications spécifiques du linter dans post-edit-check.sh.

CLAUDE.md est trop détaillé

Symptômes : Le fichier CLAUDE.md grossit de nouveau, ce qui annule l’intérêt de la configuration modulaire.

Cause probable : Des directives spécifiques à une stack ou des détails sont ajoutés dans CLAUDE.md au lieu du fichier de règle approprié.

Correction : Déplacez les directives détaillées dans le fichier .claude/rules/ concerné. CLAUDE.md doit rester un routeur léger : aperçu du projet, indices de stack, comportement par défaut et imports @. Tout le reste appartient à un fichier de règle.

Conclusion

Vous disposez maintenant d’une configuration Claude Code modulaire qui s’adapte à la stack sur laquelle vous travaillez. Les règles inconditionnelles fournissent des directives de base cohérentes. Les règles conditionnelles ne se chargent que lorsqu’elles sont pertinentes. Les subagents offrent une expertise ciblée. Les hooks automatisent les vérifications de routine. Et le script d’installation rend l’ensemble portable entre les projets.

Le principe clé est simple : ne charger que ce qui compte pour la tâche en cours. Cela donne à Claude plus de contexte pour le code sur lequel il travaille réellement, et donne à votre équipe une configuration maintenable qui passe à l’échelle avec le projet.

Le starter complet est disponible sur InkByteStudio/claude-code-vscode-multistack-starter. Clonez-le, personnalisez-le et retirez ce dont vous n’avez pas besoin.

Pour une vision plus globale de l’importance de cette approche modulaire, consultez l’article de blog compagnon : Why Most CLAUDE.md Files Are Too Big. Pour comprendre comment Claude Code s’inscrit dans le paysage plus large des agents de codage IA, lisez AI Coding Agents in 2026: How MCP Is Changing Software Development et Building Custom MCP Servers. Pour les équipes qui réfléchissent à la sécurité et à la gouvernance autour du développement agentique, combinez cela avec Securing AI Coding Agent Workflows et the Agentic AI Security Playbook.