Claude dans un projet de développement : fichiers, agents et garde-fous

Un assistant comme Claude est utile dès qu’on lui donne du contexte, et dangereux dès qu’on lui laisse tout faire sans garde-fous. Dans mes projets, j’ai donc organisé Claude Code comme le reste de mon outillage : des fichiers lisibles, versionnés, qui disent ce qu’on attend de lui, ce qu’il a le droit de faire et comment vérifier son travail. Cet article décrit cette organisation, avec des exemples tirés de mon propre socle de travail, et la distinction essentielle entre ce qui reste personnel et ce qui est partagé dans le dépôt.

Le problème : un assistant sans mémoire de vos règles

Sans cadre, il faut répéter à chaque session les mêmes consignes : langue des commentaires, outil de gestion des dépendances, format des messages de commit, fichiers à ne pas ouvrir. Et rien n’empêche l’assistant de faire une erreur coûteuse, comme pousser du code sans qu’on l’ait demandé. Le but d’un projet bien configuré est double :

• transmettre le contexte une fois pour toutes, dans des fichiers que l’assistant relit à chaque session ;
• poser des limites techniques, qui ne dépendent pas de la bonne volonté du modèle.

Les six briques d’un projet Claude Code

Claude Code lit un fichier de contexte à la racine du projet et un dossier de configuration nommé .claude. Voici comment je les décompose.

Brique	Rôle	Exemple dans mon organisation
CLAUDE.md	Contexte et règles du projet, en texte libre, relus à chaque session	Règles d’usage universelles : réponses en français, commits au format Conventional Commits, ne jamais pousser sans demande explicite
Règles (rules)	Consignes thématiques, rangées dans des fichiers séparés	Une règle « git, commits et versions » commune à tous les projets ; des règles de conventions de code propres aux utilitaires Python
Agents	Assistants spécialisés, avec leur propre consigne et leurs propres outils	Un agent de revue de sécurité qui lit un diff sans rien modifier, un agent qui exécute les tests, un autre qui audite les dépendances, un autre qui garde la documentation à jour
Commandes	Procédures déclenchées à la demande	Une commande de commit qui découpe les changements, rédige le message au bon format et refuse de contourner les contrôles
Hooks	Scripts exécutés automatiquement avant ou après une action de l’assistant	Un hook qui bloque les commits sur la branche principale et les options dangereuses de git ; un autre qui refuse d’écrire un secret apparent dans un fichier suivi
Skills	Savoir-faire détaillé, chargé seulement quand la tâche le demande	Un guide de bonnes pratiques web, utilisé pour les projets de sites

Ce qui relève de la règle et ce qui relève du garde-fou

La distinction la plus utile que j’ai retenue est celle-ci : une règle écrite dans CLAUDE.md est une demande, un hook est une contrainte. Je demande à l’assistant de ne jamais pousser sans mon accord, mais c’est le hook sur les commandes git qui l’empêche réellement de forcer un envoi ou de contourner les vérifications avant commit. Les permissions du fichier de réglages jouent le même rôle : certaines commandes de lecture (état du dépôt, historique) sont autorisées d’office, d’autres opérations sont refusées quoi qu’il arrive.

• Ce qui doit toujours être respecté (secrets, historique git, envoi en production) : un hook ou une permission.
• Ce qui relève de la préférence ou du style (langue, ton, conventions de nommage) : une règle ou le CLAUDE.md.
• Ce qui est long et spécialisé (revue de sécurité, audit de dépendances) : un agent ou une skill, pour ne pas alourdir le contexte de chaque session.

Propre au développeur ou partagé dans le dépôt ?

Tout ne doit pas finir dans le dépôt. Claude Code distingue plusieurs niveaux, et je les range ainsi :

• Partagé avec l’équipe, versionné dans le dépôt : le CLAUDE.md du projet, ses règles, ses agents, ses commandes, ses hooks et le fichier de réglages commun. Quiconque clone le projet retrouve le même cadre de travail.
• Propre au développeur, hors du dépôt : mes préférences générales, mes réglages locaux et la mémoire que l’assistant accumule sur ma manière de travailler. Ils restent sur mon poste et ne sont pas transmis à un client ou à un collègue.
• Jamais lu ni écrit : les fichiers de secrets et d’environnement. Les règles du socle interdisent de les afficher sans nécessité, et un hook refuse d’y écrire un secret apparent.

Cette séparation a une conséquence pratique : un projet que je livre à un client contient son cadre de travail, utilisable sans moi, mais jamais mes préférences personnelles.

Mon organisation : un socle commun et des projets autonomes

Je travaille sur plusieurs projets de natures différentes : sites web, applications hébergées sur un même serveur, petits utilitaires Python. Les règles universelles sont écrites une seule fois, dans un socle commun. Mais Claude Code ne lit que le dossier de configuration du projet ouvert : il ne remonte pas chercher ses règles ailleurs.

J’ai donc choisi la copie plutôt que le lien. Le socle contient :

• un dossier de sources communes (règles, agents, commandes, hooks) ;
• des profils par type de projet (web, application, utilitaire Python), qui ajoutent ce qui est propre à ce type ;
• un registre qui indique, pour chaque projet, les profils qui s’y appliquent ;
• un script de synchronisation qui copie le tout dans chaque projet.

Chaque projet reste ainsi autonome : il peut être cloné seul, sur une autre machine, et fonctionner sans le socle. La synchronisation suit trois règles : un fichier absent ou identique est copié ; un fichier copié puis jamais modifié est mis à jour à la synchronisation suivante ; un fichier que le projet a spécialisé est conservé et signalé comme différent. Un projet peut donc adapter une règle sans qu’elle soit écrasée, et je ne modifie jamais à la main un fichier géré, puisqu’il serait remplacé.

Modifier une règle commune suit toujours le même parcours : je l’édite dans le socle, je lance la synchronisation en simulation pour voir ce qui changerait, je l’applique, puis je valide le changement par un commit dans chaque projet touché.

Un exemple concret : le garde-fou git

Les consignes de commit sont un bon cas d’école. Le CLAUDE.md et la règle git précisent le format attendu (type en anglais, description en français), l’interdiction de contourner les vérifications et l’interdiction de pousser sans demande. Le hook correspondant refuse ensuite, avant même l’exécution, un envoi forcé ou un commit qui désactive les contrôles. Et la commande de commit enchaîne les étapes : examiner les changements, proposer un découpage en commits courts, rédiger le message, laisser les contrôles automatiques s’exécuter. La règle explique, la commande guide, le hook protège.

Le lien avec la certification Claude Architect Foundations

J’ai passé en 2026 la certification Claude Architect Foundations d’Anthropic, que je mentionne sur ma page À propos. Cet article ne reprend pas son programme : il décrit comment j’applique Claude dans mon quotidien de développeur. Ce que je retiens de cette démarche, c’est l’idée de traiter l’assistant comme un composant d’un système, avec un contexte défini, des outils délimités, des vérifications en sortie et un humain qui garde la décision.

Par où commencer dans votre projet

1. Écrire un CLAUDE.md court : commandes de test et de lancement, conventions de code, ce qu’il ne faut jamais faire.
2. Isoler les consignes qui dépendent d’un thème dans des règles séparées.
3. Transformer chaque interdit vraiment important en hook ou en permission refusée.
4. Ne créer un agent que pour une tâche qui revient souvent et qui demande un regard spécialisé.
5. Décider dès le départ ce qui est partagé dans le dépôt et ce qui reste personnel.

En résumé

Un bon usage de Claude dans un projet tient moins au modèle qu’à l’organisation autour de lui : un contexte clair, des règles lisibles, des contraintes techniques pour les points sensibles et une séparation nette entre le personnel et le partagé. C’est ce cadre qui rend le travail reproductible d’une session à l’autre et d’un projet à l’autre. Pour la méthode de travail qui encadre ces projets, lisez aussi du besoin au produit livré : ma méthodologie de travail.