Mais après un mois d'utilisation réelle, je suis tombé sur plusieurs problèmes substantiels que ce billet ne couvrait pas. Le principal — une particularité cachée de Claude Code sur laquelle j'ai marché par accident, quand j'ai ajouté le MCP Gmail et qu'il a "disparu" de mon profil cinq minutes plus tard. Aujourd'hui j'ai tout refait sur une nouvelle architecture — compatible XDG, avec un symlink et un sélecteur de profil interactif via gum. C'est la v2 — une évolution issue de l'expérience réelle, pas une amélioration théorique.

Ce qui a commencé à agacer

Quatre choses. Les trois premières concernent la propreté, la visibilité et l'échelle. La quatrième est le vrai piège architectural que je n'avais pas vu tout de suite. Je les passe en revue dans l'ordre, parce que c'est justement la quatrième qui a fini par forcer la refonte.

1. Deux dossiers distincts dans $HOME — c'est le bazar

~/.claude et ~/.claude-promova — deux dotfolders côte à côte à la racine de $HOME. La XDG Base Directory Specification dit que les configs doivent vivre dans ~/.config/. Des dossiers dotfile éparpillés directement dans home, c'est un antipattern qui transforme $HOME en fourre-tout avec le temps. Cosmétique, certes, mais ça m'agaçait à chaque ls -la ~.

2. Pas de confirmation visuelle du profil actif

Je lance claude et je ne sais pas quel profil est actif — tant que je n'ai pas fait claude config list à l'intérieur de la session. Si j'ai oublié quel terminal j'ai lancé où, il faut vérifier. Une broutille, mais avec personal + work qui tournent en parallèle dans deux onglets, ça s'accumule.

3. Les alias ne passent pas à l'échelle

Deux profils — claude et claude-promova — c'est OK. Un troisième s'ajoute (un client freelance) — il faut un troisième alias. Un quatrième — un quatrième. Au bout de six mois, je ne me souviendrais plus quels alias j'ai vraiment créés.

4. Le piège caché de ~/.claude.json

Et c'est la vraie raison de la refonte. Claude Code a deux endroits distincts de configuration, et la doc ne le crie pas : ~/.claude/ — le répertoire qui contient projects/, sessions/, hooks/, skills/. Et séparément — ~/.claude.json, un fichier directement à la racine de $HOME, où vivent oauthAccount, mcpServers, l'historique projects, skillUsage et environ 40 autres champs de véritable état live.

La commande claude mcp add --scope user écrit précisément dans ce ~/.claude.json à la racine du home, et pas dans ~/.claude/.claude.json ni dans le répertoire du profil. Je ne le savais pas. Jusqu'au jour où je suis tombé dedans.

Discovery : pourquoi le MCP Gmail a "disparu"

Ce matin je mettais en place le MCP Gmail dans Claude Code. Setup classique : projet Google Cloud, credentials OAuth, claude mcp add gmail --scope user -- npx -y @gongrzhe/server-gmail-autoauth-mcp. Tout va bien. Session redémarrée — ça marche, je lis mes mails, je réponds. Une heure plus tard on a commencé à refactoriser les alias en fonction avec sélecteur de profil gum, puis on a tout migré vers XDG. J'ai fait mv ~/.claude → ~/.config/claude-profiles/personal, redémarré CC, choisi personal dans le menu. Et dans la nouvelle session, j'ai ouvert /mcp :

figma            (failed)
playwright-test
claude.ai Notion

Pas de gmail. Pas de vaultforge. Juste trois serveurs, dont un même en failed. Alors que je venais d'ajouter Gmail. Pendant ce temps, la session dans un autre terminal (profil work) affichait Gmail et Vaultforge sans le moindre souci.

Je me suis mis à creuser et j'ai découvert que j'avais sur ma machine trois fichiers différents portant le nom .claude.json :

Le voilà. C'est ça, le piège architectural :

1. claude mcp add --scope user écrit toujours dans ~/.claude.json à la racine du home, indépendamment de CLAUDE_CONFIG_DIR
2. Quand CLAUDE_CONFIG_DIR est défini, Claude Code lit $CLAUDE_CONFIG_DIR/.claude.json — donc le fichier à l'intérieur du profil
3. Les entrées "user-scope MCPs" et "MCPs du profil" vivent dans des fichiers différents portant le même nom — et il est facile de les confondre

Dans mon cas, ~/.claude.json (racine du home, 113 KB) était l'état vivant et à jour — avec gmail, vaultforge, la session OAuth, tout. Et ~/.config/claude-profiles/personal/.claude.json (29 KB) s'est avéré être un vieux snapshot qui traînait déjà avant dans l'ancien ~/.claude/ — peut-être qu'une ancienne version de CC y écrivait, peut-être un plugin. jq -r 'keys[]' sur les deux fichiers a montré que la version racine-home avait 41 clés uniques absentes du snapshot.

Et ces 41 clés ne sont pas du déchet. C'est le véritable état de Claude Code :

• skillUsage — statistiques d'utilisation des skills
• githubRepoPaths — cache des repos pour la navigation projet
• cachedGrowthBookFeatures + cachedStatsigGates — feature flags (sans elles, CC va en chercher de fraîches à chaque démarrage)
• hasShownOpus45Notice, hasShownOpus46Notice, hasShownS1MWelcomeV2 — flags UI (sans elles, les modales reviennent au prochain lancement)
• lastPlanModeUse, feedbackSurveyState, installMethod — état d'onboarding et UX

Si tu fais simplement mv ~/.claude ~/.config/claude-profiles/personal sans merge — tu perds tout ça. Tu revois les modales de welcome, la recherche githubRepoPaths se relance, toutes les sollicitations de survey reviennent. Ce que j'ai failli faire.

La nouvelle architecture

Tout vit sous un unique répertoire parent dans ~/.config/, comme le veut XDG. Chaque profil est autosuffisant — il a tout son état, y compris son propre .claude.json. ~/.claude reste un symlink vers le profil personal pour la rétrocompatibilité.

~/.config/claude-profiles/
├── personal/
│   ├── .claude.json          ← full live state + MCP list (113 KB)
│   ├── projects/, sessions/, hooks/, skills/, ...
│   └── CLAUDE.md
└── promova/
    ├── .claude.json          ← work state + work MCPs (41 KB)
    └── projects/, sessions/, agents/, skills/, ...

~/.claude  →  symlink to ~/.config/claude-profiles/personal/

Aucun .claude.json à la racine de $HOME. Chaque profil est un répertoire isolé séparé qui contient tout : les dossiers projects/sessions et ce même fichier avec les serveurs MCP et les tokens OAuth. Une seule source of truth par profil.

Pourquoi le symlink pointe vers personal

Tout ce qui code en dur le chemin ~/.claude/ — vieux scripts, plugins, extensions IDE de Claude Code, configs de statusline comme claude-powerline.json — continue à fonctionner sans changement. Le symlink se résout vers le profil personal. Si par accident tu lances command claude (en court-circuitant la fonction wrapper) — tu atterris aussi dans personal via le lookup du chemin par défaut. Personal devient le "quiet default" qu'il était avant, mais vit désormais physiquement à l'emplacement XDG.

Sélecteur interactif au lancement — fonction + gum

À la place des alias — une fonction claude() dans ~/.zshrc qui affiche un menu fléché via gum (le TUI-helper de Charm). La fonction intercepte l'appel à claude au niveau du shell, laisse choisir un profil et lance command claude avec le CLAUDE_CONFIG_DIR correspondant. command est crucial — ça contourne la fonction wrapper et invoque le vrai binaire.

# brew install gum

# Claude Code: profile picker on launch
claude() {
  local profile
  profile=$(gum choose \
    --header "Claude profile:" \
    --cursor "▸ " \
    --selected.foreground 212 \
    --cursor.foreground 212 \
    --header.foreground 244 \
    "personal" "promova") || return
  case "$profile" in
    personal) CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/personal" command claude "$@" ;;
    promova)  CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/promova"  command claude "$@" ;;
  esac
}

Ce que ça donne au lancement :

Claude profile:
▸ personal
  promova

↑↓ pour naviguer, Enter pour choisir, Esc pour annuler (Claude ne démarre simplement pas). Le profil est toujours visible — impossible de l'oublier.

Script de migration

Pour celles et ceux qui lisent ça et veulent quitter l'ancien schéma. L'étape la plus critique est la deuxième : elle fusionne ~/.claude.json de la racine du home avec ce qui se trouve déjà dans le profil personal, en combinant les listes mcpServers. Sans cette étape, le profil perd à la fois ses MCPs et tout son état live.

# 1. Move existing dotfolders into a new XDG-style parent.
#    APFS mv is an inode rename — safe even if claude --resume is open in
#    another terminal, file descriptors stay alive on the same inode.
mkdir -p ~/.config/claude-profiles
mv ~/.claude          ~/.config/claude-profiles/personal
mv ~/.claude-promova  ~/.config/claude-profiles/promova   # rename as needed

# 2. CRITICAL: merge ~/.claude.json (the live state — likely 100+ KB) into
#    the personal profile, unioning mcpServers so no MCP is dropped.
jq -s '.[0] * {mcpServers: (.[0].mcpServers + .[1].mcpServers)}' \
  ~/.claude.json \
  ~/.config/claude-profiles/personal/.claude.json \
  > /tmp/personal-merged.json
mv /tmp/personal-merged.json ~/.config/claude-profiles/personal/.claude.json

# 3. Fix permissions — jq+mv inherits umask (likely 644), but this file
#    holds OAuth tokens. Tighten to 600 immediately.
chmod 600 ~/.config/claude-profiles/personal/.claude.json

# 4. Back up the orphaned home-root file (delete once verified)
mv ~/.claude.json ~/.claude.json.migrated.bak

# 5. Symlink for backward compatibility (statusline configs, IDE plugins,
#    anything that hardcodes ~/.claude/ keeps working unchanged)
ln -s ~/.config/claude-profiles/personal ~/.claude

La troisième étape, sur les permissions, est importante en soi. jq | mv crée un fichier avec umask 644 (world-readable). Il contient des tokens OAuth. chmod 600 juste après le merge est obligatoire.

Après la migration — ferme et rouvre toutes les sessions Claude actives, recharge le shell (source ~/.zshrc ou nouveau terminal), lance claude, choisis un profil, vérifie via claude mcp list que tous les MCPs sont en place. Si tout va bien — supprime ~/.claude.json.migrated.bak. Si quelque chose cloche — le rollback est trivial : mv ~/.claude.json.migrated.bak ~/.claude.json et on retire le symlink.

Ce que tu gagnes

• Un unique répertoire parent au lieu de deux dotfolders dans $HOME — compatible XDG
• Le symlink préserve la compatibilité avec tout ce qui code en dur ~/.claude/
• Chaque profil est autosuffisant — son état complet et ses MCPs vivent dans son propre .claude.json
• Une seule source of truth par profil — fini la config orpheline à la racine du home qui dérive silencieusement par rapport à celle du profil
• Les données sensibles (oauthAccount, tokens) ont des permissions 600 garanties
• Confirmation visuelle du profil actif à chaque lancement — impossible d'oublier quel profil est actif
• Ajouter un troisième profil = ajouter une ligne dans le case de la fonction, pas cloner un nouvel alias et retenir son nom

Là où ça pèche

Je veux être honnête. Ce n'est pas une amélioration gratuite — quelques compromis viennent avec, et autant les connaître à l'avance.

• gum est une dépendance supplémentaire (brew install gum, ~13 MB). Si par principe tu ne veux pas l'installer — fallback sur select de zsh ou un simple read. Ça fonctionne, mais c'est moins joli et il n'y a pas de navigation aux flèches.
• Un Enter à chaque lancement. Pour qui lance claude des dizaines de fois par jour — ça peut agacer. Alternative en dessous (direnv).
• Le symlink ~/.claude → personal fait de personal le profil par défaut. S'il te faut le profil work par défaut — il faut rediriger le symlink (ln -sf). Pas compliqué, mais ce n'est pas "j'oublie et rien ne casse".
• Le symlink peut théoriquement casser si un outil réécrit ~/.claude.json de façon atomique via un pattern temp+rename (write-file-atomic). En pratique Claude Code lui-même ne le fait pas, mais si tu installes des plugins tiers — vérifie.
• Si tu as des comptes Anthropic différents sur les profils, avec des plans différents — après un switch il peut y avoir un lag inférieur à la seconde le temps que Claude Code synchronise l'état OAuth. Dans mon usage c'est imperceptible, mais ce n'est pas nul.

Alternatives que j'ai considérées

direnv — positionne automatiquement CLAUDE_CONFIG_DIR en fonction d'un .envrc à la racine de chaque projet. Zéro interaction, zéro clic. Inconvénient : il faut poser un .envrc dans chaque work-root, et si tu lances claude dans un dossier non reconnu — tu récupères le profil par défaut (peut-être pas celui que tu voulais). Pour qui vit dans un nombre limité de work-roots et veut ne jamais cliquer — direnv est franchement meilleur.

Switching basé sur symlink (un unique profil actif en redirigeant le symlink ~/.claude) — je l'ai aussi envisagé puis écarté immédiatement. Tu ne peux pas avoir deux terminaux ouverts avec des profils différents en même temps — le "courant" global est unique. Pour moi c'est un deal-breaker.

Conclusion

La v2 n'est pas juste une meilleure UX par-dessus la v1. C'est la reconnaissance que Claude Code a une particularité architecturale cachée (~/.claude.json en tant que fichier séparé à la racine du home, écrit par les commandes --scope user indépendamment de CLAUDE_CONFIG_DIR) qu'il faut prendre en compte si on veut une vraie isolation entre profils. La première approche (~/.claude + ~/.claude-promova + alias) marchait à 80 %, mais les 20 % restants se manifestaient par une dérive silencieuse de l'état entre profils. C'est désormais pris en compte. Si tu débutes — démarre directement en v2. Si tu es déjà en v1 — le script de migration est plus haut, le déménagement prend cinq minutes et ne casse rien (le merge jq est précisément l'étape qui te sauve de la perte d'état).

Deux règles ont transformé mes workflows truffés d'hallucinations en pipelines fiables : un agent, une spécialisation, et tout ce qui peut tourner comme une commande shell doit tourner comme une commande shell. Ce n'est pas de la théorie. C'est ce que je fais tous les jours avec Claude Code, et ce sont les patterns qui font vraiment bouger les choses.

Pourquoi les agents généralistes mentent

Les LLMs prédisent le token suivant. Quand un prompt demande deux rôles — construis X et vérifie X — le modèle finit le premier rôle, puis prédit à quoi ressemblerait le résultat du second, sans l'exécuter réellement. L'auto-vérification est structurellement faible : même contexte, même modèle, mêmes angles morts. Le pass de la vérification est corrélé avec le pass de la construction — ils échouent ensemble.

Le modèle ne sait pas qu'il ment. De son point de vue, narrer j'ai tout vérifié soigneusement est une continuation cohérente d'avoir écrit le code. C'est la même raison pour laquelle les prompts du type tu es sûr ? ne détectent pas les hallucinations : le modèle est tout aussi confiant au second passage. La confiance n'est pas corrélée avec la correction — elle est corrélée avec la plausibilité de la prochaine phrase.

La solution n'est pas de meilleurs prompts. Sois prudent, vérifie deux fois, n'hallucine pas — ces instructions ne servent à rien. La solution est structurelle : spécialise l'agent pour qu'il ne puisse physiquement pas faire semblant, et fais passer le travail quantitatif par le shell pour que la réponse vienne d'un état réel, pas d'une probabilité de tokens.

Règle 1 : un agent, une spécialisation

Divise le travail en agents séparés avec des contextes séparés. Chaque agent a une seule responsabilité et un jeu d'outils resserré. L'ensemble du workflow devient un relais plutôt qu'un seul agent qui tourne en rond :

• Agent Builder : prend le spec, écrit le code. C'est son seul boulot. Il dispose de Read, Edit, Write, Bash.
• Agent Reviewer : prend le spec plus le diff, vérifie les critères d'acceptation. Contexte vierge. Aucune connaissance de comment le code a été écrit, seulement ce qui en est sorti. Il dispose de Bash, Read, Grep, Glob — aucun outil d'écriture.
• Agent Analytics : répond aux questions sur les données en construisant et en exécutant des requêtes. Bash uniquement. Ne peut pas atteindre la réponse sans lancer une vraie commande.
• Orchestrateur : la session principale qui envoie chaque agent à tour de rôle et ne demande jamais à un agent de faire le travail d'un autre.

Exemple concret : implémentation d'une UI plus une vérification visuelle contre une maquette Figma. Le Builder écrit les composants et commite le diff. L'orchestrateur invoque ensuite le Reviewer avec l'URL du design, le diff, et des critères d'acceptation explicites. Le Reviewer lance Playwright, prend des screenshots, les diffe contre la référence, et retourne PASS ou FAIL avec les chemins de screenshots réels et les pixel diffs. Le Builder ne s'approche jamais de l'étape de vérification — ce qui est exactement pourquoi la vérification est réelle.

L'anti-pattern, c'est le méga-agent : un seul prompt qui dit implémente cette UI et assure-toi qu'elle correspond à la maquette. Je te garantis qu'il déclarera que tout correspond. Ce ne sera pas le cas. Le récit j'ai vérifié est simplement la séquence de tokens la plus probable après je l'ai construit.

Règle 2 : le shell plutôt que le prompt, toujours

Tout ce qui est quantitatif, tout ce qui touche à un état réel, tout ce où la réponse peut être fausse tout en semblant juste — fais-le passer par sh. Le rôle de l'agent est de construire et d'exécuter la commande, puis de lire sa sortie. L'agent n'est pas la source de vérité. La sortie du shell l'est.

• Comptage : wc -l logs.txt, c'est vrai. Il y a environ 47 lignes de log venant d'un modèle, c'est une hallucination.
• Analytics : psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". Pas estime le volume.
• Tests : pnpm test --reporter=json | jq '.numFailedTests'. Pas résume ce qui a planté.
• État Git : git rev-list --count main..HEAD, git diff --stat. Pas compte les commits ni décris les changements.

Une fois que tu as intégré ça, tu commences à remarquer chaque endroit où l'agent allait inventer un nombre. Il semblerait qu'il y ait environ 200 enregistrements... — non. Lance SELECT count(*). La plupart des tests passent... — non. Lance la suite de tests, parse le JSON. Le modèle est excellent pour construire la commande. Il est peu fiable pour être la commande.

Modes d'échec que j'ai réellement rencontrés

Ce ne sont pas des hypothèses. Chacun m'a coûté du temps réel avant que je change de pattern :

• Vérification fantôme. L'agent a dit j'ai vérifié les 14 sections contre la maquette. Il n'avait pas ouvert la maquette. Il n'avait pas pris de screenshot. La vérification était une étape hallucinée dans le récit.
• Mauvais chiffres assénés avec confiance. J'ai demandé les monthly active users à partir des données analytics. J'ai obtenu un chiffre faux d'un facteur ~3. Le modèle avait interpolé à partir de quelques lignes d'exemple au lieu de lancer la vraie requête.
• Modifications de fichiers inventées. L'agent a dit j'ai mis à jour config/feature-flags.json. Ce n'était pas le cas. Il avait seulement eu l'intention de le faire. git diff était vide.
• Faux passages de tests. Tous les tests passent. Aucun test n'avait été exécuté. L'agent n'avait jamais invoqué le test runner — il avait prédit à quoi aurait ressemblé la sortie du test runner.

Les quatre sont résolus par les mêmes deux règles : découpe l'agent, pousse vers le shell. Le Reviewer n'a pas Write, donc il ne peut pas faire semblant d'éditer des fichiers. L'agent Analytics n'a que Bash, donc il ne peut pas retourner un nombre qui ne vient pas d'une requête. L'impossibilité structurelle bat les bonnes intentions à chaque fois.

Comment structurer ça dans Claude Code

Claude Code prend en charge les sub-agents définis dans .claude/agents/*.md. Chaque fichier d'agent déclare un nom, une description, un jeu d'outils autorisé, et un system prompt. L'orchestrateur (ta session principale) les dispatche via l'outil Agent. Voici le type de définition que j'utilise pour le reviewer — courte, ciblée, et physiquement incapable d'écrire du code :

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Remarque le jeu d'outils : Bash, Read, Grep, Glob. Pas de Write, pas d'Edit, pas d'Agent. Le Reviewer peut exécuter des commandes, lire des fichiers, chercher des patterns — et rien d'autre. S'il essaie de faire passer un diff halluciné pour vérifié, la forme de ses appels d'outils le rend évident : il n'y a eu aucune vraie vérification. Tu peux auditer les appels d'outils et voir exactement ce qui a été inspecté.

Le pattern d'orchestration : la session principale appelle le Builder → attend → lance elle-même git diff pour capturer le changement réel → appelle le Reviewer avec le spec et le diff → lit le verdict du Reviewer. La session principale ne demande jamais à un seul agent de faire les deux. Les restrictions d'outils sont plus fortes que les instructions dans le prompt : ne fais pas semblant de vérifier, c'est un vœu. Ne pas avoir Write, c'est un fait.

Anti-patterns à abandonner

Des choses que je vois dans les prompts qui ne servent à rien — ou pire, donnent une fausse impression de sécurité :

• Sois prudent et vérifie bien ton travail. Ne génère aucun comportement supplémentaire. Le modèle produit déjà ce qui ressemble à un travail soigné.
• Assure-toi de vraiment vérifier. Le mot vraiment n'ajoute pas de sémantique sur laquelle le modèle peut agir. Il vraiment affirmera avoir vérifié.
• N'hallucine pas. Un mème du prompt engineering. L'hallucination n'est pas un interrupteur que le modèle peut éteindre.
• Faire confiance à l'agent sur les petits chiffres. C'est sur les petits chiffres qu'il ment avec le plus de confiance. Il n'y a pas de plancher d'honnêteté.
• Ajouter plus de règles dans le prompt pour forcer l'honnêteté. Les corrections structurelles (découpage + shell) battent les ajustements de prompt à chaque fois. Si une règle doit être appliquée, encode-la dans l'accès aux outils, pas en français.

Si ta stratégie pour attraper les hallucinations, c'est des formulations plus emphatiques, tu n'as pas de stratégie. Tu as un espoir.

Le modèle mental

Un agent n'est pas un collègue. C'est une fonction : prompt → tokens. La fonction est excellente pour écrire du code et très mauvaise pour s'introspecter et savoir si elle a fait la bonne chose. Traite ses affirmations sur son propre travail comme des hypothèses. Le diff, le code de sortie, le screenshot, le nombre de lignes — voilà les preuves. Le résumé en fin de tour est la surface la plus mensongère de tout le système.

La spécialisation est ton assurance contre la dérive narrative. Le shell est ta seule ground truth. Le Builder écrit. Le Reviewer vérifie. Bash décide.

Conclusion

Si tu ne retiens qu'une chose : ne laisse pas un seul agent à la fois produire et juger son propre résultat, et ne laisse aucun agent répondre à une question quantitative sans exécuter une commande. Tout le reste découle de ces deux règles. Configure l'accès aux outils de façon agressive, audite les appels d'outils plutôt que les résumés, et la surface d'hallucination rétrécit de partout à quelques endroits précis où tu sais déjà regarder.

Le problème

Claude Code stocke tout dans ~/.claude par défaut — token OAuth, historique des conversations, CLAUDE.md global, mémoire des projets, configurations des serveurs MCP et paramètres. Avec deux comptes, tu as besoin de deux mondes complètement séparés :

• Compte personnel : ton abonnement Max/Pro, CLAUDE.md personnel avec tes préférences, tes serveurs MCP (Obsidian, outils personnels)
• Compte entreprise : plan géré par l'entreprise, CLAUDE.md de travail avec instructions d'intégration Jira/Slack, serveurs MCP corporate
• Sessions OAuth différentes : impossible d'être connecté à deux comptes dans le même répertoire de configuration
• Mémoire de projets séparée : tu ne veux pas que le contexte des projets professionnels fuie dans les sessions personnelles et vice versa

Se déconnecter et reconnecter à chaque changement de contexte n'est pas une option. Tu perds l'état de session, et c'est tout simplement pénible.

La solution : CLAUDE_CONFIG_DIR

Claude Code respecte une seule variable d'environnement : CLAUDE_CONFIG_DIR. Définis-la sur n'importe quel chemin et Claude utilisera ce répertoire au lieu de ~/.claude pour tout — auth, historique, paramètres, mémoire. L'installation complète prend 60 secondes.

Étape 1 : Créer un second répertoire de configuration

Choisis un nom qui correspond à ton cas d'usage :

mkdir ~/.claude-work

C'est tout. Claude le remplira avec la structure nécessaire au premier lancement.

Étape 2 : Authentifier le second compte

Lance Claude une fois avec le nouveau répertoire de configuration pour déclencher le login OAuth :

CLAUDE_CONFIG_DIR=~/.claude-work claude

Le navigateur s'ouvre. Connecte-toi avec ton compte entreprise. Le token OAuth est stocké dans ~/.claude-work — complètement séparé de ta session personnelle dans ~/.claude.

Étape 3 : Ajouter un alias shell

Ajoute ceci à ta configuration shell pour ne pas avoir à retenir la variable :

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Recharge ton shell :

source ~/.zshrc

Ce que tu obtiens

Tu as maintenant deux environnements Claude complètement isolés :

• claude — lance avec ton compte personnel, CLAUDE.md personnel, mémoire personnelle
• claude-work — lance avec ton compte entreprise, CLAUDE.md de travail, mémoire séparée
• Historique isolé : les conversations de travail restent au travail, le personnel reste personnel
• Serveurs MCP séparés : ton MCP Obsidian personnel n'apparaît pas dans les sessions de travail
• Paramètres indépendants : outils autorisés différents, niveaux de permissions différents, préférences de modèle différentes par compte

Comment ça fonctionne sous le capot

Le répertoire de configuration est la source unique de vérité pour l'état de Claude Code. Voici ce qui vit à l'intérieur de chacun :

~/.claude/              ← personal account
├── CLAUDE.md           ← personal global instructions
├── projects/           ← personal project memory
├── settings.json       ← personal permissions & MCP servers
└── ...                 ← OAuth session, history, cache

~/.claude-work/         ← corporate account
├── CLAUDE.md           ← company-specific instructions (Jira, Slack, etc.)
├── projects/           ← separate project memory
├── settings.json       ← different MCP servers, permissions
└── ...                 ← separate OAuth session

Quand tu lances claude-work, Claude lit tout depuis ~/.claude-work. Il ignore l'existence de ~/.claude. Les deux instances sont complètement indépendantes — tu peux même les faire tourner simultanément dans différents onglets du terminal.

Passage à N comptes

Le pattern s'étend à n'importe quel nombre de comptes. Freelance avec plusieurs clients ? Ajoute plus d'alias :

# Personal (default — no alias needed)
# Just run: claude

# Corporate
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

# Freelance client
alias claude-client='CLAUDE_CONFIG_DIR=~/.claude-client claude'

Chaque alias a son propre répertoire de configuration, sa propre session OAuth, son propre CLAUDE.md avec des instructions spécifiques au client.

Conseils pratiques

• Nomme les répertoires clairement : ~/.claude-work, ~/.claude-clientname — tu te remercieras quand il y en aura trois ou quatre
• Écris un CLAUDE.md dédié pour chacun : celui du travail peut inclure les instructions de l'entreprise (créer des tickets Jira, canaux Slack, procédures de déploiement). Le personnel reste minimaliste.
• Serveurs MCP différents par compte : configure les outils de travail (Jira MCP, Slack MCP, APIs internes) uniquement dans la config de travail. Garde ta config personnelle propre.
• Vérifie quel compte est actif : lance claude config list dans une session si tu as un doute — ça affiche le chemin vers le répertoire de configuration

Les limites de cette approche

CLAUDE_CONFIG_DIR isole par compte, pas par projet. À l'intérieur d'un même profil, Claude voit tous les serveurs MCP que tu as un jour enregistrés pour ce compte — à travers l'ensemble de tes projets. Pour un usage perso en solo, ça reste généralement acceptable. Dès que tu as plusieurs projets critiques en production sous un même compte, surtout dans des domaines qui se chevauchent comme la facturation, l'outillage admin ou l'infrastructure, ça introduit un risque concret entre projets : un assistant IA peut appeler un outil du projet A en travaillant sur le projet B, en particulier quand les deux exposent des opérations aux noms similaires.

Le pattern de profil répond à la question which account am I in?. Il ne répond pas à la question which project's tools should be active right now?. Pour du travail à enjeux plus élevés, empile une seconde couche d'isolation par-dessus le découpage par comptes :

• Un profil par projet critique en production, pas seulement par compte : au lieu de ~/.claude et ~/.claude-work, crée ~/.claude-work-billing et ~/.claude-work-admin. Chaque profil ne voit que les serveurs MCP dont il a réellement besoin.
• MCP au niveau projet via .mcp.json : commit un .mcp.json à la racine du projet listant uniquement les serveurs MCP de ce projet. Claude les charge quand il est lancé depuis ce répertoire. Garde ta config globale minimale — uniquement les outils universels (notes, recherche), aucun endpoint de production.
• Nomme les serveurs MCP sans ambiguïté : évite les noms génériques comme admin, billing, mcp-server. Préfixe avec le projet : acme_billing_prod, acme_admin_stage. Un nom descriptif force une pause quand quelque chose est sur le point d'être appelé depuis le mauvais contexte.
• Vérifie chaque appel d'outil MCP avant approbation : les appels comme *_create_*, *_delete_*, *_charge_* méritent un second regard délibéré. La vitesse gagnée par une auto-approbation systématique s'évapore la première fois qu'un outil du mauvais projet tire en production.

La règle générale : découpe les profils agressivement, garde le MCP de niveau production hors du profil par défaut, et traite tout chevauchement de noms d'outils entre projets comme un smell qui mérite un refactoring.

Conclusion

Une variable d'environnement. Un alias. Isolation totale entre les comptes. Pas de danse logout/login, pas de conflits de configuration, pas de fuite de contexte. Le genre de solution presque décevante de simplicité — mais c'est exactement ce qui la rend bonne. Configure une fois et n'y pense plus jamais.

Qu'est-ce que MCP et pourquoi ce n'est pas si simple

MCP (Model Context Protocol) est un protocole ouvert d'Anthropic qui permet à Claude de se connecter à des outils et des données externes. Le principe est simple : un serveur local tourne, expose des "outils" (tools), et Claude les appelle pendant la conversation.

Pour Obsidian, il existe théoriquement beaucoup de serveurs MCP. En pratique — chacun a ses propres problèmes.

Le problème principal de l'écosystème Obsidian : Obsidian est une application fermée sans MCP officiel. La communauté a comblé le vide, mais chaque implémentation suit son propre chemin, et aucune n'a de "bénédiction officielle".

Tentative 1 : MarkusPfundstein/mcp-obsidian

Le premier outil trouvé lors de la recherche. 3 400 étoiles sur GitHub, dans tous les tutoriels. Semble être un choix sûr.

Comment ça fonctionne : serveur Python basé sur le plugin Local REST API d'Obsidian. Le serveur communique avec le plugin via HTTPS, le plugin effectue les opérations via l'API d'Obsidian.

Ce qui a mal tourné

• Pas mis à jour depuis 17 mois
• 85 issues ouvertes
• Pas de move/rename — seulement read, write, append, delete
• Local REST API a un bug documenté de perte de données : le endpoint POST peut silencieusement écraser un fichier lors d'un append

Pas adapté au refactoring — nous avons besoin de déplacer des fichiers et de préserver les liens. On continue.

Tentative 2 : aaronsb/obsidian-mcp-plugin

Trouvé une option qui fonctionne comme un plugin natif Obsidian. Cela signifie un accès direct à l'API interne d'Obsidian — backlinks, Dataview, graphe de liens. Move via l'API native met à jour tous les wiki-links automatiquement, car Obsidian gère cela lui-même.

Difficultés d'installation

• Le plugin n'est pas dans le catalogue officiel d'Obsidian (PR en attente avec des erreurs de validation)
• Installation obligatoire via BRAT (Beta Reviewers Auto-update Tool)
• Claude Desktop n'accepte pas le Bearer token directement via l'UI — a forcé l'activation de HTTPS dans le plugin
• Le certificat self-signed pour localhost crée des problèmes de confiance

À travers tous ces contournements, j'ai finalement réussi à le connecter. Test basique — vault.move réécrit bien les [[wikilinks]], fonctionne comme prévu.

Ce qui a mal tourné en production

Quand j'ai commencé le refactoring massif (drag-and-drop de dizaines de dossiers dans Obsidian + opérations MCP simultanées), le serveur a figé pendant 4+ minutes. Pourquoi : le plugin tourne à l'intérieur d'Obsidian. Quand Obsidian réindexe des milliers de fichiers après un changement massif de structure, le plugin se bloque avec.

Conclusion : la dépendance à une instance Obsidian ouverte et son index est fatale pour les opérations en masse.

Tentative 3 : @bitbonsai/mcpvault

Logiquement — il faut un serveur qui ne dépend pas d'Obsidian. Travaille directement avec les fichiers sur le disque. @bitbonsai/mcpvault — recommandé dans de nombreux avis. Accès direct au système de fichiers, configuration simple (npx @bitbonsai/mcpvault@latest /path/to/vault), 14 outils. Obsidian n'a même pas besoin d'être ouvert.

Avant d'installer, j'ai vérifié un point critique — est-ce que les wiki-links se mettent à jour lors d'un move. J'ai trouvé un avis utilisateur :

Le connecteur filesystem ne sait pas qu'il est dans Obsidian — il voit un dossier de fichiers <code>.md</code> et c'est tout. Ne sait pas que les noms de fichiers portent un poids sémantique, que chaque <code>[[wikilink]]</code> cassera au moment d'un rename ou move. L'auto-update des liens ne fonctionne que quand le rename se fait depuis l'intérieur de l'app. Je l'ai appris après avoir demandé à Claude de nettoyer les noms de fichiers et suis revenu à un dashboard avec la moitié des liens cassés.

Confirmé dans la documentation même de mcpvault : PR #101 (wiki link resolution) est en review, pas mergé. Donc déplacer via mcpvault casserait la moitié du vault. Pas adapté.

Tentative 4 : VaultForge (Final)

blacksmithers/vaultforge — spécialement conçu pour les agents IA qui font du refactoring.

Architecturalement correct

• Direct filesystem — ne dépend pas d'Obsidian
• Moteur wikilink propre — implémente la logique de résolution [[wikilink]] qui met à jour toutes les formes (stem, chemin complet, alias, embed)
• Dry run par défaut sur toutes les opérations destructives — montre d'abord ce qui va changer, puis vous confirmez
• 27 outils contre 8–14 chez les concurrents : batch_rename, update_links, backlinks (impact analysis), prune_empty_dirs, frontmatter, smart_search (BM25), vault_themes (TF-IDF clustering)
• Licence MIT, TypeScript, zéro sous-dépendance
• Installation en 30 secondes via .mcpb (extension one-click pour Claude Desktop)

Test de sécurité sur fichiers isolés

Créé 4 fichiers test avec des liens croisés — liens stem, liens avec alias, liens avec chemin complet. Déplacement d'un fichier dans un sous-dossier :

delta.md → subfolder/delta-renamed.md

VaultForge a affiché un dry run : "1 fichier sera renommé, 3 liens seront mis à jour". Exécuté pour de vrai.

Vérifié après — les trois types de liens se sont mis à jour correctement. C'est exactement ce qui manquait à tous les outils précédents.

Comment installer VaultForge — Instructions finales

Si vous avez macOS et Claude Desktop :

Étape 1

Téléchargez le fichier .mcpb :

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb \
  -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

Étape 2

Claude Desktop ouvrira le dialogue d'installation d'extension. Entrez le chemin absolu vers votre vault — pas de backslashes, espaces normaux :

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault

Étape 3

Cliquez sur Save. Claude Desktop ajoutera l'extension à la configuration automatiquement. Pas de redémarrage nécessaire — les extensions .mcpb sont détectées automatiquement.

Étape 4

Vérifiez : dans un nouveau chat, demandez : "What is the status of my Obsidian vault?" — devrait retourner quelque chose comme totalFiles: 416, totalDirs: 135, ...

Ce que j'ai appris sur l'écosystème MCP d'Obsidian

Premièrement, "le plus populaire" ne signifie pas "fonctionnel". MarkusPfundstein/mcp-obsidian a 3 400 étoiles et est la recommandation par défaut, mais il est obsolète et il lui manque des opérations clés.

Deuxièmement, un plugin natif a un coût caché. Le plugin aaronsb semblait idéal — graph, Dataview, move natif. Mais la dépendance à une instance Obsidian ouverte et son index le rend inadapté aux opérations massives sérieuses.

Troisièmement, filesystem direct sans link-engine est un piège. Mcpvault est rapide et simple, mais "juste déplacer des fichiers" détruit la structure du vault. Les liens portent une sémantique imposée que le filesystem ne connaît pas. Sans sa propre implémentation de logique wikilink, l'outil devient une mine.

Quatrièmement, testez sur des données isolées. Avant de confier un refactoring massif à un outil — créez un dossier test avec 4–5 fichiers avec des liens croisés et regardez ce qui se passe. 5 minutes de test économisent des heures de récupération depuis un backup.

Cinquièmement, gardez un backup git de votre vault. Le plus important de tout. Un seul git init à l'intérieur du vault et des commits périodiques — c'est l'assurance contre toute erreur d'un agent IA ou d'un outil. Si quelque chose casse — git reset --hard ramène tout.

Conclusion

Le parcours a pris plusieurs heures et trois tentatives échouées. L'architecture finale ressemble à ceci :

• VaultForge — l'outil de travail principal. Filesystem direct + moteur wikilink propre + 27 outils = refactoring stable à toute échelle.
• Git — versionnage du vault. Rollback gratuit pour toute erreur.

Maintenant je peux faire ce pour quoi tout a commencé : demander à Claude d'organiser 400 notes en une architecture PARA propre, fusionner les doublons, ajouter du frontmatter, construire des cartes MOC. Chaque opération est sûre, les liens sont préservés, le dry run montre ce qui se passera avant que quelque chose ne change.

Si vous aussi vous regardez votre Obsidian encombré et voulez un assistant IA — commencez directement avec VaultForge. Ne répétez pas mon parcours à travers des projets morts, des plugins beta et des serveurs filesystem sans logique de liens.

Et si chaque trou noir était un Big Bang d'un nouvel univers ? Cet article explore l'idée que notre univers pourrait n'être qu'un noeud dans un arbre récursif infini — où les trous noirs engendrent des sous-univers, l'énergie revient par le rayonnement de Hawking, et les lois fondamentales de la physique sont délibérément conçues pour rendre tout contact entre univers impossible.

Trou noir = univers

L'idée est née d'un moment de réflexion : un trou noir se forme lorsque suffisamment de masse et de pression se concentrent en un seul point. Cette singularité — densité infinie, courbure infinie — ressemble étrangement aux conditions que nous décrivons pour le Big Bang.

Et si c'était le même événement, observé depuis des côtés différents ? De l'extérieur, nous voyons un trou noir engloutir la matière. De l'intérieur — un nouvel univers explosant à l'existence. La masse et l'énergie qui se sont effondrées dans le trou noir deviennent la matière première d'un cosmos entièrement nouveau, avec ses propres étoiles, ses planètes et, peut-être, ses propres trous noirs.

Chaque trou noir de notre univers pourrait contenir un univers. Et notre univers pourrait exister à l'intérieur d'un trou noir d'un univers parent.

Pourquoi les univers ne peuvent pas entrer en contact

Voici la partie élégante : une fois le passage de l'horizon des événements franchi, il n'y a pas de retour. La relativité générale le garantit — l'avenir de l'univers parent se situe entièrement au-delà de l'horizon des événements, inaccessible depuis l'intérieur. Du point de vue du sous-univers, l'univers parent est déjà terminé. Toute sa ligne temporelle est déjà révolue.

Ce n'est pas une limitation technique que l'on pourrait surmonter avec une meilleure technologie. C'est inscrit dans la géométrie même de l'espace-temps. Les univers sont fondamentalement isolés les uns des autres — non par la distance, mais par la structure du temps.

Le cycle énergétique : emprunter et restituer

Mais l'énergie ne disparaît pas. Le rayonnement de Hawking — le processus quantique par lequel les trous noirs s'évaporent lentement — crée un cycle remarquable :

1. Un univers parent crée un trou noir, transférant de l'énergie dans un sous-univers
2. Le sous-univers vit l'intégralité de son cycle de vie sur des billions d'années
3. Le trou noir s'évapore lentement, restituant l'énergie à l'univers parent via le rayonnement de Hawking
4. L'univers parent récupère son énergie — avec intérêts

Ces « intérêts » sont fascinants : les physiciens pensent désormais que le rayonnement de Hawking préserve l'information. L'univers parent ne récupère pas simplement de l'énergie vide — il reçoit une empreinte de tout ce qui s'est passé à l'intérieur. Chaque étoile formée, chaque planète, chaque instant de conscience — encodé dans le rayonnement.

La récursion jusqu'au bout

Si vous êtes programmeur, le schéma est immanquable. C'est de la récursion. Chaque univers appelle universe() avec moins d'énergie, créant des sous-univers qui créent des sous-sous-univers, jusqu'à ce qu'il n'y ait plus assez d'énergie pour former des trous noirs — le cas de base.

universe(energy)
  ├── creates black holes
  │     ├── universe(energy - n)
  │     │     ├── universe(energy - n - m)
  │     │     │     └── base case: not enough energy for black holes
  │     │     └── returns energy via Hawking radiation
  │     └── returns energy via Hawking radiation
  └── receives all energy back

Le physicien Lee Smolin a formalisé une idée similaire sous le nom de Sélection Naturelle Cosmologique : les univers se « reproduisent » via les trous noirs, et chaque génération possède des constantes physiques légèrement différentes — optimisées au fil d'innombrables cycles pour produire davantage de trous noirs, davantage d'univers.

Où en sommes-nous dans ce cycle ?

Notre univers a environ 13,8 milliards d'années. Cela semble ancien, mais dans le contexte de sa durée de vie totale, nous n'en observons que le tout début :

Nous existons à environ 0,00000000...01 % de la durée de vie totale de notre univers. L'ère des étoiles — tout ce que nous pouvons observer — n'est qu'un bref éclat tout au début. La véritable histoire de l'univers, c'est l'ère lente et patiente des trous noirs créant et évaporant des sous-univers.

La question des dimensions supérieures

Tout ce qui a été discuté jusqu'ici s'inscrit dans notre compréhension tridimensionnelle. Mais si notre univers n'est qu'une « tranche » de quelque chose de dimension supérieure, alors l'arbre récursif entier de trous noirs et de sous-univers pourrait n'être que l'ombre d'une structure que nous ne pouvons pas percevoir.

En 1884, Edwin Abbott a écrit Flatland — l'histoire d'êtres bidimensionnels incapables de concevoir une troisième dimension. Une sphère traversant Flatland apparaît comme un cercle qui grandit puis rétrécit. Les « Flatlandais » peuvent le décrire mathématiquement mais ne comprendront jamais véritablement ce qu'ils observent. Nous pourrions nous trouver dans exactement la même situation vis-à-vis de notre univers.

Qu'est-ce que la conscience ? Pourquoi l'expérience subjective existe-t-elle ? David Chalmers a appelé cela le « problème difficile » — et c'est peut-être la preuve la plus forte que quelque chose opère au-delà de notre portée dimensionnelle.

Tout est verrouillé au niveau fondamental

La prise de conscience la plus frappante n'est pas que nous ne savons pas — c'est que nous ne pouvons pas savoir. Chaque direction de recherche se heurte à une barrière fondamentale :

• Vous voulez voir l'univers parent ? Bloqué par l'horizon des événements
• Vous voulez comprendre la conscience ? Bloqué — un système ne peut pas s'analyser entièrement lui-même (théorèmes d'incomplétude de Gödel)
• Vous voulez savoir ce qu'il y avait « avant » ? Bloqué — le temps a commencé avec le Big Bang
• Vous voulez percevoir des dimensions supérieures ? Bloqué par les limitations cognitives d'un être tridimensionnel

Le philosophe Colin McGinn appelle cela la clôture cognitive : certaines questions sont fermées à l'esprit humain non par manque de données, mais à cause de l'architecture même de l'esprit. La différence entre « nous ne savons pas encore » et « nous ne pouvons pas savoir » est immense.

La seule chose qui reste : le perfectionnement de soi

Si chaque sortie est bloquée par conception — si l'on ne peut regarder au-dehors, ni en arrière, ni vers le haut — alors il ne reste qu'une seule direction : vers l'intérieur. L'univers semble délibérément construit pour forcer l'attention sur soi-même.

Cette conclusion ne vient ni de la religion ni des manuels de philosophie. Elle découle de la logique des trous noirs, de la récursion, de la théorie de l'information et des limites de la cognition. Existentialistes, bouddhistes, stoïciens et physiciens arrivent tous au même point par des chemins différents : le but de l'existence pourrait simplement être le perfectionnement de l'être qui existe.

Nous sommes arrivés à cette conclusion non par la foi, mais par la physique — des trous noirs aux univers récursifs, en passant par les blocages fondamentaux de la connaissance, jusqu'à la seule porte ouverte : devenir meilleur.

Références

• Lee Smolin — Sélection Naturelle Cosmologique
• Stephen Hawking — Rayonnement de Hawking
• David Chalmers — Le Problème Difficile de la Conscience
• Edwin Abbott — Flatland : Un Roman en Plusieurs Dimensions (1884)
• Kurt Gödel — Théorèmes d'Incomplétude

Pour les sites web simples — portfolios, blogs, landing pages, sites de petites entreprises — un CMS traditionnel devient une surcharge inutile. Les outils d'IA comme Claude Code, Cursor et GitHub Copilot peuvent désormais modifier votre code directement, comprendre le contexte, traduire le contenu et déployer les changements via git. La couche d'abstraction que fournissait le CMS est remplacée par une interface plus intelligente : le langage naturel.

La taxe CMS que vous payez

Chaque CMS s'accompagne d'un coût caché. Pas seulement l'abonnement — tout un écosystème de complexité qui enveloppe votre site web pourtant simple :

• Infrastructure : Une base de données à héberger, une API à maintenir, un tableau de bord à sécuriser. WordPress à lui seul représente ~43% du web et ~90% des attaques ciblant les CMS.
• Performance : Génération dynamique de pages, appels API à chaque requête, hydratation côté client des données CMS. Votre portfolio de 3 pages a désormais l'architecture d'un produit SaaS.
• Dépendance au fournisseur : Votre contenu vit dans le schéma de base de données de quelqu'un d'autre. Migrer de Contentful vers Sanity ? C'est un projet, pas un changement de configuration.
• Changement de contexte : Vous éditez du code dans votre IDE, puis basculez vers le tableau de bord CMS dans le navigateur pour modifier un titre. Deux modèles mentaux différents pour ce qui est fondamentalement la même opération.
• Coût : Les tarifs des CMS headless évoluent souvent avec les appels API ou les entrées de contenu. Un blog personnel n'a pas besoin d'une infrastructure de contenu à $99/mois.

Pour un site marketing où 50 personnes éditent du contenu quotidiennement, ce coût est justifié. Pour le portfolio d'un développeur ou la landing page d'une petite entreprise ? Vous construisez un pont pour traverser une flaque.

Ce qui a changé : l'IA comprend votre code

La raison d'être du CMS était simple : les personnes non techniques (et même les développeurs qui ne voulaient pas toucher au code pour des modifications de contenu) avaient besoin d'une interface visuelle pour mettre à jour les sites web. Le code était trop complexe, trop fragile, trop facile à casser.

L'IA a fondamentalement changé cette équation. Les outils d'IA modernes pour le code ne se contentent pas d'autocompléter — ils comprennent la structure du projet, lisent les patterns existants et effectuent des modifications contextuellement correctes. Le changement de flux de travail est radical :

# Old workflow: CMS
1. Open browser → log into CMS dashboard
2. Navigate to content → find the right page
3. Edit in WYSIWYG editor → fight with formatting
4. Preview → looks different from production
5. Hit publish → pray the cache invalidates

# New workflow: AI
1. Tell AI: "Change the pricing on the landing page to $29/month"
2. AI edits the file, you review the diff
3. Push to git → deploy

Ce n'est pas hypothétique. Ce blog tourne sur SolidStart avec du contenu stocké dans des fichiers TypeScript. Chaque article — y compris celui-ci — a été créé en disant à l'IA quoi écrire, en vérifiant le résultat et en poussant vers git. Pas de tableau de bord CMS. Pas de base de données. Pas de couche API entre le contenu et le code.

Exemples concrets de ce site

Ce site supporte 10 langues, possède un blog, génère des images OG dynamiquement et produit des flux RSS et des sitemaps. Voici à quoi ressemble la couche de contenu — du TypeScript pur :

// This blog post you're reading right now is a TypeScript file.
// No database. No API. No CMS dashboard.
// Just a typed object that AI can read and edit directly.

export const myPost: BlogPost = {
  slug: "ai-killed-cms",
  date: "2026-04-17",
  translations: {
    en: {
      title: "Why I stopped using a CMS",
      description: "AI understands my codebase better than any CMS UI.",
      content: makeContent(proseEn),
    },
    uk: { /* ... */ },
    de: { /* ... */ },
    // 10 languages — AI translates them all
  },
};

Ce que je fais avec l'IA et qui aurait traditionnellement nécessité un CMS :

• Ajouter un nouvel article : "Écris un nouvel article sur X, suis la même structure que les posts existants" — l'IA crée le fichier, ajoute les traductions, l'enregistre dans l'index
• Mettre à jour le texte de la landing : "Change le titre du hero en Y" — l'IA trouve le bon fichier et le met à jour
• Traduire du contenu : "Ajoute la traduction allemande pour la page de tarifs" — l'IA lit la version anglaise et produit une traduction culturellement adaptée, pas du mot-à-mot
• Corriger une coquille : "Il y a une faute sur la page about, 'recieve' devrait être 'receive'" — fait en 3 secondes, commité dans git avec un message explicite

Ce que le CMS résolvait vraiment — et comment l'IA le remplace

Soyons honnêtes sur ce que le CMS apportait et comment chaque fonctionnalité se transpose dans le flux de travail IA :

L'insight clé : git est déjà un meilleur système de contrôle de version que tout ce qu'un CMS a jamais construit. Et le langage naturel est une meilleure interface que n'importe quel éditeur WYSIWYG — parce qu'il porte l'intention, pas seulement le formatage.

Le changement de paradigme : le code est la couche de contenu

Nous assistons à une inversion. Pendant deux décennies, la tendance était de séparer le contenu du code — placer le contenu dans une base de données, l'exposer via une API, le rendre côté frontend. Cela avait du sens quand le code était difficile à modifier et que le contenu devait être accessible aux non-développeurs.

L'IA n'a pas rendu le CMS obsolète en devenant un meilleur CMS. Elle l'a rendu obsolète en rendant le code aussi accessible qu'un tableau de bord.

La progression de la gestion de contenu web suit une trajectoire claire :

1. Années 2000 : CMS monolithiques (WordPress, Drupal) — contenu et présentation couplés dans un seul système
2. Années 2010 : CMS headless (Contentful, Strapi) — contenu séparé via API, rendu par des frameworks frontend
3. Années 2020 : Générateurs de sites statiques + Markdown (Hugo, Astro) — contenu sous forme de fichiers, compilé au déploiement
4. 2025+ : Code-as-content + IA — le contenu vit dans du code typé, l'IA est l'interface d'édition

Quand vous avez encore besoin d'un CMS

Ce n'est pas un discours "le CMS est mort". Le CMS résout de vrais problèmes à grande échelle. Vous en avez encore besoin quand :

• Grandes équipes éditoriales : Plus de 10 éditeurs de contenu qui ont besoin d'accès basé sur les rôles, de workflows d'approbation et d'édition simultanée. Les conflits de merge dans git ne sont pas le problème d'un éditeur de contenu.
• Contenu à haute fréquence : Les sites d'actualités qui publient plus de 50 articles par jour ont besoin de pipelines éditoriaux optimisés, pas de commits git.
• Relations de contenu complexes : Les catalogues e-commerce avec des milliers de SKUs, des variantes de produits et des prix dynamiques nécessitent des bases de données structurées.
• Conformité réglementaire : Les secteurs exigeant des pistes d'audit, des chaînes d'approbation de contenu et des processus de révision légalement obligatoires nécessitent des systèmes spécialisés.

La frontière est claire : si vos modifications de contenu nécessitent une coordination entre plusieurs parties prenantes non techniques à haute fréquence, un CMS mérite sa complexité. Si vous êtes un développeur solo, une petite équipe, ou si vous gérez un site qui change chaque semaine plutôt que chaque heure — IA + code est plus simple, plus rapide, moins cher et plus fiable.

L'avenir : l'IA comme interface universelle

La tendance dépasse le cadre du CMS. Chaque couche d'abstraction qui existait parce que "le système sous-jacent est trop complexe pour une interaction directe" est comprimée par l'IA. Tableaux de bord d'administration, interfaces de configuration, éditeurs visuels de bases de données — ce sont tous des interfaces qui traduisent l'intention humaine en modifications système. L'IA effectue cette traduction nativement.

Pour les sites web simples, l'avenir est déjà là. Votre contenu est du code. Votre éditeur est l'IA. Votre contrôle de version est git. Votre déploiement est un push. Toute la couche CMS — le tableau de bord, la base de données, l'API, l'hébergement — était du middleware entre votre intention et votre site web. L'IA a supprimé le besoin de ce middleware.

Le meilleur CMS, c'est pas de CMS. Non pas parce que la gestion de contenu n'a pas d'importance — mais parce que l'IA a fait du code lui-même l'interface de gestion de contenu la plus intuitive que nous ayons jamais eue.

Perplexity Desktop prend en charge les connecteurs MCP (Model Context Protocol). En ajoutant le serveur officiel @modelcontextprotocol/server-filesystem pointant vers votre Obsidian vault, vous pouvez demander à Perplexity en langage naturel de lire, créer et modifier des notes — directement depuis le chat. Sans plugins, sans extensions, sans copier-coller.

Le Problème

Perplexity excelle dans la recherche — il parcourt le web, résume les sources et donne des réponses avec citations. Mais quand vous voulez sauvegarder ces trouvailles dans votre Obsidian vault, le workflow se brise : copier le texte, basculer vers Obsidian, trouver la bonne note, coller, formater. À. Chaque. Fois.

Les extensions navigateur comme "Perplexity to Obsidian" aident à l'export, mais elles sont unidirectionnelles — l'IA ne peut pas voir votre vault, ne peut pas lire vos notes existantes et ne peut pas décider où placer les choses en fonction de votre structure de dossiers.

Qu'est-ce que MCP ?

Model Context Protocol (MCP) est un standard ouvert qui permet aux modèles d'IA d'interagir avec des outils et sources de données locaux. Imaginez un port USB pour l'IA — vous branchez un "serveur" (un petit programme) et l'IA acquiert de nouvelles capacités. Dans notre cas, le serveur filesystem donne à Perplexity 14 outils pour travailler avec les fichiers :

Perplexity Desktop (Mac App)
  │
  ├── MCP Connector: "Obsidian Vault"
  │     │
  │     └── @modelcontextprotocol/server-filesystem
  │           │
  │           ├── read_file()      → read any .md file
  │           ├── write_file()     → create or overwrite files
  │           ├── edit_file()      → patch existing files
  │           ├── list_directory() → browse vault structure
  │           ├── search_files()   → find files by pattern
  │           └── ... 14 tools total
  │
  └── Perplexity AI Model
        │
        └── "Save this to my daily note" → calls write_file()

Le point clé : le modèle d'IA n'accède pas directement à vos fichiers. Il appelle des outils fournis par le serveur MCP, qui s'exécute localement sur votre machine. Vos données ne quittent jamais votre ordinateur sauf si vous demandez explicitement à l'IA de faire quelque chose avec.

Prérequis

• Abonnement Perplexity Pro (les connecteurs MCP sont disponibles pour les utilisateurs payants)
• Perplexity Mac App depuis l'App Store (pas la version navigateur)
• Node.js installé sur votre Mac (pour que npx fonctionne)

Configuration étape par étape

L'ensemble de la configuration prend environ 2 minutes :

La Commande

La commande à coller dans le champ Command :

npx -y @modelcontextprotocol/server-filesystem "/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault"

Remplacez le chemin par l'emplacement réel de votre Obsidian vault. Si votre vault est synchronisé via iCloud, le chemin sera sous ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/. Gardez les guillemets — le chemin contient probablement des espaces.

Comment l'utiliser

Une fois que le connecteur affiche Running avec 14 outils disponibles, allez dans n'importe quel chat Perplexity et commencez à parler à votre vault :

> Show me the structure of my Obsidian vault
> Add a new reflection to daily notes/2026-04-12.md: "Started using MCP today"
> Find all notes that mention "meditation"
> Create a new note in concepts/ about quantum computing
> List all files in my ideas/ folder

L'IA comprend la structure de votre vault, respecte vos conventions de formatage et peut travailler avec le contenu existant. Vous pouvez lui demander de rechercher un sujet sur le web et de sauvegarder le résumé directement dans une note spécifique.

Pourquoi MCP surpasse les autres approches

Avant MCP, il y avait des moyens limités de connecter Perplexity et Obsidian :

Limitations actuelles

• Mac uniquement — les connecteurs MCP de Perplexity ne fonctionnent actuellement que sur la version Mac App Store
• Pas d'intégration API Obsidian — le serveur filesystem travaille avec les fichiers bruts, pas via l'API d'Obsidian. Cela signifie qu'il ne déclenchera pas les plugins Obsidian (Linter, Templater) lors de la création de fichiers
• Approbation requise — les opérations sensibles sur les fichiers peuvent nécessiter votre confirmation dans l'app Perplexity — c'est une fonctionnalité de sécurité, pas un bug

Conclusions

Cette configuration transforme Perplexity d'un outil de recherche en un outil de recherche-et-capture :

1. Recherchez sur le web et sauvegardez dans Obsidian en une seule conversation
2. L'IA voit la structure de votre vault et s'adapte à votre système d'organisation
3. Zéro basculement entre apps — tout se passe dans le chat Perplexity

Sources

• Model Context Protocol — official MCP specification
• MCP Filesystem Server — the server used in this setup
• Perplexity Help Center — Local and Remote MCPs for Perplexity
• Perplexity Blog — Everything is Computer

Un script bash de 6 lignes qui exécute Claude Code CLI en mode headless chaque matin à 9h00. Il recherche des actualités sur 11 sujets configurables, filtre le bruit et écrit un digest markdown formaté directement dans un Obsidian vault synchronisé via iCloud. Zéro dépendance. ~100 lignes de configuration au total.

Le Problème

En tant que développeur, rester à jour sur plusieurs technologies est un impôt quotidien. Les flux RSS sont bruyants, Twitter est chronophage, les newsletters arrivent quand on est en plein flow. J'avais besoin de quelque chose qui fasse la recherche pour moi.

La solution typique est de construire un pipeline de scraping : un planificateur, un crawler, un pipeline NLP, une base de données, un service de notification. C'est des semaines de travail. Je voulais quelque chose faisable en un après-midi.

Architecture

Le système entier fait 4 fichiers et zéro dépendance :

macOS launchd (9:00 AM daily)
  │
  └── digest.sh
        │
        └── claude -p "$(cat prompt.md)" --max-turns 20 --allowedTools Read,WebSearch,WebFetch,Write
              │
              ├── Reads topics.yaml (11 configurable topics)
              ├── WebSearch → finds news for each topic (last 24-48h)
              ├── WebFetch → reads full articles
              ├── Filters noise: old tutorials, promos, AI spam
              └── Write → saves digest to Obsidian Vault
                    │
                    └── ~/Obsidian Vault/digests/2026-04-12.md
                          │
                          └── iCloud sync → available on all devices

Le Code (en entier)

Le projet est intentionnellement minimal.

Point d'entrée : digest.sh

L'application entière est un script bash de 6 lignes :

#!/bin/bash
DIGEST_DIR="$HOME/Developer/news-digest"

claude -p "$(cat "$DIGEST_DIR/prompt.md")" \
  --max-turns 20 \
  --allowedTools Read,WebSearch,WebFetch,Write

Les flags clés : -p lance Claude en mode headless, --max-turns 20 donne assez de tours à l'agent, --allowedTools restreint l'agent à la lecture, recherche et écriture.

Le Cerveau : prompt.md

C'est ici que vit l'intelligence. Le prompt transforme Claude en agent de recherche d'actualités :

# News Digest Agent

You are a news research agent. Your job is to find today's most important
and interesting news for a senior frontend developer.

## Instructions

1. Read the topics file at ~/Developer/news-digest/topics.yaml
2. For EACH topic, search the web for news from the last 24-48 hours
3. Filter: only include genuinely new and noteworthy items
4. Write the digest as a markdown file to Obsidian Vault digests/YYYY-MM-DD.md
5. IMPORTANT: Use the Write tool to save the file. Do NOT output to stdout.

## Rules

- Language: Ukrainian for summaries, English for titles and technical terms
- If there's no real news for a topic — SKIP IT ENTIRELY
- Prioritize: releases > breaking changes > security > new patterns > discussions
- Max 5 items per topic, sorted by importance
- Include direct links to sources
- Skip promotional content, generic tutorials, and AI-generated spam

Configuration : topics.yaml

Les sujets sont entièrement configurables — ajoutez-en un nouveau et il sera dans le digest de demain :

topics:
  - name: better-auth
    context: "auth library for TypeScript. New releases, breaking changes"

  - name: Next.js
    context: "GitHub issues, releases, App Router, Turbopack, performance"

  - name: SolidJS
    context: "SolidStart, releases, ecosystem, comparison with React"

  - name: Tailwind CSS
    context: "v4 updates, new utilities, plugins"

  - name: Claude AI
    context: "Anthropic announcements, Claude Code, new models, MCP, API"

  - name: GPT AI
    context: "OpenAI announcements, new models, ChatGPT features"

  - name: React
    context: "React 19+, Server Components, new patterns, ecosystem"

  - name: Apple
    context: "Hardware, software, WWDC, developer tools, Apple Intelligence"

  - name: Notable People
    context: >
      Latest tweets from: Elon Musk, Dario Amodei, Sam Altman,
      Jensen Huang, Andrej Karpathy, Simon Willison, Swyx...

  - name: AI Global
    context: "Major AI news, new models, regulations, open-source AI"

Planification avec launchd

Sur macOS, launchd est le moyen natif de planifier des tâches récurrentes :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.news-digest</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/you/Developer/news-digest/digest.sh</string>
    </array>

    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>

    <key>StandardOutPath</key>
    <string>/Users/you/Developer/news-digest/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/Developer/news-digest/logs/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
        <key>HOME</key>
        <string>/Users/you</string>
    </dict>
</dict>
</plist>

Installation : launchctl load ~/Library/LaunchAgents/com.news-digest.plist. Le script s'exécute tous les jours à 9h00.

À quoi ressemble le résultat

Chaque matin, un nouveau fichier markdown apparaît dans le vault Obsidian :

---
date: 2026-04-12
---

# News Digest — 2026-04-12

## Next.js

### Next.js 16.1 Released with Improved Turbopack Caching
Нова версія Next.js 16.1 включає покращене кешування для Turbopack,
що зменшує час холодного старту на ~40%.
[Посилання](https://nextjs.org/blog/next-16-1)

### Critical Memory Leak Fix in App Router
Виправлено витік пам'яті в App Router при частому перемиканні
між динамічними маршрутами.
[GitHub Issue](https://github.com/vercel/next.js/issues/...)

## Claude AI

### Claude Code 1.5 — MCP Server Auto-Discovery
Anthropic випустив оновлення Claude Code з автоматичним
виявленням MCP серверів у проєкті.
[Блог](https://www.anthropic.com/news/...)

En chiffres

Décisions clés de conception

• Claude Code CLI plutôt qu'API — pas besoin de gérer des clés API, clients HTTP ou parsing de réponses
• Obsidian plutôt qu'email — les digests sont recherchables, liables et permanents
• launchd plutôt que cron — planificateur natif macOS avec gestion propre des exécutions manquées
• YAML pour les sujets — un nouveau sujet est un changement de 2 lignes
• Ignorer les sujets vides — pas d'actualités = pas de section

Construire le vôtre

Opérationnel en 10 minutes :

1. Installer Claude Code CLI et s'authentifier
2. Cloner le repo : git clone https://github.com/oleksiimazurenko/news-digest
3. Éditer topics.yaml et prompt.md
4. Éditer le plist et launchctl load
5. Attendre 9h00 — ou tester manuellement avec bash digest.sh

Conclusions

Le plus intéressant dans ce projet est ce qui n'y est pas. Pas de base de données, pas de serveur API, pas de Docker, pas de npm, pas de Python, pas de parser HTML, pas de pipeline NLP.

Voilà à quoi ressemble la construction avec des agents AI : vous définissez le quoi et le où, l'agent gère le comment. Temps total : environ 2 heures.

Sources

• news-digest on GitHub — full source code
• Claude Code Documentation — headless mode and CLI flags
• Apple Developer — creating launchd jobs
• Obsidian — markdown knowledge base

next-themes insère une balise <script> dans un React Client Component pour éviter le flash de thème (FOUC). React 19 émet désormais un avertissement — impossible à supprimer. La bibliothèque n'a pas été mise à jour depuis mars 2025. La solution : remplacer next-themes par un store Zustand + useServerInsertedHTML pour injecter le script hors de l'arbre React. Zéro dépendance ajoutée. Zéro FOUC. Zéro avertissement.

Le Problème

Si vous utilisez next-themes avec Next.js 15+ et React 19, vous obtenez cette erreur dans la console à chaque chargement de page :

Encountered a script tag while rendering React component.
Scripts inside React components are never executed when rendering on the client.
Consider using template tag instead.

src/providers/theme-provider.tsx (7:10) @ ThemeProvider

Ce n'est pas une incohérence d'hydratation. React 19 avertit explicitement que les balises <script> rendues par des composants React côté client ne s'exécuteront jamais. Le script fonctionne pendant le SSR (il est dans le HTML), mais React le signale comme incorrect.

Pourquoi Ça Se Produit

next-themes doit définir la bonne classe de thème sur <html> avant l'hydratation de React — sinon il y a un flash du mauvais thème. Pour cela, il injecte un <script> inline via React.createElement :

// next-themes renders a <script> inside a Client Component
return React.createElement(Provider, { value },
  React.createElement("script", {
    suppressHydrationWarning: true,
    dangerouslySetInnerHTML: { __html: `(...theme init code...)` }
  }),
  children
)

React 19 a changé son comportement : les balises script dans les composants sont désormais explicitement signalées. Avant React 19, c'était ignoré silencieusement. La prop suppressHydrationWarning sur le script n'aide pas — elle supprime les avertissements d'hydratation, pas l'avertissement "script dans un composant".

Ce Que Nous Avons Essayé (Et Pourquoi Ça N'a Pas Marché)

Nous avons systématiquement essayé chaque approche avant de trouver la solution :

La Solution : Zustand + useServerInsertedHTML

L'insight clé : useServerInsertedHTML est un hook Next.js qui injecte du HTML dans le flux SSR en dehors de l'arbre de composants React. Le script se retrouve dans le HTML mais React ne le "voit" jamais lors du rendu côté client — donc pas d'avertissement. Combiné avec un store Zustand pour l'état réactif du thème, on obtient un remplacement complet sans dépendances.

Comment Ça Fonctionne

SSR (server):
  useServerInsertedHTML → injects <script> into HTML stream
  ↓
  Browser receives HTML with theme script already in it
  ↓
  Script runs BEFORE React hydrates → correct class on <html>
  ↓
  No flash. No mismatch. No warning.

Client (after hydration):
  useEffect → _init() → Zustand store syncs with localStorage
  ↓
  useTheme() → reactive theme state for components

Étape 1 : Store Zustand

Le store gère l'état du thème, applique les classes au DOM, détecte le thème système et synchronise entre les onglets. La méthode _init() renvoie une fonction de nettoyage pour useEffect :

import { create } from "zustand";

const STORAGE_KEY = "theme";
const MEDIA_QUERY = "(prefers-color-scheme: dark)";

function getSystemTheme(): "light" | "dark" {
  return window.matchMedia(MEDIA_QUERY).matches ? "dark" : "light";
}

function applyTheme(resolved: string, disableTransition: boolean) {
  const d = document.documentElement;

  if (disableTransition) {
    const style = document.createElement("style");
    style.appendChild(
      document.createTextNode(
        "*,*::before,*::after{transition:none!important}"
      )
    );
    document.head.appendChild(style);
    window.getComputedStyle(document.body);
    setTimeout(() => document.head.removeChild(style), 1);
  }

  d.classList.remove("light", "dark");
  d.classList.add(resolved);
  d.style.colorScheme = resolved;
}

interface ThemeState {
  theme: string;
  systemTheme: "light" | "dark";
  resolvedTheme: string;
  setTheme: (theme: string) => void;
  _init: (disableTransition: boolean) => () => void;
}

export const useThemeStore = create<ThemeState>((set, get) => ({
  theme: "system",
  systemTheme: "light",
  resolvedTheme: "light",

  setTheme: (newTheme) => {
    const { systemTheme, disableTransitionOnChange } = get();
    const resolved = newTheme === "system" ? systemTheme : newTheme;
    localStorage.setItem(STORAGE_KEY, newTheme);
    applyTheme(resolved, disableTransitionOnChange);
    set({ theme: newTheme, resolvedTheme: resolved });
  },

  _init: (disableTransition) => {
    const stored = localStorage.getItem(STORAGE_KEY) || "system";
    const system = getSystemTheme();
    const resolved = stored === "system" ? system : stored;

    set({ theme: stored, systemTheme: system, resolvedTheme: resolved });
    applyTheme(resolved, disableTransition);

    // System theme changes
    const mq = window.matchMedia(MEDIA_QUERY);
    const onChange = (e: MediaQueryListEvent) => {
      const newSystem = e.matches ? "dark" : "light";
      const { theme } = get();
      set({ systemTheme: newSystem,
            resolvedTheme: theme === "system" ? newSystem : theme });
      if (theme === "system") applyTheme(newSystem, disableTransition);
    };
    mq.addEventListener("change", onChange);

    // Cross-tab sync
    const onStorage = (e: StorageEvent) => {
      if (e.key !== STORAGE_KEY || !e.newValue) return;
      const system = getSystemTheme();
      const resolved = e.newValue === "system" ? system : e.newValue;
      set({ theme: e.newValue, resolvedTheme: resolved });
      applyTheme(resolved, disableTransition);
    };
    window.addEventListener("storage", onStorage);

    return () => {
      mq.removeEventListener("change", onChange);
      window.removeEventListener("storage", onStorage);
    };
  },
}));

export function useTheme() {
  return useThemeStore((s) => ({
    theme: s.theme,
    setTheme: s.setTheme,
    resolvedTheme: s.resolvedTheme,
    systemTheme: s.systemTheme,
  }));
}

Étape 2 : ThemeProvider

Le provider fait deux choses : injecte le script anti-FOUC via useServerInsertedHTML, et initialise le store Zustand au montage :

"use client"

import { useEffect } from "react"
import { useServerInsertedHTML } from "next/navigation"
import { useThemeStore } from "@/store/use-theme-store"

const THEME_INIT_SCRIPT = `(function(){
  try {
    var t = localStorage.getItem("theme") || "system";
    var r = t;
    if (t === "system") {
      r = window.matchMedia("(prefers-color-scheme: dark)").matches
        ? "dark" : "light";
    }
    document.documentElement.classList.remove("light", "dark");
    document.documentElement.classList.add(r);
    document.documentElement.style.colorScheme = r;
  } catch(e) {}
})()`

export function ThemeProvider({
  children,
  disableTransitionOnChange = false,
}) {
  // Injects script into SSR HTML outside the React tree
  // — prevents FOUC without triggering React 19 warning
  useServerInsertedHTML(() => (
    <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
  ))

  useEffect(() => {
    return useThemeStore.getState()._init(disableTransitionOnChange)
  }, [disableTransitionOnChange])

  return <>{children}</>
}

Étape 3 : Layout

import { ThemeProvider } from "@/providers/theme-provider"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider disableTransitionOnChange>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Étape 4 : Utilisation

import { useTheme } from "@/store/use-theme-store"

export function ThemeSwitch() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(
      theme === "dark" ? "light" : "dark"
    )}>
      {theme === "dark" ? "☀️" : "🌙"}
    </button>
  );
}

Migration depuis next-themes

L'API est intentionnellement identique. La migration se résume à un seul changement d'import par fichier :

- import { useTheme } from "next-themes"
+ import { useTheme } from "@/store/use-theme-store"

  // API is identical — no other changes needed
  const { theme, setTheme, resolvedTheme, systemTheme } = useTheme()

Comparaison

Pourquoi Pas Les Autres Alternatives ?

@wrksz/themes

Un remplacement direct qui utilise aussi useServerInsertedHTML. Ça fonctionne, mais c'est une dépendance de plus maintenue par un seul développeur. Si next-themes nous a appris quelque chose — les dépendances finissent par être abandonnées. Avec ~100 lignes de code, vous possédez entièrement la solution.

next-themes@1.0.0-beta.0

Existe sur npm, mais sans date de sortie, sans changelog et sans indication claire que l'avertissement React 19 est corrigé. Miser du code de production sur une bêta indéfinie n'est pas un risque qui en vaut la peine.

CSS uniquement (prefers-color-scheme)

Fonctionne pour la détection du thème système, mais ne peut pas gérer la persistance des préférences utilisateur (localStorage), le changement manuel de thème ni l'option "system". JavaScript est nécessaire pour cela.

Conclusions

1. next-themes est effectivement abandonné — dernière version mars 2025, avertissement React 19 non corrigé
2. useServerInsertedHTML est la bonne primitive Next.js pour injecter des scripts sans avertissements React
3. Zustand fournit un état de thème réactif avec moins de code qu'un provider Context
4. La solution complète fait ~100 lignes, zéro nouvelle dépendance, et vous en êtes propriétaire

Sources

• shadcn/ui #10104 — Dark mode guide should address React 19 script warning
• next-themes #296 — React 19 support request (open since 2024)
• React #34008 — Script tags not executing in components (by design)
• @wrksz/themes — Drop-in replacement using useServerInsertedHTML
• Next.js Docs — useServerInsertedHTML API

Notre application (Promova) utilise Next.js 16 avec un Landing Builder — un système piloté par CMS qui assemble des pages marketing à partir de ~90 composants de section différents (heroes, FAQs, tarifs, avis, etc.). L'architecture utilise un sectionRegistry.tsx qui mappe les noms de section aux appels next/dynamic() :

// sectionRegistry.tsx — imports all 90 sections
export const sectionRegistry = {
  HeroSection: dynamic(() => import('./HeroSection/HeroSection')),
  FAQSection: dynamic(() => import('./FAQSection/FAQSection')),
  ReviewsSection: dynamic(() => import('./ReviewsSection/ReviewsSection')),
  // ... 87 more
}

Une seule landing page ne rend que 5-8 sections. Mais Lighthouse affichait :

Eliminate render-blocking resources
  94 CSS resources (~330 KB)
  Potential savings: 5,440 ms

Pourquoi ? Turbopack voit les 90 chemins import() comme atteignables et génère <link rel="stylesheet"> pour chaque module SCSS. Même les sections qui ne sont jamais rendues obtiennent leur CSS injecté dans <head>. C'est un comportement confirmé et attendu du Next.js App Router. Aucun correctif n'est prévu.

Tout ce que j'ai essayé (et pourquoi ça a échoué)

J'ai passé des jours à parcourir chaque approche que j'ai pu trouver. Voici la liste complète :

Le piège inlineCss

Next.js a un flag experimental.inlineCss qui remplace tous les <link rel="stylesheet"> par des balises <style> inline. Ça semble parfait, non ?

Le problème : c'est tout ou rien. On ne peut pas l'activer par route. Si vous avez des pages SSR (force-dynamic), chaque requête reconstruit tout le CSS inline. Nous avons essayé — notre CMS headless n'a pas supporté la charge.

La découverte : Turbopack Import Attributes

En fouillant les notes de version Next.js 16.2, j'ai trouvé une fonctionnalité peu documentée : Turbopack Import Attributes. Elle permet de remplacer le pipeline du bundler pour un import spécifique avec la syntaxe TC39 with {} :

import { cssText, styles } from './hero.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}

Cela dit à Turbopack : "Ne traite pas cet import comme une feuille de style. Passe-le par mon loader personnalisé et traite la sortie comme du JavaScript."

C'est l'insight clé. Au lieu que Turbopack génère un <link rel="stylesheet"> bloquant le rendu, notre loader compile le SCSS et l'exporte comme string JS. Résultat : seul le CSS des sections qui sont réellement rendues arrive dans le HTML de la page.

La solution

1. Loader Turbopack personnalisé

Un script Node.js d'environ 70 lignes comme package yarn workspace (@promova/scss-to-inline-loader) :

const { createHash } = require('node:crypto')
const sass = require('sass')
const postcss = require('postcss')
const postcssModules = require('postcss-modules')
const path = require('path')

const SHARED_STYLES = path.resolve(__dirname, '../shared/styles')

// Same prependData as sassOptions.prependData in next.config.ts
const PREPEND_DATA = `
@use "sass:math" as math;
@use "sass:list" as list;
@use "${SHARED_STYLES}/_variables.scss" as *;
@use "${SHARED_STYLES}/_breakpoints.scss" as *;
@use "${SHARED_STYLES}/_mixins.scss" as *;
`

module.exports = function scssToInlineLoader(source) {
  const callback = this.async()
  processScss(source, this.resourcePath)
    .then((js) => callback(null, js))
    .catch((err) => callback(err))
}

async function processScss(source, resourcePath) {
  // 1. Compile SCSS → CSS (with global variables, mixins, breakpoints)
  const sassResult = sass.compileString(PREPEND_DATA + '\n' + source, {
    loadPaths: [path.dirname(resourcePath), SHARED_STYLES],
    style: 'compressed',
    sourceMap: false,
    url: new URL('file://' + resourcePath),
  })

  // 2. Scope class names with postcss-modules (CSS Modules compatible)
  let classNames = {}
  const result = await postcss([
    postcssModules({
      generateScopedName(name, filename) {
        const file = path.basename(filename, path.extname(filename))
          .replace('.module', '')
        const hash = createHash('md5')
          .update(filename + name)
          .digest('base64url')
          .slice(0, 6)
        return `${file}__${name}__${hash}`
      },
      getJSON(_, json) { classNames = json },
    }),
  ]).process(sassResult.css, { from: resourcePath })

  // 3. Export as JS module — same interface as CSS Modules
  return [
    `export const cssText = ${JSON.stringify(result.css)};`,
    `export const styles = ${JSON.stringify(classNames)};`,
    `export default styles;`,
  ].join('\n')
}

Ce qu'il fait : styles — la même carte de noms de classes scopés que les CSS Modules standard. cssText — le CSS compilé comme string.

2. Composant InlineStyle

Utilise l'API intégrée de React 19 <style href precedence> pour la déduplication automatique :

export function InlineStyle({ css, id }: { css: string; id: string }) {
  return (
    <style href={id} precedence="default">
      {css}
    </style>
  )
}

React 19 garantit : même href → un seul <style> dans le DOM.

3. Migration par composant (~6 lignes par section)

// BEFORE: Turbopack → <link rel="stylesheet"> (render-blocking)
import styles from './hero_section.module.scss'

// AFTER: Custom loader → JS module → inline <style> (non-blocking)
import { cssText, styles } from './hero_section.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}
import { InlineStyle } from '@promova/scss-to-inline-loader/InlineStyle'

export function HeroSection() {
  return (
    <section className={styles.hero}>
      <InlineStyle css={cssText} id="hero-section" />
      {/* ... component JSX, className usage is identical */}
    </section>
  )
}

Les fichiers .module.scss restent exactement les mêmes. Aucune réécriture CSS.

Pourquoi c'est mieux que inlineCss: true

Voici la différence critique :

Avec inlineCss: true, une page obtient toujours les 94 feuilles de style inline. Avec notre approche, seul le CSS réellement rendu arrive dans le HTML.

Le piège Turbopack : pas de règles globales pour .module.scss

Un piège dans lequel je suis tombé : on pourrait penser qu'on peut ajouter une règle Turbopack dans next.config.ts pour appliquer le loader globalement :

// ❌ THIS CAUSES A FATAL PANIC
turbopack: {
  rules: {
    '**/components/**/*.module.scss': {
      loaders: ['@promova/scss-to-inline-loader'],
      as: '*.js'
    }
  }
}

Ne faites pas ça. Le pipeline intégré de modules CSS de Turbopack intercepte les fichiers .module.scss avant l'application des règles personnalisées, causant :

FATAL PANIC: inner asset should be CSS processable

Les attributs with {} fonctionnent car ils instruisent Turbopack au site d'import de contourner complètement le pipeline de modules CSS.

Résultats

127 composants de section migrés dans le Landing Builder. Build de production vérifié.

Limitations

• with {} par import est verbeux — chaque import nécessite 3 lignes supplémentaires.
• Turbopack uniquement — les attributs with {} ne sont pas supportés par Webpack.
• Hachage des noms de classe — notre loader utilise un algorithme de hachage différent de celui de Turbopack.
• La taille du HTML augmente — CSS inline dans le HTML au lieu de fichiers cachés séparés.

Quand l'utiliser

Cette technique est plus efficace quand :

1. Vous avez un pattern registry/barrel — un fichier importe beaucoup de composants, mais seuls quelques-uns sont rendus par page
2. Vous êtes sur Turbopack — les Import Attributes sont spécifiques à Turbopack
3. Vous voulez un contrôle par composant — pas un flag tout ou rien
4. Votre SCSS est complexe — variables, mixins, breakpoints, imbrication — tout supporté
5. Vous ne pouvez pas utiliser experimental.inlineCss — parce que vous avez des pages SSR ou voulez un contrôle granulaire

Issues GitHub liées

Si vous êtes affecté par le CSS bloquant le rendu dans Next.js App Router — vous n'êtes pas seul :

Le problème central

• #62485 — Render blocking CSS (maintainers: "expected behavior")
• #61066 — Dynamic imports from Server Components are not code-split
• #54935 — Server-side dynamic imports don't split client modules
• #61574 — JS/CSS code splitting doesn't work as documented
• #57634 — Add support for critical CSS inlining with App Router
• #50300 — next/dynamic on server component does not build CSS modules

Feature inlineCss et problèmes

• PR #72195 — experimental: css inlining (the implementation)
• PR #73182 — Don't inline CSS in RSC payload for client navigation
• #75648 — WhatsApp preview broken with inlineCss + Tailwind
• #83612 — Turbopack wrong font URL with inline CSS

La communauté cherche des solutions

• Discussion #82894 — How to prevent render-blocking with CSS Modules? (2025)
• Discussion #70526 — Ideas for reducing render-blocking CSS
• Discussion #59814 — Render blocking styles with Tailwind
• Discussion #49691 — How to deal with render-blocking modular CSS
• Discussion #59989 — Critical CSS inlining with App Router
• Discussion #80486 — Is optimizeCss still in use?
• Discussion #85465 — Turbopack plugin API (doesn't exist)

Bugs CSS de Turbopack

• #68412 — Incorrect CSS modules load order with external components
• #76464 — Turbopack sometimes strips SCSS imports
• #82497 — SCSS module not loading when not-found.tsx is present
• #88544 — Exporting Sass variables from CSS modules doesn't work with Turbopack

Construit chez Promova — une plateforme d'apprentissage des langues au service de millions d'utilisateurs.

Next.js patche le fetch global et ajoute une couche de cache qui maintient des références sur les données de réponse après qu'elles auraient dû être libérées. Chaque appel fetch ajoute de la mémoire qui n'est jamais rendue au GC. Sous Docker/Kubernetes, cela provoque des crashes OOM toutes les quelques heures. Le bug existe depuis Next.js 14 (avril 2024) et n'est toujours pas résolu dans 16.2.x (mars 2026). Sur Vercel, le problème ne se manifeste pas grâce aux fonctions serverless éphémères.

Comment fonctionne un fetch normal

Request → fetch → got data → response to user → GC cleans up → memory free

Comment fonctionne fetch dans Next.js

Next.js intercepte le fetch global et l'enveloppe avec sa propre couche de cache/tracking :

Request → Next.js fetch wrapper → creates:
  - Performance entry (speed tracking)    ← not cleaned
  - Request metadata object               ← not cleaned
  - Internal promise wrapper              ← not cleaned
  - Cache lookup entry                    ← not cleaned
  - Response body (for unique URL)        ← not cleaned
→ Response to user
→ GC sees objects are still referenced → doesn't touch them
→ Memory grows indefinitely

Ce qui se passe en production

Self-hosted (Docker/K8s):
  Request 1:      fetch → +100KB → RAM: 100KB
  Request 2:      fetch → +100KB → RAM: 200KB
  Request 1000:   fetch → +100KB → RAM: 100MB
  Request 50,000: fetch → +100KB → RAM: 5GB → OOM Kill 💀
  → Kubernetes restarts the pod → cycle repeats

Vercel (Serverless):
  Request 1: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  Request 2: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  → Memory never accumulates

Versions affectées

Next.js — Toutes les versions avec App Router

Node.js

Testé sur Node.js 20, 22, 24, 25 — fuite sur tous.

Ce qui ne fonctionne pas

Ce qui fonctionne (contournements)

Limitation du contournement axios

Vos propres appels API peuvent être remplacés par axios. Mais Next.js utilise en interne le fetch patché pour :

• ISR (Incremental Static Regeneration)
• revalidatePath / revalidateTag
• Data fetching des Server Components avec déduplication
• use cache (Next.js 16)

Même sans un seul fetch dans votre code — Next.js l'utilise toujours en interne.

Pourquoi Vercel ne corrige pas

Logique business

Vercel est une entreprise qui gagne de l'argent en hébergeant Next.js. Sur leur plateforme, le problème ne se manifeste pas (serverless = éphémère). Le bug n'affecte que le self-hosted (Docker, K8s, VPS) — ceux qui ne paient pas Vercel.

Position officielle

Tim Neutkens (mainteneur Vercel) a analysé le problème et déclaré que c'est un problème d'undici (bibliothèque fetch de Node.js), pas de Next.js. L'issue #90433 a été fermée. Malgré le fait que :

• axios et node-fetch sur le même Node.js fonctionnent sans fuites
• La fuite n'apparaît que quand fetch passe par le wrapper Next.js
• Le bug est ouvert depuis 2 ans sans correction

Priorités

En 2 ans, l'équipe Next.js a livré :

• Turbopack (builds 2-5x plus rapides) — avantage marketing
• Cache Components / use cache — réduit la charge sur les serveurs Vercel
• proxy.ts au lieu du middleware — simplifie le déploiement edge sur Vercel
• DevTools MCP — hype IA

Memory leak en self-hosted ? Pas une priorité.

Solution : AWS Lambda (SST + OpenNext)

Qu'est-ce que c'est

OpenNext est un adaptateur open-source qui convertit un build Next.js en format pour AWS Lambda. SST est un framework qui automatise l'infrastructure.

Architecture

Next.js build
  → OpenNext
    → AWS Lambda (SSR, API routes)
    → S3 (static, assets)
    → CloudFront (CDN)
    → SQS + DynamoDB (ISR revalidation)

Pourquoi cela résout le memory leak

Les fonctions Lambda traitent les requêtes et sont recyclées après 5-15 minutes d'inactivité. La mémoire n'a pas le temps de s'accumuler.

Déploiement

npx sst@latest init
npx sst deploy --stage production

Comparaison

Nuances Lambda

• Cold starts — la première requête est plus lente (~200-500ms)
• Sécurité — activer OAC (Origin Access Control), sinon l'URL Lambda est publique
• OpenNext — projet communautaire, pas officiel Vercel. Les nouvelles fonctionnalités Next.js peuvent casser
• Attaque au portefeuille — lors d'un DDoS, l'auto-scaling Lambda peut mener à une grosse facture

Pourquoi une vraie correction est irréaliste

1. Problème architectural

La fuite n'est pas un bug accidentel mais la conséquence d'une décision de conception : Next.js intercepte le fetch global et ajoute du cache/tracking par-dessus. Pour corriger, il faudrait repenser la façon dont App Router interagit avec fetch. Cela touche ISR, revalidation, data cache, request deduplication — le cœur du framework.

2. Conflit d'intérêts

Vercel n'est pas motivé à corriger ce qui n'affecte pas sa plateforme. Le self-hosted est en concurrence avec leur business. Plus il y a de problèmes en self-hosted — plus de gens migrent vers Vercel.

3. Rejet de la faute

La position officielle est "c'est undici, pas nous". Tant que cela ne change pas — ils ne travailleront pas sur un correctif.

4. Pas de correctif communautaire

La licence AGPL-3.0 de Next.js autorise les forks, mais la base de code est énorme et étroitement couplée à l'infrastructure Vercel. Un PR communautaire pour corriger le wrapper fetch nécessiterait une compréhension approfondie de l'architecture interne et l'approbation des mainteneurs — qui ont déjà fermé l'issue.

Conclusions

1. Si sur Vercel — pas de problème, rien à faire
2. Si self-hosted et besoin de serverless — SST + OpenNext sur AWS Lambda
3. Si self-hosted Docker — remplacer fetch par axios où possible, surveiller la RAM, configurer le redémarrage automatique des pods
4. Si nouveau projet — envisager SvelteKit ou Nuxt comme alternatives sans ce problème

Sources

• Issue #64212 — Memory Leak with global fetch (April 2024)
• Issue #68578 — Possible memory leak in Fetch API (August 2024)
• Issue #85914 — Memory Leak with fetch + standalone (November 2025)
• Issue #90433 — OOM in 16.0.10 (February 2026)
• Discussion #88603 — OOM in Docker/K8s (January 2026)
• Discussion #88078 — cacheMaxMemorySize behavior
• OpenNext
• SST — Next.js on AWS
• Secret knowledge to self-host Next.js
• Next.js Memory Usage Guide