CLAUDE.md minimal pour monorepo pnpm — template prêt à copier

Te voilà avec un monorepo pnpm, des packages qui se croisent, et Claude Code qui oublie tout entre deux sessions. Ce guide te donne un CLAUDE.md minimal, testable en 5 minutes — conçu pour les monorepos, compatible avec claude-mem et MCP, et prêt à copier-coller.

---

Pourquoi un CLAUDE.md dédié pour monorepo ?

Les monorepos ajoutent deux frictions pour les agents IA : 1) la surface du code est plus large (plus de fichiers à scanner), 2) les conventions varient selon les packages (frontend vs backend). Un CLAUDE.md mal placé ou trop verbeux devient du bruit — Claude perd du temps et des tokens.

Un fichier contexte minimal et bien organisé règle ces problèmes : il oriente l’agent vers le package ciblé, expose les commandes exactes (pnpm workspace, scripts), et définit les limites (ce que l’agent ne doit jamais modifier). C’est ce que recommande la doc officielle de Claude Code pour optimiser la fenêtre de contexte (voir section “best practices”).

Sources rapides :

• claude-mem (plugin mémoire persistante) — README officiel : https://github.com/thedotmack/claude-mem
• Guide best-practices Claude Code : https://code.claude.com/docs/en/best-practices
• Étude sur le bruit causé par fichiers auto-générés (ETH Zurich) : https://arxiv.org/abs/2602.11988
• MCP (interop) et contexte multi-outils : https://arxiv.org/abs/2604.03551 (AgenticFlict) — contexte sur MCP dans notre article : /blog/fr/2026-04-07-mcp-protocole-standard-agents-ia/

---

Règles simples (à lire avant d’écrire)

• Court = utile : 20–80 lignes. Si tu peux le dire en 10, dis-le.
• Package-first : indique toujours le package cible (ex: packages/frontend) dès la première ligne.
• Commandes exactes : pas de npm run dev indistinct — écris pnpm --filter=@myorg/frontend dev.
• Ne répète pas AGENTS.md — si ton repo a un AGENTS.md, importe-le (@AGENTS.md) puis ajoute uniquement les spécificités Claude.
• Permissions & limites : bloque clairement les dossiers sensibles (/infra, /secrets, prisma/migrations).

---

Template CLAUDE.md minimal pour monorepo (pnpm)

Copie-coller ci-dessous et adapte en 2–5 minutes.

# CLAUDE.md

## Package ciblé
packages/frontend  # <= change selon la tâche (packages/frontend | packages/api | apps/worker)

## Commandes (exactes)
- Install: `pnpm install --frozen-lockfile`
- Dev (frontend): `pnpm --filter=@myorg/frontend dev`
- Test (package): `pnpm --filter=@myorg/frontend test -- --runInBand`
- Build (package): `pnpm --filter=@myorg/frontend build`
- Lint: `pnpm --filter=@myorg/frontend lint -- --fix`

## Où chercher
- Code important: `packages/frontend/src`, `packages/frontend/components`
- Entrées serveur: `packages/api/src/server.ts`
- Scripts utiles: `scripts/repro.sh`, `scripts/run-local-db.sh`

## Conventions rapides
- TS strict, target ES2022
- Tests: jest + vitest (voir `package.json` de chaque package)
- Branches: `feat/`, `fix/`, `chore/`

## Limites : NE PAS TOUCHER
- `prisma/migrations/` — migrations générées automatisées
- `infra/terraform/` — attention aux secrets
- `apps/ci/` — pipeline CI propriétaire

## Claude-specific
- Utilise `subagent:code-review` pour PR > 10 fichiers
- Après modification majeure, exécute `npm run smoke -- --filter=@myorg/frontend`
- Pour debug: commence par `cat logs/last-error.log` puis ouvre `packages/api/src` au path indiqué

---

Pourquoi ce template marche (3 points)

1. Package-first réduit la surface de recherche — Claude charge le contexte le plus proche du code ciblé.
2. Commandes explicites évitent les erreurs d’arguments et les tests flakys (les agents reproduisent exactement ce que tu demandes).
3. Limites claires empêchent les réécritures catastrophiques (infrastructure, migrations).

Chaque ligne corrige un comportement observé : c’est la différence entre une instruction utile et du bruit — comme l’explique l’étude ETH Zurich sur les fichiers auto-générés (voir sources).

---

Checklist d’intégration (5 min)

1. Crée CLAUDE.md à la racine ou dans le dossier package s’il doit être local (packages/frontend/CLAUDE.md).
2. Si tu as déjà AGENTS.md, ajoute en tête @AGENTS.md et laisse AGENTS.md gérer les commandes globales.
3. Installe claude-mem si tu veux mémoire persistante : npx claude-mem install (optionnel mais recommandé).
4. Test rapide : lance Claude Code, demande Fix le bug X dans packages/frontend et observe si l’agent utilise les commandes listées.
5. Si l’agent oublie, raccourcis encore le fichier (supprime lignes non actionnables).

---

Pièges courants & comment les éviter

• “Je mets tout pour être sûr” → résultat : l’agent ignore la moitié. Règle : supprime tout ce qui n’est pas demandable.
• “Je génère CLAUDE.md avec un LLM” → dangers : la recherche ETH Zurich montre que les fichiers auto-générés peuvent empirer la performance. Édite à la main.
• “Je ne précise pas le package” → l’agent perd du temps à choisir. Soyez explicite.

---

Et si tu utilises MCP ou plusieurs agents ?

Garde AGENTS.md pour les instructions multi-outils (MCP), et réserves CLAUDE.md aux spécificités Claude (skills, subagents, hooks). MCP permet d’exposer des serveurs (logs, DB, CI) à tous les agents — si tu relies un serveur MCP, indique-le clairement dans la section “Où chercher”.

Pour plus de contexte technique sur MCP et l’interopérabilité, vois notre article détaillé : /blog/fr/2026-04-07-mcp-protocole-standard-agents-ia/

---

Ce qu’il faut retenir

• Un CLAUDE.md pour monorepo doit être : court, package-first, et précis.
• Rédige-le pour corriger des erreurs réelles, pas pour expliquer le projet.
• Installe claude-mem si tu veux persistance entre sessions.

---

Modèle prêt — colle ce fichier dans ton repo, teste en 5 minutes, ajuste selon les retours de l’agent.