Module 15 — Maîtriser les coûts, la sécurité et le déploiement en équipe

Le module précédent a mis Claude Code dans un cron, une PR GitHub Actions et un SDK Python. Reste ce qui décide si Kiosque continue en octobre : combien ça coûte, ce que ça voit, et comment l'installer proprement pour cinq développeurs. Trois axes — coûts, contexte, sécurité — sur une règle : tout ce qui n'est pas indispensable au tour courant coûte du jeton et augmente la surface d'attaque.

Lire /usage

/usage est le premier réflexe. La ligne Total cost de la section Session affiche le coût local, calculé à partir des jetons au tarif affiché ; si un modelPricing géré est en vigueur, la mention at your organization's configured rates apparaît. En Pro/Max, ce chiffre est indicatif ; la facturation réelle passe par les crédits d'usage, visibles dans Usage credits et gérables via /usage-credits. /cost et /stats sont des alias.

À partir de la deuxième réponse, une ligne Prompt cache (main) s'ajoute : 14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · warm (1h TTL, last activity 40s ago). Un fort ratio de lecture signifie que la conversation lit surtout depuis le cache, facturé au tarif « cached » (environ 10 % du tarif d'entrée). Un miss désigne une requête qui a re-traité plus de 5 % et au moins 2 000 jetons de ce qui aurait pu être servi ; une cause probable s'affiche parfois (likely cause: tool definitions changed). Les expected rebuilds sont volontaires (compaction, nettoyage de tool-results). warm 1h TTL : conversation principale sur la fenêtre longue (garantie sur abonnement dans l'usage inclus ; sur crédits, clé API ou fournisseur cloud, cinq minutes par défaut).

Sous ces lignes, la section breakdown (touches d et w) attribue l'usage récent aux skills, sous-agents, plugins et serveurs MCP, et signale trois behavior flags au plus (long context, cache misses…) quand un comportement dépasse 10 %. Une ligne Loops liste les tâches /loop ordonnées par jetons. /insights écrit un rapport HTML dans ~/.claude/usage-data/report.html en analysant jusqu'à 200 sessions locales récentes.

Réduire les jetons

costs.md hiérarchise les gestes. Sur Kiosque, cinq gestes font baisser la facture d'un facteur trois : /clear entre tâches non liées (un contexte ouvert toute la journée facture la conversation entière à chaque tour ; /rename avant /clear pour retrouver via /resume) ; /compact avec instructions (/compact concentre-toi sur le correctif d'auth garde ce qui compte, à placer à une pause naturelle) ; le bon modèle (Sonnet gère 90 % du travail Kiosque à un coût inférieur à Opus ; Opus pour les décisions d'architecture et les traces multi-couches ; model: haiku pour un sous-agent trivial) ; moins de MCP allumés (/mcp liste les serveurs actifs) ; déporter dans un sous-agent (une lecture de dix fichiers reste dans son contexte, seul un résumé revient).

Compléments : MAX_THINKING_TOKENS=8000 (ou /effort medium) pour du travail simple, migrer les instructions détaillées de CLAUDE.md vers des skills chargées à la demande (viser CLAUDE.md < 200 lignes), prompts spécifiques (« ajoute la validation dans auth.ts » plutôt que « améliore l'auth »).

Comprendre le contexte

context-window.md décrit la fenêtre en couches. Avant la première frappe, une session Kiosque charge : prompt système et définitions d'outils (~4,5 k jetons, se rejoue à chaque changement d'outil), auto-mémoire (~700, premières 200 lignes ou 25 Ko de MEMORY.md), noms d'outils MCP (~120, schémas différés par tool search), descriptions de skills (~450, absentes après /compact sauf skills invoquées), ~/.claude/CLAUDE.md (~320), CLAUDE.md projet (~1 800). Chaque lecture ajoute 1 000 à 3 000 jetons ; chaque règle à paths: rejoint la conversation quand un fichier correspondant est lu ; un sous-agent maintient sa propre fenêtre.

Après /compact : prompt système et output style restent (hors historique), CLAUDE.md racine et règles non filtrées se rechargent depuis le disque, jusqu'à cinq fichiers récemment modifiés sont relus, skills invoquées réinjectées à 5 000 jetons chacune, 25 000 cumulés au maximum. Les règles à paths: réapparaissent quand un fichier correspondant est relu. Ce qui est écrit dans un fichier survit ; ce qui vit uniquement dans la conversation est résumé.

Ce qui invalide le cache

prompt-caching.md est la deuxième lecture indispensable. Le cache est un match de préfixe : toute modification à l'intérieur force à re-traiter la suite. Les invalidations coûteuses : /model (chaque modèle a son propre cache, Claude Code demande confirmation tant que le cache est chaud), changement d'effort mid-session (sauf Fable 5.1 sur clé API ou abonnement), activation du fast mode (l'en-tête modifie la clé de cache, un tour uncached est facturé au tarif fast mode), connexion/déconnexion d'un MCP dont les outils sont chargés en préfixe (les outils différés par tool search restent gratuits en cache), refus d'un outil entier via un deny sur Bash ou WebFetch, /compact (invalide par construction), changement d'output style, mise à jour de Claude Code.

Éditer un fichier, changer de mode de permission, invoquer une skill, faire /rewind ou /recap : rien de tout cela ne casse le cache. Un sous-agent démarre son propre cache. Choisissez modèle et effort en début de session, gardez /compact pour les pauses.

Pour confirmer le TTL : claude -p "hello" --output-format json, puis lire usage.cache_creation.ephemeral_1h_input_tokens versus ephemeral_5m_input_tokens. Deux réglages, promptCacheTtl (conversation principale) et subagentPromptCacheTtl (sous-agents, workflows, compaction, titres), acceptent 5m ou 1h. FORCE_PROMPT_CACHING_5M=1 force cinq minutes ; ENABLE_PROMPT_CACHING_1H=1 demande une heure. Sur clé API ou fournisseur cloud, mettre promptCacheTtl: 1h.

Quand activer le fast mode

fast-mode.md est explicite : /fast est une configuration Opus, pas un modèle différent. Disponible sur Opus 5 et Opus 4.8, tarifée 10 $/50$ par MTok entrée/sortie, facturée en crédits d'usage même sur abonnement. Le premier tour où fast mode s'active fait payer l'intégralité du contexte uncached au tarif fast mode ; activez-le donc au démarrage plutôt qu'en cours. Cas d'usage : debug interactif sous pression, itération serrée sur un patch React. À éviter pour un batch ou une PR revue en fond de nuit.

Sur Team/Enterprise, un Owner active fast mode dans Admin Settings > Claude Code ; sur Console, un admin dans Claude Code preferences. Sans provisionnement, l'API répond 429. Trois env vars pour les cas passerelle : CLAUDE_CODE_DISABLE_FAST_MODE=1, CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1, CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1. Pour un reset à chaque session : "fastModePerSessionOptIn": true.

Sécurité en trois couches

security.md pose l'architecture. En mode Manual, Claude Code démarre en lecture seule et demande avant chaque écriture ou exécution non triviale ; les commandes Bash en lecture (ls, cat, git status…) passent sans demander. En mode auto, un classifieur sépare les actions sûres, à valider, à refuser ; vos deny/ask restent prioritaires. La frontière de répertoire est stricte : Claude n'écrit que dans le dossier de démarrage et ses sous-dossiers. Élargissez avec additionalDirectories, restreignez la lecture avec denyRead sous sandboxing.

Trois gestes défensifs pour Kiosque : bloquer les commandes réseau (par défaut curl/wget demandent en Manual ; ajoutez-les dans permissions.deny), interdire les secrets (Read(./.env) et Read(./.env.*) dans permissions.deny), utiliser le hook ConfigChange pour auditer ou bloquer une modification de settings en session. Le sandbox isole les commandes Bash (filesystem, réseau). --bare reste la seule protection fiable contre l'injection en -p : sans lui, un CLAUDE.md, un hook ou un serveur MCP hostile du dossier courant sont chargés sans dialogue de confiance. Contre l'injection de prompt : relire chaque commande avant approbation, éviter de piper du contenu non fiable directement, exécuter les scripts risqués dans une VM ou un devcontainer. WebFetch utilise sa propre fenêtre. Sur Windows, désactiver WebDAV et refuser les chemins \\*.

Le plugin security-guidance

security-guidance.md installe une revue à trois couches, gratuite pour la couche motifs : à chaque édition, match d'expressions/substrings (eval(, new Function, os.system, child_process.exec, pickle, dangerouslySetInnerHTML, .innerHTML =, document.write, éditions dans .github/workflows/) sans appel modèle ; en fin de tour, revue modèle en arrière-plan sur le diff cumulé (jusqu'à 30 fichiers, trois passes en cascade au plus) ; à chaque git commit ou git push lancé par Claude via Bash, revue agentique plus profonde qui lit appelants et sanitizers (plafond 20 par heure glissante ; vos commits shell ne sont pas revus).

Installation : /plugin install security-guidance@claude-plugins-official, puis /reload-plugins. Pour toute l'équipe, "enabledPlugins": {"security-guidance@claude-plugins-official": true} dans .claude/settings.json. Deux extensions locales additives : .claude/claude-security-guidance.md (modèle de menace maison), .claude/security-patterns.yaml (motifs projet). Aucun ne peut désactiver un check natif. Quatre variables coupent une couche : ENABLE_PATTERN_RULES=0, ENABLE_STOP_REVIEW=0, ENABLE_COMMIT_REVIEW=0, ENABLE_CODE_SECURITY_REVIEW=0. SECURITY_GUIDANCE_DISABLE=1 désactive tout.

Complémentaire, /security-review fait une passe unique sur le diff branche courante versus branche par défaut d'origin. Utile avant d'ouvrir la PR. Sans origin, la commande échoue avec l'ambiguous argument documenté dans errors.md.

Régler l'équipe

settings.md définit cinq scopes, prioritaire d'abord : Managed, Command line (--settings), Project local (.claude/settings.local.json), Shared project (.claude/settings.json), User (~/.claude/settings.json). Les listes fusionnent (permissions.allow s'additionne au lieu de se remplacer), quatre exceptions pour les listes de modèles (fallbackModel, modelPicker, availableModels, modelSettings).

Pour Kiosque, le fichier partagé fixe les invariants :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(make test)",
      "Bash(make lint)",
      "Bash(ruff *)",
      "Bash(pytest *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  },
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true,
    "kiosque-tools@kiosque-marketplace": true
  }
}

.claude/settings.local.json, au .gitignore, sert aux exceptions personnelles. Les allow et additionalDirectories d'un settings partagé ne s'activent qu'après confiance du dossier (workspace trust) ; deny et ask s'appliquent immédiatement. /status liste les fichiers réellement chargés dans Setting sources. claude doctor détaille les entrées rejetées.

Certains clés sont ignorées dans le fichier partagé (colonne Scope User, local, or managed de settings-reference.md). Les administrateurs définissent des politiques via managed settings que rien de local ne peut relâcher, sauf quelques exceptions sécurité-sensitives où la valeur plus stricte l'emporte (disableClaudeAiConnectors: true, enableArtifact: false, isolatePeerMachines: true…). L'onboarding d'un nouveau développeur passe par /team-onboarding : Claude analyse les 30 derniers jours de sessions locales et écrit un guide markdown à copier-coller comme premier message ; sur claude.ai, un lien partageable est aussi retourné. /privacy-settings reste réservé aux abonnés Pro et Max.

En résumé

Lisez /usage chaque semaine, la ligne Prompt cache (main) chaque jour où le coût grimpe. Videz entre tâches non liées, compactez aux pauses, gardez Sonnet par défaut, Opus pour les décisions dures. N'activez /fast qu'en début de session sensible à la latence. Cadenassez les permissions dans .claude/settings.json partagé, installez security-guidance pour toute l'équipe, complétez avec /security-review, et distribuez la configuration via managed settings quand un point est non négociable.

Module suivant : « Projet : la boîte à outils Claude Code complète de l'équipe Kiosque ».