Un agent de code devient utile lorsqu’il comprend les conventions du dépôt et peut vérifier son travail. La configuration initiale doit donc expliquer comment construire, tester et modifier le projet, tout en limitant les commandes et données accessibles.
Commencer par une cartographie
Avant toute modification, identifiez gestionnaire de paquets, applications, dossiers générés, tests, formatage, variables attendues et règles Git. Lancez les commandes de lecture et de validation déjà documentées. Corrigez d’abord une documentation obsolète : un agent suivra fidèlement une mauvaise commande.
Écrire un CLAUDE.md utile
Le fichier d’instructions doit rester court et opérationnel : architecture, commandes validées, conventions importantes, zones à ne pas toucher et définition du travail terminé. Évitez de recopier tout le README ou d’imposer des préférences contradictoires avec les linters. Placez des instructions plus locales près des sous-projets si leur comportement diffère.
Permissions et secrets
Accordez uniquement les commandes nécessaires et examinez les effets externes. Ne placez jamais de secrets dans les instructions. Vérifiez les fichiers ignorés, les logs et les sorties de test avant de les partager. Une commande de déploiement, migration ou suppression mérite une confirmation distincte.
Première tâche de validation
Choisissez une modification petite et réversible. Demandez à l’agent d’expliquer les fichiers concernés, puis de modifier et tester. Examinez le diff, les tests et les fichiers non suivis. Cette expérience révèle les instructions manquantes bien mieux qu’un long document théorique.
Checklist
- Commandes d’installation, test et formatage confirmées.
- CLAUDE.md concis et versionné.
- Dossiers générés et sensibles signalés.
- Permissions minimales.
- Tests ciblés puis suite pertinente.
- Diff relu avant commit ou déploiement.
FAQ
Faut-il décrire chaque fichier ?
Non. Documentez les règles difficiles à déduire et laissez l’agent explorer le dépôt.
Peut-on partager CLAUDE.md ?
Oui s’il contient des conventions d’équipe sans informations personnelles ou secrets.
Les permissions remplacent-elles la revue ?
Non. Elles réduisent le risque ; la revue et les tests valident le résultat.
Mise en pratique : préparer le dépôt
Placez les règles réellement utiles à l’agent dans un fichier CLAUDE.md à la racine. Elles doivent être courtes, vérifiables et propres au projet.
# CLAUDE.md
## Commandes de validation
- npm run lint
- npm run typecheck
- npm test
## Contraintes
- TypeScript strict, aucun `any` ajouté sans justification.
- Ne pas modifier les migrations existantes.
- Conserver les réponses API rétrocompatibles.Ajoutez ensuite les permissions locales minimales dans .claude/settings.json :
{
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run typecheck)", "Bash(npm test)"]
}
}Commencez par une demande de lecture seule : « analyse l’architecture, cite les fichiers concernés et propose un plan sans modifier le dépôt ». Une fois le plan validé, demandez une petite modification puis contrôlez git diff --stat et git diff. N’autorisez jamais par défaut les commandes de déploiement, la lecture des secrets ou les opérations Git destructrices.