TL;DRUn projet Claude Code bien rangé tient en trois fichiers à la racine et un dossier .claude/. Voici à quoi sert chaque emplacement, ce qu'il faut y écrire et ce qui se partage ou non avec votre équipe.

Pourquoi structurer un projet Claude Code ?#

Claude Code est l'assistant de développement d'Anthropic qui travaille directement dans votre dépôt : il lit les fichiers, lance des commandes et modifie le code. À chaque session, il repart pourtant de zéro. Ce qu'il sait de votre projet, il le tient de quelques fichiers placés à des endroits précis.

Bien ranger ces fichiers change deux choses. D'abord, vous arrêtez de répéter les mêmes consignes à chaque conversation. Ensuite, toute l'équipe travaille avec les mêmes règles, puisque la plupart de ces fichiers se versionnent avec Git comme le reste du code.

Chez Websource, nous utilisons Claude Code au quotidien sur nos projets Symfony et PrestaShop. La structure présentée ici est celle décrite par la documentation officielle ; nous y ajoutons ce que la pratique nous a appris sur la place de chaque consigne.

L'arborescence type d'un projet#

Tout tient en trois fichiers à la racine et un dossier .claude/. Les noms de fichiers dans rules/, commands/, skills/ et agents/ sont des exemples : vous choisissez les vôtres.

mon-projet/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── commands/
    │   ├── review.md
    │   └── fix-issue.md
    ├── skills/
    │   └── deploy/
    │       ├── SKILL.md
    │       └── deploy-config.md
    ├── agents/
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/
        └── validate-bash.sh

1. CLAUDE.md : la mémoire du projet#

C'est le fichier le plus important. Claude Code le charge au début de chaque session. Vous y décrivez ce qu'un nouveau développeur devrait savoir avant de toucher au code :

  • le contexte du projet : objectifs et périmètre ;
  • la stack technique et l'architecture ;
  • les conventions de code et les bonnes pratiques de l'équipe ;
  • les commandes courantes (tests, build, cache).
# Projet : boutique en ligne

## Contexte
Site e-commerce Symfony 7, PHP 8.3, MariaDB. Production sur un serveur dédié.

## Commandes utiles
- Tests : `php bin/phpunit`
- Vider le cache : `php bin/console cache:clear`

## Conventions
- PSR-12, typage strict, pas de logique métier dans les contrôleurs
- Toute nouvelle route doit avoir un test fonctionnel

La documentation recommande de rester sous 200 lignes par fichier : au-delà, le fichier consomme plus de contexte et les consignes sont moins bien suivies. Ce qui ne concerne qu'une partie du code a sa place dans .claude/rules/ (voir plus bas).

Bon à savoir. La commande /init génère un premier CLAUDE.md à partir de l'analyse de votre dépôt. C'est une base à relire et à corriger, pas un fichier à garder tel quel.

2. CLAUDE.local.md : vos consignes personnelles#

Même principe, mais pour vous seul : adresse de votre environnement de test, jeux de données préférés, notes personnelles. Ce fichier ne se versionne pas : ajoutez-le à votre .gitignore.

Il ne remplace pas CLAUDE.md. Les deux fichiers sont chargés ensemble, et CLAUDE.local.md est lu en dernier. C'est ce qui lui permet de compléter les consignes communes, ou de les préciser pour votre poste.

3. .mcp.json : les connexions aux outils#

Le protocole MCP (Model Context Protocol) permet à Claude Code de dialoguer avec des outils externes : GitHub, Jira, Slack, une base de données, etc. Le fichier .mcp.json, à la racine, déclare les serveurs MCP du projet.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Comme il est versionné, toute l'équipe dispose des mêmes connexions. Par sécurité, Claude Code demande à chaque utilisateur d'approuver les serveurs déclarés dans ce fichier avant de s'y connecter. N'y écrivez jamais de jeton ou de mot de passe en clair : passez par des variables d'environnement.

4. settings.json et settings.local.json : les réglages#

Le fichier .claude/settings.json contient les réglages partagés du projet : permissions (ce que Claude peut faire sans demander, ce qui lui est interdit), choix du modèle, variables d'environnement et déclaration des hooks.

{
  "permissions": {
    "allow": ["Bash(php bin/phpunit *)"],
    "deny": ["Read(./.env)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-bash.sh"
          }
        ]
      }
    ]
  }
}

.claude/settings.local.json joue le même rôle pour vos réglages personnels sur ce projet. Claude Code le tient hors de Git lorsqu'il crée lui-même le fichier ; si vous le créez à la main, ajoutez-le au .gitignore.

5. rules/ et commands/ : règles par sujet et commandes réutilisables#

rules/ : une règle par sujet#

Plutôt qu'un CLAUDE.md interminable, le dossier .claude/rules/ accueille un fichier Markdown par thème : style de code, tests, conventions d'API. Une règle peut cibler des fichiers précis grâce au champ paths ; elle n'est alors chargée que lorsque Claude travaille sur un fichier correspondant.

---
paths:
  - "src/api/**/*.php"
---

# Conventions de l'API

- Chaque point d'entrée valide ses données en entrée
- Les erreurs suivent le format de réponse commun

Une règle sans champ paths est chargée à chaque session, comme CLAUDE.md.

commands/ : vos commandes maison#

Un fichier .claude/commands/review.md crée la commande /review : son contenu est la consigne que Claude exécute quand vous la tapez. Pratique pour une revue de code ou la correction d'un ticket, toujours menées de la même façon.

À noter : selon la documentation, les commandes personnalisées ont été fusionnées avec les skills. Les fichiers de commands/ continuent de fonctionner, mais pour un nouveau besoin, mieux vaut créer un skill.

6. skills/ et agents/ : méthodes de travail et sous-agents#

skills/ : des méthodes déclenchées selon la tâche#

Un skill est un dossier contenant un fichier SKILL.md et, si besoin, des fichiers annexes (ici deploy-config.md). Il décrit une méthode : comment déployer, comment rédiger une migration, comment préparer une mise en production. Vous pouvez l'appeler par son nom (/deploy), et Claude peut aussi le charger de lui-même quand la tâche s'y prête.

agents/ : des sous-agents spécialisés#

Un sous-agent est un assistant spécialisé, défini par un fichier Markdown : un nom, une description, les outils autorisés et sa consigne. Il travaille dans sa propre fenêtre de contexte et ne renvoie que son résultat, ce qui évite d'encombrer la conversation principale.

---
name: code-reviewer
description: Relit le code modifié et signale les défauts de qualité ou de sécurité
tools: Read, Glob, Grep
---

Tu es relecteur de code. Analyse les fichiers modifiés et rends
des remarques précises, classées par gravité.

Dans cet exemple, le relecteur n'a accès qu'à des outils de lecture : il peut analyser le code, pas le modifier.

7. hooks/ : des scripts lancés automatiquement#

Un hook est un script exécuté à un moment précis : avant l'usage d'un outil, après une modification de fichier, etc. Il sert à vérifier, formater ou valider, sans dépendre de la bonne volonté du modèle : c'est le programme qui l'exécute, pas Claude.

Le dossier .claude/hooks/ range les scripts ; leur déclenchement se déclare dans settings.json (voir l'exemple de la section 4). Un hook placé avant un outil peut bloquer l'opération : il lui suffit de se terminer avec le code de sortie 2, et son message d'erreur est transmis à Claude.

#!/bin/bash
# .claude/hooks/validate-bash.sh
commande=$(jq -r '.tool_input.command')

if echo "$commande" | grep -q 'rm -rf'; then
  echo "Commande destructrice refusée par le projet" >&2
  exit 2
fi
exit 0

Pensez à rendre le script exécutable (chmod +x). L'exemple utilise l'outil jq, qui doit être installé sur la machine.

Quel fichier pour quel besoin ?#

Vous voulez…Emplacement
Expliquer le projet et ses conventions généralesCLAUDE.md
Garder des notes propres à votre posteCLAUDE.local.md
Brancher GitHub, Jira ou une base de données.mcp.json
Autoriser ou interdire des commandes.claude/settings.json
Imposer une règle à une partie du code seulement.claude/rules/ avec paths
Rejouer une consigne à la demande.claude/skills/ (ou commands/)
Confier une tâche à un assistant spécialisé.claude/agents/
Garantir une vérification à chaque fois.claude/hooks/ + settings.json

Ce qui se partage et ce qui reste local#

Fichier ou dossierVersionné avec Git ?Concerne
CLAUDE.mdOuiToute l'équipe
CLAUDE.local.mdNon (.gitignore)Vous
.mcp.jsonOuiToute l'équipe
.claude/settings.jsonOuiToute l'équipe
.claude/settings.local.jsonNonVous
rules/, commands/, skills/, agents/, hooks/OuiToute l'équipe

Par où commencer ?#

Inutile de tout créer le premier jour. L'ordre qui fonctionne bien :

  1. Un CLAUDE.md court : contexte, stack, commandes de test, trois ou quatre conventions.
  2. Les permissions dans settings.json, dès que vous validez dix fois par jour la même commande.
  3. Des règles ciblées dans rules/ quand CLAUDE.md grossit.
  4. Un skill pour chaque procédure que vous expliquez pour la troisième fois.
  5. Un hook pour ce qui ne doit jamais être oublié : formatage, commande interdite, test obligatoire.
  6. Les serveurs MCP et les sous-agents quand le besoin est réel, pas avant.

Une consigne dans CLAUDE.md reste une demande faite au modèle ; un hook est une garantie. Si une règle ne tolère aucune exception, c'est un hook qu'il vous faut.

Pour aller plus loin sur l'usage de Claude dans un dépôt, lisez aussi Graphify pour consommer moins de tokens Claude et Comment faire du web design avec Claude Opus 5.5. Et si vous souhaitez mettre en place des agents IA ou des automatisations dans votre entreprise, parlons-en.

Questions fréquentes#

Faut-il créer tous ces fichiers pour utiliser Claude Code ?#

Non. Aucun n'est obligatoire. Un CLAUDE.md court suffit pour démarrer ; les autres emplacements s'ajoutent au fil des besoins.

Quelle différence entre CLAUDE.md et CLAUDE.local.md ?#

CLAUDE.md est versionné et partagé avec l'équipe. CLAUDE.local.md contient vos préférences personnelles pour le projet et s'ajoute au .gitignore. Les deux sont chargés ensemble, le fichier local étant lu en dernier.

Les fichiers de .claude/commands/ fonctionnent-ils encore ?#

Oui. La documentation indique que les commandes personnalisées ont été fusionnées avec les skills : les fichiers existants continuent de fonctionner, mais un skill est conseillé pour tout nouveau besoin.

Un hook peut-il vraiment empêcher Claude d'exécuter une commande ?#

Oui. Un hook déclenché avant l'usage d'un outil qui se termine avec le code de sortie 2 bloque l'appel, et son message d'erreur est transmis à Claude.

Peut-on mettre des identifiants dans .mcp.json ?#

Mieux vaut l'éviter : ce fichier est versionné. Utilisez des variables d'environnement pour les jetons et mots de passe.

Article publié le 11/10/2026 sous la signature de Jonathan Gutierrez, rédigé à partir des sources citées ci-dessus, puis relu avant publication. Une information vous semble inexacte ou datée ? Signalez-le nous, nous corrigeons.