Claude Code : CLAUDE.md — instructions dépôt
À la fin, vous saurez rédiger un CLAUDE.md minimal mais efficace, le versionner, l’itérer avec l’équipe, et éviter le piège du roman d’instructions.
Niveau : Débutant → Intermédiaire · Temps estimé : 40–50 min · Dernière vérification : 2026-09-11
Prérequis
- [ ] Claude Code installé — démarrer
- [ ] Repo lab Git
- [ ] Notions prompt engineering — prompt engineering
- [ ] Hub /ia/
Coût : lab tokens/abonnement ; pas de secrets. Angle DevOps Elastic Hayway : livrables Git, humain responsable.
Vous restez responsable de chaque action proposée par l’outil.
Ce que nous allons construire
CLAUDE.md lab
├── /init ou squelette manuel
├── Sections : stack, commandes, garde-fous, style
├── Commit + revue PR
└── Itération après 3 sessions
(Schéma — alt : « claude-code-claude-md lab DevOps ».)
Étape 1 — Rôle du fichier
Le fichier CLAUDE.md (racine du dépôt, parfois variantes de chemin selon version) fournit à Claude Code un contexte projet durable : stack, conventions, commandes de test, interdits. C’est l’équivalent spirituel d’un AGENTS.md côté Codex ou des rules Cursor — une spec d’agent versionnée avec le code.
Sans ce fichier, l’agent improvisera des conventions. Avec un roman de 2 000 lignes, il noiera le signal. Objectif : une à deux pages scannables, consignes vérifiables, zéro secret.
Étape 2 — Structure recommandée
Sections types :
- Produit / périmètre (1 paragraphe)
- Stack (langages, runtime, IaC)
- Commandes (test, lint, format — copiables)
- Conventions (style commit, structure dossiers)
- Garde-fous (pas de secrets, pas de prod, namespaces lab)
- À ne pas faire (liste courte)
Exemple minimal :
# Lab demo API
### Stack
- Python 3.12, pytest ; pas de cloud réel
### Commandes
- Tests : `python -m pytest -q`
### Garde-fous
- Jamais de `.env` prod ; pas de `kubectl` hors staging fictif
## Style
- FR pour docs ; code EN ; commits conventional
Étape 3 — Générer puis élaguer
Utilisez /init (voir slash commands) pour un starter, puis élaguez : supprimez les généralités, gardez ce qui change le comportement. Chaque phrase doit passer le test : « si je retire ça, l’agent se trompe-t-il vraiment ? »
Étape 4 — Gouvernance d’équipe
Traitez CLAUDE.md comme du code : PR, revue, owners. Évitez les instructions contradictoires avec les Skills (claude-skills-instructions). Documentez qui peut élargir les permissions décrites. Pont MCP : ne listez dans CLAUDE.md que les serveurs approuvés — claude-code-mcp.
Étape 5 — Mesurer l’efficacité
Après 3 sessions : l’agent respecte-t-il les commandes de test ? Propose-t-il encore des chemins hors repo ? Si oui, renforcez les garde-fous. Si le fichier grossit sans gain, archivez des sections vers Skills ciblés. Voir evaluer-qualite-skill.
Lab concret DevOps
mkdir -p ~/lab-claude-md && cd ~/lab-claude-md
git init
printf '%s
' 'def ping(): return "pong"' > app.py
cat > CLAUDE.md << 'EOF'
# Lab CLAUDE.md
## Stack
- Python 3 ; tests via `python -c`
## Commandes
- Smoke : `python -c "import app; assert app.ping()=='pong'"`
## Garde-fous
- Pas de réseau ; pas de secrets ; rester dans ce dépôt
EOF
git add . && git commit -m "chore: CLAUDE.md minimal"
claude
Demandez : « ajoute une fonction health + mets à jour CLAUDE.md commandes ». Validez le diff. Refusez toute commande hors scope.
Erreurs fréquentes
| Symptôme | Cause | Correctif |
|---|---|---|
| Agent ignore les tests | Commande absente/floue | Section Commandes exacte |
| Roman CLAUDE.md | Init non élagué | Couper à 1–2 pages |
| Secret dans le md | Copier config | Redact + rotation |
| Conflit Skills | Double source | Une source de vérité / PR |
| Toujours régénérer | Pas de commit | Versionner le fichier |
Quiz (4 questions)
1. CLAUDE.md sert à :
– A. Stocker des clés API
– B. Donner un contexte dépôt durable à l’agent
– C. Remplacer pytest
2. Taille idéale jour 1 :
– A. 50 pages
– B. 1–2 pages scannables
– C. Vide toujours
3. Après /init :
– A. Merger sans lire
– B. Élaguer et committer
– C. Désactiver Git
4. Bonne section Garde-fous :
– A. Coller .env
– B. Interdits explicites lab/secrets
– C. Always-allow
Réponses : 1‑B · 2‑B · 3‑B · 4‑B
Compléments opérationnels
Mesure et amélioration continue
Définissez trois indicateurs simples : taux de DoD vert du premier coup, nombre de refus utiles par session, coût tokens par livrable Git accepté. Revoyez-les toutes les deux semaines. Si le taux DoD stagne sous 50 %, le problème est le brief ou le corpus de rules, pas « le besoin d’un modèle plus cher ». Si le coût explose, imposez un modèle fast par défaut et réservez strong aux plans. Publiez un mini tableau dans le dépôt docs pour rendre le coût visible à l’équipe, comme n’importe quelle ligne cloud.
Standard de brief réutilisable
Pour claude-code-claude-md, adoptez un brief unique partagé par l’équipe. Il contient toujours cinq champs : objectif mesurable, contexte borné (lab/staging), liste blanche de fichiers ou ressources, interdits explicites (secrets, réseau, prod), et definition of done exécutable (commande de test ou checklist). Sans ces champs, l’outil improvisera — parfois avec élégance, souvent hors périmètre.
Stockez les briefs gagnants sous briefs/claude-code-claude-md/ dans un dépôt de documentation interne. Chaque brief cite le commit de référence et le modèle utilisé. Au troisième succès comparable, ouvrez une PR qui transforme le brief en rule, Skill ou slash command. Voir ai-skills-concept, claude-skills-instructions et evaluer-qualite-skill.
Revue de diff comme compétence P0
La vitesse d’un agent n’a aucune valeur si personne ne sait lire un diff. Instituez une règle simple : aucun apply massif sans parcours hunk par hunk. Posez-vous trois questions : ce changement est-il demandé ? est-il testé ? est-il réversible ? Si une réponse est non, refusez ou exigez un plan plus petit.
En atelier, faites commenter un diff à voix haute pendant cinq minutes. Les juniors apprennent ainsi le vocabulaire du refus. Reliez cette pratique à ai-code-review-pr et aux workflows ai-agent-workflows.
Sécurité continue
Les surfaces claude-code-claude-md multiplient les occasions d’injection et de fuite. Traitez tickets, README upstream, logs et ressources MCP comme des données non fiables. Séparez instructions et données. Allowlist tools. Confirmation humaine avant mutation. Guide : ai-prompt-injection-securite, mcp-servers-devops, claude-code-mcp.
Secrets : variables d’environnement de session, gestionnaire d’équipe, rotation, jamais de commit. Si un secret fuit dans un chat vendor, supposez-le compromis et rotatez.
Coûts, modèles et mode dégradé
Documentez un mapping fast/strong et un soft-cap mensuel dans la stack perso. OpenRouter peut aider à basculer — openrouter-multi-modeles. Le local (ollama-llm-locaux + continue-dev) sert de mode dégradé ou de bac à sable confidentialité.
Surveillez les changements silencieux de modèle par défaut : une régression de qualité est souvent un routing vendor, pas « l’équipe qui a oublié comment prompter ».
Ancrage parcours
claude-code-claude-md n’est qu’une étape du parcours IA DevOps 2026. Tronc commun d’abord (prompts, injection, skills), puis surface spécialisée, puis industrialisation (routines, MCP, RAG). Hub de navigation : /ia/. Comparatifs utiles : claude-vs-gpt-code, codex-vs-claude-code, claude-vs-cursor-vs-copilot.
Rituals hebdomadaires
Hebdo : promouvoir un brief en Skill/rule ; archiver un échec instructif ; vérifier le budget tokens. Mensuel : revoir la stack (retirer l’inutile) ; rejouer un lab gold ; mettre à jour les versions d’outils. Ces rituals valent mieux que d’ajouter un cinquième abonnement.
Exemple de NOTES.md
# NOTES claude-code-claude-md
Date:
Modèle:
Brief (résumé):
Fichiers touchés:
Commande DoD:
Refus utiles:
Commit:
Leçon:
Sans ce journal, vous réapprendrez les mêmes leçons chaque sprint. Avec ce journal, vous construisez un avantage composé d’équipe.
Quand arrêter l’outil
Arrêtez la session si : le DoD échoue deux fois de suite sans diagnostic clair ; l’outil insiste pour sortir du scope ; une commande dangereuse revient après refus ; vous ne comprenez plus le diff. Dans ces cas, revenir à l’éditeur manuel + checklist est un succès de gouvernance, pas un échec personnel.
Ponts concrets vers d’autres tutoriels
Après ce lab, enchaînez selon besoin : agent CLI (claude-code-demarrer, openai-codex-intro-2026, aider-pair-programming), IDE (windsurf-cascade, continue-dev, cursor-agent-composer-2026), qualité (evaluer-qualite-skill, ai-routines-agents), ou recherche (gemini-cli-deep-research, chatgpt-search-browsing).
Mesure et amélioration continue
Définissez trois indicateurs simples : taux de DoD vert du premier coup, nombre de refus utiles par session, coût tokens par livrable Git accepté. Revoyez-les toutes les deux semaines. Si le taux DoD stagne sous 50 %, le problème est le brief ou le corpus de rules, pas « le besoin d’un modèle plus cher ». Si le coût explose, imposez un modèle fast par défaut et réservez strong aux plans. Publiez un mini tableau dans le dépôt docs pour rendre le coût visible à l’équipe, comme n’importe quelle ligne cloud.
Mesure et amélioration continue
Définissez trois indicateurs simples : taux de DoD vert du premier coup, nombre de refus utiles par session, coût tokens par livrable Git accepté. Revoyez-les toutes les deux semaines. Si le taux DoD stagne sous 50 %, le problème est le brief ou le corpus de rules, pas « le besoin d’un modèle plus cher ». Si le coût explose, imposez un modèle fast par défaut et réservez strong aux plans. Publiez un mini tableau dans le dépôt docs pour rendre le coût visible à l’équipe, comme n’importe quelle ligne cloud.
FAQ
Par où commencer avec claude-code-claude-md ?
Lab jetable sans secrets, brief borné, puis seulement élargir. Voir parcours et /ia/.
Faut-il always-allow pour aller plus vite ?
Non. Le gain est illusoire face au coût d’un mauvais push.
Comment industrialiser ?
Rules/Skills versionnées — ai-skills-concept, claude-skills-instructions.
Lien sécurité ?
prompt injection et permissions cas par cas.
Où documenter le choix d’outil ?
stack-ia-perso-devops-2026.
Quel voisin lire ensuite ?
Pages sœurs du header + hub /ia/.
Points clés
- CLAUDE.md = spec agent versionnée
- Court, vérifiable, sans secrets
- /init puis élagage
- PR + owners
- Mesurer après 3 sessions
- Pont Skills/MCP maîtrisé
Pour aller plus loin / Suite
Maillage série IA Outils 2026
- Hub : /tutoriels/ia-parcours-devops-2026/ · /ia/
- Sécurité : prompt injection
- seo_title : CLAUDE.md Claude Code DevOps | Elastic Hayway
- seo_desc : Rédigez un CLAUDE.md minimal : stack, commandes, garde-fous — tutoriel FR Claude Code 2026.
- focus : CLAUDE.md Claude Code
Mesure et amélioration continue
Définissez trois indicateurs simples : taux de DoD vert du premier coup, nombre de refus utiles par session, coût tokens par livrable Git accepté. Revoyez-les toutes les deux semaines. Si le taux DoD stagne sous 50 %, le problème est le brief ou le corpus de rules, pas « le besoin d’un modèle plus cher ». Si le coût explose, imposez un modèle fast par défaut et réservez strong aux plans. Publiez un mini tableau dans le dépôt docs pour rendre le coût visible à l’équipe, comme n’importe quelle ligne cloud.
Mesure et amélioration continue
Définissez trois indicateurs simples : taux de DoD vert du premier coup, nombre de refus utiles par session, coût tokens par livrable Git accepté. Revoyez-les toutes les deux semaines. Si le taux DoD stagne sous 50 %, le problème est le brief ou le corpus de rules, pas « le besoin d’un modèle plus cher ». Si le coût explose, imposez un modèle fast par défaut et réservez strong aux plans. Publiez un mini tableau dans le dépôt docs pour rendre le coût visible à l’équipe, comme n’importe quelle ligne cloud.
Retour parcours IA — hub Claude, Codex, ChatGPT et Skills.