Template CLAUDE.md pour Claude Code dans un projet existant

CLAUDE.md évite de répéter le contexte à chaque session

Dans un dépôt existant, Claude Code n’a pas seulement besoin de savoir écrire du code. Il doit connaître les règles locales: le gestionnaire de paquets, le dossier principal, les fichiers générés, les commandes risquées, les critères de fin et les parties du produit qui ne doivent pas être modifiées sans accord.

CLAUDE.md sert à garder ces instructions en mémoire. La documentation officielle Claude Code memory explique que ce fichier est chargé au début d’une session. Mais il faut garder la bonne séparation: c’est du contexte, pas une couche d’exécution forcée. Pour bloquer des commandes ou des chemins, combinez-le avec settings, permissions, hooks, CI et règles du dépôt. Pour les secrets et les déploiements, consultez aussi la page security.

Ici, harness veut dire un échafaudage de travail pour l’agent. Le but n’est pas de créer une charte de 40 pages. Le but est de poser assez de repères pour éviter les mêmes erreurs. Pour aller plus loin, voyez les templates CLAUDE.md et le guide des permissions Claude Code.

Template CLAUDE.md prêt à copier

La première version doit rester courte. Mettez les faits utiles à presque toutes les sessions: résumé du projet, commandes, limites, règles qualité et définition de fin.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Placez-le à la racine du dépôt sous le nomCLAUDE.md. Si le dépôt utilise déjàAGENTS.md, évitez de dupliquer toutes les règles. Créez un petitCLAUDE.mdqui importe la source commune puis ajoute les consignes spécifiques à Claude Code. Les préférences personnelles vont plutôt dansCLAUDE.local.md.

Gardez les limites fortes dans settings

Une phrase comme “ne pas faire de push” dansCLAUDE.mdest utile, mais elle ne bloque pas l’action. Les limites réellement critiques doivent être dans settings, la CI, la protection de branche ou le processus de déploiement.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Utilisez.claude/settings.local.jsonpour une protection personnelle et.claude/settings.jsonpour une base d’équipe. Vérifiez le schéma actuel dans la documentation officielle settings avant de l’appliquer. CLAUDE.md décrit l’intention; settings définit les garde-fous d’exécution.

Trois cas d’usage concrets

Cas d’usage	À écrire dans CLAUDE.md	Ce que cela améliore
Maintenance d’articles localisés	slug cible, liste des langues, frontmatter à préserver, longueur, CTA, vérifications	Moins de langues oubliées, de texte anglais résiduel et de liens cassés
Petite correction SaaS	dossiers modifiables, commande de test, accord avant base de données, logs attendus	Moins de refactorings hors périmètre et de migrations risquées
Revue de code d’équipe	sévérité, fichier, ligne, impact, reproduction, test manquant	Des retours exploitables dans une PR ou un ticket

Pour le contenu multilingue, le problème fréquent est d’avoir tous les fichiers mais pas le bon contenu. Indiquer les dossiers par langue, les chemins de liens internes et la limite de description réduit ce risque dès le début.

Pour un SaaS, le périmètre est essentiel. Une petite correction d’interface ne doit pas toucher billing, auth ou migrations. Une consigne vérifiable vaut mieux que “améliore la qualité”.

Pour la revue de code, le format de sortie décide de l’utilité. Demandez un niveau de sévérité, le chemin, la ligne, l’impact utilisateur, la reproduction et le test manquant. La CLI reference aide si vous voulez lancer ces revues depuis un script.

Pièges fréquents

Premier piège: écrire trop. Un fichier de 300 lignes consomme du contexte et finit par être moins respecté. Gardez les règles communes et déplacez les cas spécifiques vers des règles par chemin ou une documentation dédiée.

Deuxième piège: y mettre des secrets. Pas de clés API, noms de clients, URL internes privées ni chiffres non publiés. Écrivez seulement la règle de traitement: les secrets restent dans les variables d’environnement, ne sont pas imprimés et nécessitent une demande avant ouverture.

Troisième piège: garder de vieilles commandes. Si le projet passe de Yarn à npm, de Jest à Vitest ou de Next.js à Astro, mettezCLAUDE.mdà jour immédiatement. Une commande obsolète donne de mauvais résultats avec beaucoup d’assurance.

Quatrième piège: croire que l’instruction remplace la vérification. Demandez un reçu final: commandes exécutées, résultat, fichiers changés, liens vérifiés et risques restants. C’est souvent ce qui révèle les petites erreurs de publication.

Déployer la pratique progressivement

Commencez avec ce template, puis testez-le sur trois petites tâches: une édition de contenu, une correction UI et une revue. Ajoutez ensuite uniquement les règles qui auraient évité une erreur réelle. Les limites qui doivent être garanties passent dans settings, CI, protection de branche ou validation de déploiement.

Sur un site commercial, les CTA font partie de la qualité. Produits, formulaires, pages training et liens de consultation doivent rester visibles et corrects. Sinon les visites continuent mais la conversion baisse.

Pour des prompts, templates et checklists réutilisables, consultez ClaudeCodeLab products. Pour un déploiement d’équipe avec permissions, règles de revue, formation etCLAUDE.mdadapté au dépôt, passez par Claude Code training and consultation. Le bon fichier n’est pas le plus complet; c’est celui qui empêche la prochaine erreur répétée.