Stratégies de cache Claude Code pour applications réelles

Le cache n’est pas un bouton magique pour accélérer une application. Dans un vrai produit, les en-têtes HTTP, le CDN, un Service Worker, Redis et la mémoire du processus stockent des données différentes avec des durées différentes. Si vous demandez simplement à Claude Code “ajoute du cache”, l’application peut devenir plus rapide tout en affichant d’anciens prix, un stock périmé ou des données privées à la mauvaise personne.

Ce guide donne une stratégie concrète à transmettre à Claude Code avant qu’il modifie le code. Masa l’a testée sur une petite application Express et un workflow de site de contenu : le gain le plus net venait du fait de décider quelle couche possède quelle donnée avant d’ajouter Redis ou un Service Worker.

flowchart LR
  User[Browser] --> Http[HTTP cache]
  Http --> SW[Service worker Cache API]
  SW --> CDN[CDN or edge cache]
  CDN --> App[Node or app server]
  App --> Redis[Redis or app cache]
  App --> DB[(Database)]

Commencer par les décisions

Avant de laisser Claude Code implémenter, répondez à quatre questions :

1. Quels utilisateurs peuvent voir la même réponse ?
2. Combien de temps la donnée peut-elle être périmée sans dommage ?
3. Quelle key, URL ou étiquette de cache sera supprimée après mise à jour ?
4. Qui lance le rollback ou le purge quand le cache est faux ?

Les images, CSS et bundles JavaScript avec hash peuvent souvent rester en cache longtemps. Les pages de facturation, paramètres de compte et HTML authentifié ne doivent pas aller dans un cache partagé. Le guide MDN HTTP caching explique la différence entre cache privé du navigateur et cache partagé comme un proxy ou un CDN.

Comparaison des couches

Couche	Bon usage	TTL indicatif	Invalidations	Échec fréquent
Cache HTTP navigateur	Images, CSS, JS, API publique courte	1 minute à 1 an	Changement de nom, ETag, Cache-Control	API trop longtemps cachée
CDN ou edge	Listes produit, HTML d’article, images OGP	30 secondes à 1 jour	Purge URL, tag ou déploiement	HTML connecté servi à tous
Service Worker Cache API	Page offline, app shell, JSON stable	Par version	Changer le nom au release	Ancien worker sert de vieux bundles
Redis ou cache applicatif	Agrégats DB, API externes, classements	10 secondes à 1 heure	Conception des keys, événements, TTL	KEYS bloque Redis en production
Mémoire du processus	Configuration, feature flags courts	Secondes à minutes	Redémarrage ou clear explicite	Instances avec valeurs différentes

Mettez ce tableau dans CLAUDE.md pour donner à Claude Code une règle stable quand il ajoute une route. Pour structurer ces règles, lisez aussi CLAUDE.md best practices.

Cas 1 : en-têtes HTTP dans Express

Le premier cache à corriger n’est souvent pas Redis, mais l’en-tête de réponse. Cache-Control indique aux navigateurs et aux CDN combien de temps une réponse peut être stockée. Les directives sont détaillées dans Cache-Control header sur MDN.

Copiez ce fichier en server.js et lancez-le.

npm install express
node server.js

// server.js
const express = require("express");

const app = express();

function cacheControl(req, res, next) {
  const path = req.path;

  if (path.startsWith("/assets/")) {
    res.set("Cache-Control", "public, max-age=31536000, immutable");
    return next();
  }

  if (path.startsWith("/api/private/")) {
    res.set("Cache-Control", "no-store");
    return next();
  }

  if (path.startsWith("/api/public/")) {
    res.set("Cache-Control", "public, max-age=60, s-maxage=300, stale-while-revalidate=600");
    res.set("Vary", "Accept-Encoding");
    return next();
  }

  res.set("Cache-Control", "no-cache");
  next();
}

app.use(cacheControl);
app.use("/assets", express.static("public/assets"));

app.get("/api/public/products", (_req, res) => {
  res.json({ items: ["book", "template", "consultation"], generatedAt: new Date().toISOString() });
});

app.get("/api/private/me", (_req, res) => {
  res.json({ userId: "demo-user", plan: "team" });
});

app.listen(3000, () => {
  console.log("http://localhost:3000");
});

Le choix important est de séparer les routes publiques et privées. /api/private/ reçoit no-store, donc navigateur et CDN ne doivent pas stocker la réponse. Les API publiques ont un TTL court côté navigateur et un TTL un peu plus long côté CDN avec s-maxage.

Dans le prompt Claude Code, écrivez la règle explicitement : les réponses authentifiées doivent utiliser no-store; seules les routes publiques peuvent utiliser s-maxage.

Cas 2 : helper Redis getOrSet

Redis est utile pour réduire les requêtes répétées à la base de données ou aux API externes. Le modèle sûr par défaut est cache-aside : regarder Redis, charger la source en cas de miss, puis stocker avec TTL.

npm install redis

// cache.js
const { createClient } = require("redis");

const redis = createClient({
  url: process.env.REDIS_URL || "redis://localhost:6379",
});

let connecting;

async function client() {
  if (redis.isOpen) return redis;
  if (!connecting) connecting = redis.connect();
  await connecting;
  return redis;
}

async function getOrSet(key, ttlSeconds, loader) {
  const r = await client();
  const cached = await r.get(key);

  if (cached !== null) {
    return JSON.parse(cached);
  }

  const fresh = await loader();
  await r.set(key, JSON.stringify(fresh), { EX: ttlSeconds });
  return fresh;
}

async function invalidate(keys) {
  const r = await client();
  if (keys.length > 0) {
    await r.del(keys);
  }
}

module.exports = { getOrSet, invalidate };

// products.js
const { getOrSet, invalidate } = require("./cache");

async function loadProductsFromDb() {
  return [
    { id: "p1", name: "Prompt Templates", price: 500 },
    { id: "p2", name: "Claude Code Consultation", price: 15000 },
  ];
}

async function getPublicProducts() {
  return getOrSet("products:list:v1", 300, loadProductsFromDb);
}

async function updateProduct(productId, patch) {
  console.log("update db", productId, patch);
  await invalidate(["products:list:v1", `products:item:${productId}:v1`]);
}

module.exports = { getPublicProducts, updateProduct };

Évitez KEYS products:* en production. Quand le nombre de keys augmente, cette commande peut bloquer Redis. Préférez une liste de keys connues, des sets de keys liées ou une commande de maintenance basée sur SCAN.

Cas 3 : versionner Service Worker Cache API

Un Service Worker peut intercepter les requêtes du navigateur. La Cache API sert à conserver une page offline, un app shell et des assets statiques. Le risque est de servir du vieux code : si le nom du cache ne change jamais, un ancien worker peut continuer à livrer un vieux JavaScript après déploiement.

// public/sw.js
const CACHE_VERSION = "claude-code-cache-v2026-06-01";
const STATIC_CACHE = `${CACHE_VERSION}:static`;
const PRECACHE_URLS = ["/", "/offline.html", "/assets/app.css"];

self.addEventListener("install", (event) => {
  event.waitUntil(
    caches
      .open(STATIC_CACHE)
      .then((cache) => cache.addAll(PRECACHE_URLS))
      .then(() => self.skipWaiting())
  );
});

self.addEventListener("activate", (event) => {
  event.waitUntil(
    caches
      .keys()
      .then((names) =>
        Promise.all(
          names
            .filter((name) => !name.startsWith(CACHE_VERSION))
            .map((name) => caches.delete(name))
        )
      )
      .then(() => self.clients.claim())
  );
});

self.addEventListener("fetch", (event) => {
  const request = event.request;
  if (request.method !== "GET") return;

  event.respondWith(
    caches.match(request).then((cached) => {
      if (cached) return cached;

      return fetch(request)
        .then((response) => {
          if (response.ok && new URL(request.url).pathname.startsWith("/assets/")) {
            const copy = response.clone();
            caches.open(STATIC_CACHE).then((cache) => cache.put(request, copy));
          }
          return response;
        })
        .catch(() => caches.match("/offline.html"));
    })
  );
});

Enregistrez-le depuis l’entrée client.

if ("serviceWorker" in navigator) {
  window.addEventListener("load", () => {
    navigator.serviceWorker.register("/sw.js");
  });
}

Demandez à Claude Code d’inclure une date de release ou un build ID dans le nom du cache, et de supprimer les anciens caches dans activate.

Cas 4 : prompt d’audit pour Claude Code

Claude Code est plus utile lorsqu’il audite tout le dépôt au lieu d’ajouter seulement un helper. Les Claude Code common workflows recommandent de petites boucles investigation, édition, vérification ; c’est idéal pour le cache.

Vous êtes responsable de l'audit cache d'une application web.
Inspectez ce dépôt pour trouver les en-têtes HTTP, hypothèses CDN, Service Worker, Redis et caches mémoire de processus.

Retournez :
1. Les données stockées par chaque couche
2. Le TTL et la condition d'invalidation
3. Le risque que des réponses personnelles ou authentifiées atteignent un cache partagé
4. Les écrans concrets où des données périmées peuvent apparaître
5. Le plan minimal de correction et les commandes de vérification

Contraintes :
- Marquer clairement les hypothèses
- Suivre les patterns existants du projet
- Proposer les gros refactors séparément sans les appliquer tout de suite

Ce prompt est un cache de contexte réutilisable. Gardez la checklist dans un template ou CLAUDE.md, puis ajoutez seulement le diff actuel.

Scénarios pratiques

Pour un catalogue produit ou une boutique de templates, les cartes publiques peuvent être gardées brièvement dans le CDN et la liste DB cinq minutes dans Redis. Après modification, supprimez la key de liste et purgez l’URL CDN concernée.

Dans un dashboard admin, revenus, pages vues et conversions peuvent être cachés 30 secondes à 5 minutes. Permissions, notifications personnelles et facturation doivent rester private ou no-store.

Pour docs et blogs, le HTML des articles peut être court en edge, les assets hashés longs, et la coquille offline gérée par Service Worker. C’est adapté aux sites riches en contenu comme ClaudeCodeLab.

Pour les API externes, Redis absorbe les limites de débit pour météo, devises, plans SaaS ou flux de statut. Demandez à Claude Code de vérifier les conditions officielles, car certains fournisseurs limitent le stockage.

Pièges

L’erreur la plus grave est de cacher du HTML authentifié dans un CDN. Si la réponse dépend des cookies, choisissez private ou no-store par défaut. Si vous voulez la vitesse du CDN, séparez la coquille publique des données utilisateur chargées ensuite.

Un Vary manquant crée aussi de mauvaises réponses. Si la langue, la compression, le device ou l’autorisation changent la réponse, séparez l’URL ou envoyez le bon Vary.

Redis peut subir un cache stampede quand une key populaire expire et que beaucoup de requêtes frappent la base en même temps. Ajoutez du jitter au TTL, un lock court ou un fallback de type stale-while-revalidate.

Service Worker peut garder vivants des fichiers supprimés. Versionnez le cache, supprimez les anciens noms dans activate, et prévoyez une procédure d’urgence pour unregister le worker.

Runbook d’invalidation

1. Définir le périmètre : produit, article, utilisateur ou application entière.
2. Terminer l’écriture DB d’abord ; si elle échoue, ne pas supprimer le cache.
3. Supprimer Redis via keys connues, sets liés ou SCAN.
4. Purger le CDN par URL ou tag. Le purge total reste le dernier recours.
5. Monter la version du cache Service Worker et vérifier la disparition des anciens caches.
6. Vérifier avec curl -I, DevTools et les logs de hit rate Redis.
7. En incident, raccourcir les TTL ou passer les routes sensibles en no-store, puis revenir progressivement.

Ajoutez ce runbook à la définition de terminé de Claude Code. Pour la discipline d’équipe, combinez-le avec Claude Code productivity tips.

Formation, templates et consultation

Pour transformer cette stratégie en workflow d’équipe, commencez par la bibliothèque produits et templates ClaudeCodeLab afin d’aligner CLAUDE.md, prompts de review et prompts d’audit. Si la difficulté est de cartographier CDN, Redis, permissions et règles de review sur un vrai dépôt, utilisez la page formation et consultation Claude Code.

Références officielles : MDN sur HTTP caching, la Cache API, Cache-Control, et les Claude Code common workflows.

Après avoir essayé les exemples de cet article, Masa a constaté moins de requêtes répétées sur les assets statiques, des réponses publiques plus prévisibles grâce aux TTL orientés CDN, et des lectures DB inutiles plus visibles avec getOrSet. Le Service Worker a montré la leçon principale : sans suppression versionnée, un vieux CSS peut survivre au déploiement. Le vrai gain n’est pas seulement la vitesse ; c’est d’écrire où chaque valeur a le droit de devenir ancienne.