L'ingénierie de contexte est de l'architecture : 650 fichiers plus tard

Mon CLAUDE.md a commencé à 50 lignes. Six mois plus tard, il s’était transformé en une architecture distribuée de 650 fichiers répartis sur sept couches. Cette évolution a révélé que l’ingénierie de contexte n’est pas de l’ingénierie de prompts avec davantage de fichiers. C’est de l’architecture logicielle pour un substrat où la mémoire se dégrade à chaque token.

Le contexte n’est pas un fichier de configuration. C’est le substrat architectural qui détermine ce qu’un agent IA peut penser, ce qu’il retient et ce qu’il oublie. Toute autre décision de conception en découle. Ce qui suit représente six mois d’ingénierie de contexte en production pour Claude Code : l’architecture, les défaillances, et le système qui leur a survécu.

En bref

L’article de Böckeler sur l’ingénierie de contexte (martinfowler.com, 2026)¹ et le cadre de pensée claire de Miessler² font avancer la discussion, mais tous deux sous-estiment ce que l’utilisation en production exige. L’ingénierie de contexte nécessite de concevoir un système où les bonnes instructions atteignent l’agent au bon moment, et où les mauvaises instructions ne se chargent jamais. Mon système utilise neuf règles, 40 skills, 19 agents, 84 hooks et 14 fichiers de configuration répartis sur une hiérarchie à sept couches. L’architecture ne réside pas dans les fichiers eux-mêmes, mais dans quels fichiers se chargent à quel moment et ce qui en est exclu.

---

Le contexte n’est pas un fichier

L’article hebdomadaire « comment écrire un CLAUDE.md » passe à côté de l’essentiel. Écrire un bon CLAUDE.md est nécessaire mais insuffisant, de la même manière qu’écrire du bon code est nécessaire mais insuffisant pour construire un bon système. L’architecture est la structure qui détermine comment les composants interagissent. Dans les systèmes agents, le contexte est cette structure.

Mon premier CLAUDE.md était un monolithe : 200 lignes couvrant les normes de codage, la structure du projet, les préférences, les corrections, la philosophie, les identifiants et l’état des projets actifs. Cela a fonctionné pendant un mois. Puis trois choses se sont produites simultanément :

1. Le fichier a dépassé 300 lignes et a commencé à se contredire (la règle A disait « restez simple », la règle B disait « ajoutez une gestion d’erreurs approfondie »)
2. Le contexte du projet A a fuité dans le projet B (des règles spécifiques à iOS polluant une session de développement web)
3. L’agent dépensait des tokens à lire des instructions sans rapport avec la tâche en cours

Les symptômes pointent vers des problèmes architecturaux, pas des problèmes de documentation : couplage, fuite de périmètre et gaspillage de ressources. Les mêmes forces guident les décisions d’architecture logicielle.³

---

Les sept couches

Après six mois de refactorisation, mon système de contexte s’est stabilisé en une hiérarchie à sept couches. Chaque couche remplit un objectif distinct et se charge à un moment précis :

Couche	Contenu	Moment de chargement	Nombre
1. Noyau	CLAUDE.md : philosophie, projets actifs, corrections	À chaque démarrage de session	Un fichier, 205 lignes
2. Règles	Contraintes spécifiques au domaine (conception API, sécurité, tests, Git)	À chaque démarrage de session	Neuf fichiers
3. Skills	Modules de connaissances réutilisables avec procédures et exemples	À la demande (invoqués ou activés automatiquement par les hooks)	40 répertoires
4. Agents	Spécifications de reviewers/générateurs spécialisés	À la demande (via l’outil Task)	19 fichiers
5. Hooks	Injection automatique de contexte aux événements du cycle de vie	Événementiel (démarrage de session, pre-commit, post-tool)	84 scripts
6. Config	Paramètres numériques (seuils, budgets, limites)	Référencés par les hooks et les skills	14 fichiers JSON
7. État	Suivi en temps réel (lignée des agents, calibration de confiance, coûts)	Référencé par les hooks	36 fichiers

L’insight crucial est la séparation des couches. Les règles se chargent à chaque session car elles s’appliquent universellement. Les skills se chargent à la demande car ils sont spécifiques à un domaine. Les hooks se déclenchent sur des événements car le timing est déterminant. Charger les 650 fichiers au démarrage de la session épuiserait la fenêtre de contexte avant même que l’agent ne lise le premier message utilisateur.⁴

---

Trois défaillances qui ont façonné l’architecture

Défaillance 1 : Le CLAUDE.md monolithique

Mon CLAUDE.md original contenait des règles iOS, des règles web, des modèles de conception API, des conventions Git, la gestion des identifiants et des principes philosophiques, le tout dans un seul fichier. L’agent lisait l’intégralité à chaque session, même lorsqu’il construisait un projet web qui ne toucherait jamais à SwiftUI.

Le coût : Le contexte non pertinent consommait environ 4 000 tokens par session. Sur 50 sessions, cela représente 200 000 tokens dépensés pour des instructions que l’agent n’a jamais utilisées.

La solution : Extraire le contenu spécifique au domaine dans des fichiers rules/. rules/security.md se charge à chaque session (la sécurité s’applique partout). rules/ios-security.md ne se charge que lorsque la session concerne des projets iOS. L’article sur la gestion de la fenêtre de contexte documente l’économie de tokens qui a motivé cette décision.

Défaillance 2 : Les skills devenus obsolètes

J’ai créé un skill fastapi avec des exemples tirés de FastAPI 0.109. Trois mois plus tard, le projet utilisait FastAPI 0.115 avec des modèles différents. Le skill enseignait silencieusement des conventions obsolètes. L’agent produisait du code fonctionnel qui ne correspondait pas à la base de code actuelle.

Le coût : Une session de débogage de 45 minutes pour comprendre pourquoi un nouveau endpoint utilisait un modèle d’injection de dépendances différent de tous les autres endpoints. Le modèle provenait du skill obsolète, pas de la base de code.

La solution : Les skills référencent une documentation versionnée et incluent des dates de « dernière vérification ». Plus important encore, la boucle qualité exige que le code généré corresponde aux modèles existants de la base de code, une vérification métacognitive qui détecte la dérive des skills obsolètes indépendamment de leur contenu.

Défaillance 3 : Des règles contradictoires à différentes couches

CLAUDE.md disait « privilégiez les solutions simples ». Un skill disait « ajoutez une gestion d’erreurs approfondie avec logique de retry et circuit breakers ». Les deux étaient raisonnables isolément. Ensemble, ils produisaient un résultat incohérent, tantôt minimal, tantôt sur-ingénieré, selon l’instruction que l’agent pondérait le plus dans un tour donné.

Le coût : Une qualité de sortie imprévisible. Le même type de tâche produisait des niveaux de qualité différents d’une session à l’autre, rendant le système peu fiable.

La solution : Établir une hiérarchie de précédence claire. CLAUDE.md définit les principes (« privilégiez la simplicité »). Les règles définissent les contraintes (« validez toutes les entrées utilisateur »). Les skills définissent les procédures (« voici comment construire un endpoint FastAPI »). En cas de conflit, la couche la plus spécifique l’emporte : la procédure d’un skill prévaut sur les orientations d’un principe pour la tâche spécifique que le skill couvre. La résolution reflète la façon dont les langages de programmation gèrent la portée : le local surcharge le global.⁵

---

Le budget de contexte comme contrainte architecturale

La fenêtre de contexte n’est pas infinie. Les 200 000 tokens de la fenêtre de contexte de Claude⁶ semblent généreux jusqu’à ce que vous mesuriez ce qui les consomme :

Consommateur	Tokens typiques	% de la fenêtre
Prompt système + CLAUDE.md + règles	8 000-12 000	4-6 %
Historique de conversation	20 000-80 000	10-40 %
Lectures de fichiers (par fichier)	5 000-20 000	2,5-10 %
Sorties d’outils (par appel)	1 000-10 000	0,5-5 %
Contexte skill/agent (à la demande)	3 000-15 000	1,5-7,5 %

Les mesures de consommation de tokens proviennent de 50 sessions Claude Code que j’ai suivies entre août 2025 et février 2026.⁷ Une session intensive de 90 minutes peut épuiser la fenêtre par de simples lectures de fichiers et interactions avec les outils. Le budget de contexte impose des compromis architecturaux :

Toujours charger la philosophie fondamentale, les corrections actives et les règles de sécurité. Les trois sont peu coûteuses (4-6 % du budget) et universellement applicables.

Charger à la demande les skills, les spécifications d’agents et la documentation de référence. Chacun coûte 5-15 % de la fenêtre par skill et s’applique à un seul domaine. Ne les charger que lorsqu’ils sont pertinents préserve le budget pour le travail réel.

Ne jamais charger les documents de transfert obsolètes, les configurations dépréciées ou l’état historique. Chaque fichier obsolète consomme du budget sans améliorer la sortie. Le modèle d’ingénierie composée exige un élagage périodique du contexte qui ne justifie plus son coût en tokens.

La gestion du budget de contexte reflète le compromis qui guide l’indexation des bases de données, les stratégies de cache et la gestion mémoire en ingénierie logicielle traditionnelle.⁸ La contrainte diffère (des tokens au lieu d’octets), mais la discipline architecturale est identique.

---

Propagation du contexte dans les systèmes multi-agents

Lorsque l’agent principal engendre un sous-agent via l’outil Task, le choix du contexte à propager détermine toutes les autres décisions de conception. Mon système de délibération multi-agents utilise 10 agents de recherche. Chaque agent a besoin de suffisamment de contexte pour évaluer de manière indépendante, mais trop de contexte partagé provoque le problème de convergence documenté dans l’article sur les boids : des agents qui partagent trop de contexte produisent des conclusions identiques.

Les règles de propagation :

Type de contexte	Propagé ?	Pourquoi
Philosophie fondamentale	Oui	Cohérence entre les agents
Règles du domaine	Oui	Standards de qualité partagés
Instructions spécifiques à la tâche	Oui	Le travail concret
Historique de conversation	Non	L’indépendance exige l’isolation
Conclusions des autres agents	Non (jusqu’à la synthèse)	Empêche la convergence prématurée
Procédures des skills	Sélectivement	Uniquement les skills pertinents pour le rôle de l’agent

L’architecture Ralph résout un problème connexe : la propagation du contexte à travers le temps (itérations), et non à travers les agents (processus parallèles). Les deux partagent le même principe : propager les contraintes et les principes, isoler les détails d’implémentation.

---

Mesurer la qualité du contexte

Le nombre de tokens est une métrique indirecte. La véritable mesure de la qualité du contexte est : l’agent produit-il le bon résultat dès la première tentative ?

Après avoir suivi 50 sessions, j’ai identifié trois signaux de qualité :

Taux de réussite à la première tentative. À quelle fréquence la première réponse de l’agent ne nécessite aucune correction ? Avec le CLAUDE.md monolithique, le taux était d’environ 60 %. Après l’architecture à sept couches, il est monté à environ 80 %. L’amélioration provient de la suppression du contexte non pertinent (moins de distractions) et de l’ajout de skills spécifiques au domaine (des connaissances plus ciblées).⁹

Type de correction. Lorsque l’agent nécessite une correction, l’erreur est-elle factuelle (mauvaise API, mauvais modèle) ou un choix de jugement (mauvaise approche, mauvaise priorité) ? Les erreurs factuelles indiquent un contexte manquant. Les erreurs de jugement indiquent un contexte contradictoire ou ambigu. Suivre les types de correction révèle quelle couche nécessite une attention particulière.

Pression de contexte à la fin de la tâche. Quelle part du budget de contexte reste-t-il lorsque la tâche se termine ? Si la fenêtre est pleine à 90 % avant que la tâche ne soit à moitié terminée, l’architecture de contexte charge trop de contenu non pertinent. Mon système de hooks inclut un moniteur de pression de contexte qui alerte lorsque l’utilisation dépasse 70 %.

---

Le modèle d’architecture distribuée

Rien dans le système à sept couches n’est propre aux agents IA. Il reflète des modèles logiciels établis :

Modèle logiciel	Équivalent contextuel
Variables d’environnement	CLAUDE.md principal (toujours chargé, global)
Fichiers de configuration	Règles (chargées au démarrage, spécifiques au domaine)
Bibliothèques/modules	Skills (chargés à la demande, autonomes)
Microservices	Agents (isolés, communiquant via des protocoles)
Gestionnaires d’événements	Hooks (déclenchés par les événements du cycle de vie)
Base de données	Fichiers d’état (persistants, interrogeables)
Contrats API	Schémas de configuration (paramètres numériques partagés)

Le parallèle n’est pas métaphorique. Les mêmes forces (couplage, cohésion, portée, cycle de vie) conduisent à des décisions architecturales identiques.¹⁰ L’ingénierie de contexte est de l’ingénierie logicielle pour un substrat où la « mémoire » est une ressource rare et dégradable plutôt qu’une ressource abondante et persistante.¹¹

---

Points clés à retenir

Pour les ingénieurs qui construisent des systèmes agents :

• Concevez le contexte comme de l’architecture logicielle, pas comme de la documentation. Ce qui se charge quand, ce qui surcharge quoi, et ce qui se propage aux sous-agents détermine le comportement de l’agent bien plus que n’importe quelle instruction individuelle. Appliquez la même discipline de séparation des responsabilités que vous utilisez pour le code.

• Séparez les couches par cycle de vie. Les règles universelles se chargent à chaque session. Les connaissances spécifiques au domaine se chargent à la demande. L’état propre à la session reste transitoire. Mélanger les cycles de vie dans un même fichier crée les problèmes de couplage que l’architecture logicielle existe précisément pour résoudre.

Pour les équipes qui mettent à l’échelle des workflows IA :

• Traitez la fenêtre de contexte comme un budget. Les prompts système, les lectures de fichiers et les sorties d’outils consomment la fenêtre de 200 000 tokens. Chaque instruction persistante entre en compétition avec la mémoire de travail. Mesurez ce que vous chargez et élaguez ce qui ne justifie pas ses tokens.

• Les règles de propagation déterminent la qualité multi-agents. Les sous-agents ont besoin de principes partagés pour la cohérence et d’un état isolé pour l’indépendance. Propager trop de contexte provoque la convergence. En propager trop peu provoque l’incohérence.

---

Cet article s’appuie sur La gestion de la fenêtre de contexte (économie de tokens) et Le système Ralph (mémoire par système de fichiers). Le système de hooks Claude Code implémente la couche d’automatisation. Pour les modèles de coordination d’agents, voir Délibération multi-agents et Des boids aux agents.

---