Module 6 — Observation masking et KV-cache — Context Engineering — le pack Praktik

Objectif

À la fin de ce module, tu sauras masquer les outputs verbeux et structurer tes prompts pour maximiser le cache.

Observation masking

Principe

Remplacer les outputs d’outils verbeux par des références compactes une fois leur contenu traité. L’original reste récupérable si besoin.

Règles de masking

Situation	Action
Output critique pour la tâche en cours	Ne PAS masquer
Output des 3 derniers tours	Ne PAS masquer
Output déjà résumé dans la conversation	Masquer après 3+ tours
Output répété/dupliqué	Masquer IMMÉDIATEMENT
Headers et footers boilerplate	Masquer IMMÉDIATEMENT
Error output en cours de debug	Ne PAS masquer

Format de référence masquée

[Obs:{ref_id} masqué. Clé: {summary}. Complet récupérable.]

Exemple :

[Obs:grep-001 masqué. Clé: 12 fichiers trouvés, 3 pertinents 
(auth.ts, middleware.ts, config.ts). Complet récupérable.]

Gains typiques

60-80% de réduction sur les outputs masqués
<2% d’impact qualité
Latence quasi nulle

KV-cache optimization

Principe

Le KV-cache stocke les tenseurs Key/Value calculés pendant l’inférence. Quand des requêtes consécutives partagent un préfixe identique, les tenseurs sont réutilisés.

Gain : 50%+ de réduction de coût, 40%+ de réduction de latence sur les tokens cachés.

Ordonnancement optimal

# 1. System prompt (le plus stable — ne change jamais)
# 2. Tool definitions (stables entre requêtes)
# 3. Templates et few-shot réutilisés
# 4. Historique de conversation (partage le préfixe)
# 5. Requête actuelle et contenu dynamique (toujours à la fin)

Ce qui casse le cache

Changement	Impact
Espace ou newline dans le system prompt	Cache invalidé en aval
Timestamp dans le system prompt	Cache miss à chaque jour
Compteur de session dans le prompt	Cache miss à chaque requête
Réordonnancement des outils	Cache invalidé

Règles pour un cache stable

Épingler le system prompt comme string immuable
Ne pas interpoler de timestamps, versions, ou IDs de session
Déplacer les métadonnées dynamiques dans un message user séparé
Diff byte-for-byte les templates de prompt entre déploiements

Budget et triggers

Allocation type

budgets:
  tool_outputs: 35%        # Souvent le plus gros poste
  message_history: 30%
  retrieved_documents: 20%
  reserved_buffer: 15%     # Marge pour nouveaux outputs

triggers:
  tool_outputs_over_budget: masquer les observations résolues
  total_context_over_70%: compacter l'historique
  retrievals_irrelevantes: resserrer le scope de recherche

Ordre d’optimisation

KV-cache d’abord (pas de perte qualité, gain immédiat)
Masking ensuite (largest capacity gain)
Compaction ensuite (lossy, mais contrôlé)
Partitioning en dernier recours (overhead de coordination)

Checklist de validation

Je masque les outputs verbeux après traitement
Je ne masque jamais les errors en cours de debug
Mon system prompt est immuable (pas de timestamps)
Les métadonnées dynamiques sont dans un message user séparé
J’ai un budget alloué par catégorie
Je connais l’ordre d’optimisation (cache → masking → compaction → partition)

Un espace dans le system prompt invalide tout le cache. → Même un seul whitespace ou newline de différence dans le préfixe invalide le KV-cache en aval. Diff tes templates byte-for-byte entre déploiements. Un changement de version dans le prompt = pic de coût 2-5x jusqu’à ce que le nouveau cache se réchauffe.

Prochaine étape

→ Module 7 (Subagents et partitionnement) pour splitter quand un seul contexte ne suffit plus