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 est de l’architecture logicielle pour un substrat dont la mémoire se dégrade à chaque token, et non de l’ingénierie de prompts avec davantage de fichiers.
Le contexte 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.
L’ingénierie de contexte pour agents IA consiste à concevoir des systèmes qui fournissent à l’agent les bonnes instructions au bon moment tout en garantissant que les instructions non pertinentes ne se chargent jamais. Elle va au-delà de la rédaction d’un bon fichier de prompt : elle exige une architecture en couches où règles, skills, hooks, configurations et fichiers d’état se chargent chacun à des événements précis du cycle de vie. Ce qui est exclu compte autant que ce qui est inclus, car chaque token non pertinent évince du contexte dont l’agent a réellement besoin pour produire un résultat correct.
En bref
L’article de Böckeler sur l’ingénierie de contexte (martinfowler.com, 2026)1 et le cadre de pensée claire de Miessler2 font avancer la discussion, mais tous deux sous-estiment ce qu’exige l’utilisation en production. 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 réside dans le choix des fichiers qui se chargent, et du moment où ils se chargent. Ce qui est exclu compte autant que ce qui est inclus.
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 la manière dont les composants interagissent. Dans les systèmes d’agents, le contexte est cette structure.
Ce qui avait commencé à 50 lignes était devenu un monolithe : mon premier CLAUDE.md comptait 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 :
- 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 »)
- Le contexte du projet A a fuité dans le projet B (des règles spécifiques à iOS polluaient une session de développement web)
- 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 d’architecture, et non de documentation : couplage, fuite de périmètre et gaspillage de ressources. Ce sont les mêmes forces qui guident les décisions d’architecture logicielle.3
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 rôle distinct et se charge à un moment précis :
| Couche | Contenu | Quand elle se charge | Nombre |
|---|---|---|---|
| 1. Noyau | CLAUDE.md : philosophie, projets actifs, corrections |
À chaque début de session | Un fichier, 205 lignes |
| 2. Règles | Contraintes propres à un domaine (conception d’API, sécurité, tests, git) | À chaque début 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 des hooks) | 40 répertoires |
| 4. Agents | Spécifications de relecteurs et de générateurs spécialisés | À la demande (via l’outil Task) | 19 fichiers |
| 5. Hooks | Injection automatique de contexte lors des événements du cycle de vie | Pilotés par les événements (début 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 direct (lignée des agents, calibration de la confiance, coûts) | Référencé par les hooks | 36 fichiers |
L’idée essentielle est la séparation des couches. Les règles se chargent à chaque session parce qu’elles s’appliquent universellement. Les skills se chargent à la demande parce qu’ils sont propres à un domaine. Les hooks se déclenchent sur des événements parce que le moment compte. Charger les 650 fichiers au début de la session épuiserait la fenêtre de contexte avant même que l’agent ait lu le premier message de l’utilisateur.4
Un exemple concret pour chaque couche :
Layer 1 (Core): ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules): ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills): ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents): ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks): ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config): ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State): ~/.claude/state/agent-lineage.json — tracks active agent tree
Chaque fichier de la hiérarchie a une responsabilité unique et un déclencheur de chargement clair. Le hook (couche 5) se déclenche au pre-commit, quel que soit le type de projet. Le skill (couche 3) ne se charge que lorsqu’une tâche FastAPI commence. Cette distinction détermine le coût en tokens.
Trois défaillances qui ont façonné l’architecture
Défaillance 1 : le CLAUDE.md monolithique
Mon CLAUDE.md d’origine contenait des règles iOS, des règles web, des modèles de conception d’API, des conventions git, la gestion des identifiants et des principes philosophiques, le tout dans un seul fichier. L’agent lisait l’ensemble à chaque session, même pour construire un projet web qui ne toucherait jamais à SwiftUI.
Le coût : le contexte non pertinent consommait environ 4 000 tokens par session, selon mon estimation. Sur 50 sessions, cela représente quelque 200 000 tokens dépensés pour des instructions que l’agent n’a jamais utilisées.
La solution : extraire le contenu propre à chaque 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 : des 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 en silence des conventions dépassées. 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 nouvel endpoint utilisait un modèle d’injection de dépendances différent de celui de tous les autres endpoints. Le modèle venait du skill obsolète, pas de la base de code.
La solution : les skills renvoient à une documentation versionnée et portent une date de dernière vérification (« last verified »). 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 d’un skill obsolète quel que soit son contenu.
Défaillance 3 : des règles contradictoires sur différentes couches
CLAUDE.md disait « préférez les solutions simples ». Un skill disait « ajoutez une gestion d’erreurs approfondie avec logique de nouvelle tentative et disjoncteurs (circuit breakers) ». Chacune était raisonnable prise isolément. Ensemble, elles produisaient des résultats incohérents (tantôt minimalistes, tantôt surdimensionnés) selon l’instruction que l’agent pondérait le plus lors d’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, ce qui rendait le système peu fiable. Voici les instructions contradictoires réelles :
# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.
# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
for all external API calls.
Les deux sont correctes prises isolément. « Préférez les solutions simples » est un bon conseil général. « Ajoutez une logique de nouvelle tentative pour les appels externes » est un bon conseil propre au domaine. Mais un agent qui lit les deux omettra parfois la logique de nouvelle tentative (en suivant le principe de simplicité) et surdimensionnera parfois une fonction simple (en suivant l’instruction de gestion des erreurs).
La solution : établir une hiérarchie de priorité claire. CLAUDE.md fixe les principes (« privilégiez la simplicité »). Les règles fixent les contraintes (« validez toutes les entrées utilisateur »). Les skills fixent 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 prime sur l’orientation d’un principe pour la tâche précise que couvre le skill. Cette résolution reflète la façon dont les langages de programmation gèrent la portée : le local prime sur le global.5 La correction pour l’exemple ci-dessus consiste à ajouter une précision au skill : « Ajoutez une logique de nouvelle tentative pour les appels d’API externes (cela prime sur le principe général de simplicité pour le code dépendant du réseau, car les appels externes échouent de manière intermittente et les nouvelles tentatives ne relèvent pas du surdimensionnement). »
Le budget de contexte comme contrainte architecturale
La fenêtre de contexte n’est pas infinie. La fenêtre de contexte standard de 200 000 tokens de Claude6 semble généreuse jusqu’à ce que vous mesuriez ce qui la consomme. (Une bêta à 1M de tokens existe via un en-tête d’API ; elle augmente le budget en proportion mais ne supprime pas les compromis : charger 650 fichiers épuiserait même 1M de tokens.)
| 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.7 Une session intensive de 90 minutes peut épuiser la fenêtre par de simples lectures de fichiers et interactions avec les outils. Notez que la fenêtre de 200K correspond à la capacité d’entrée totale ; l’attention effective du modèle (la portion qu’il traite avec une grande fidélité) est un chiffre différent et plus petit. La discipline du budget de contexte compte même lorsque la consommation totale de tokens reste bien en deçà de la limite, car les instructions placées au début d’un long contexte reçoivent une attention plus fiable que celles situées au milieu. 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. Les charger quand elles ne servent pas coûte très peu. Les omettre quand elles sont nécessaires coûte un résultat incorrect.
Charger à la demande les skills, les spécifications d’agents et la documentation de référence. Chaque skill coûte 5-15 % de la fenêtre et s’applique à un seul domaine. Ne les charger que lorsqu’ils sont pertinents préserve le budget pour le travail réel. Le déclencheur du chargement d’un skill est le type de tâche, et non le type de session : une session de développement web qui rencontre une migration de base de données a besoin du skill base de données, même s’il n’a pas été chargé au démarrage.
Ne jamais charger les documents de passation périmés, les configurations obsolètes ni l’état historique. Chaque fichier périmé consomme du budget sans améliorer le résultat. Pire, un contexte périmé dégrade activement le résultat en enseignant des modèles dépassés. Le modèle de l’ingénierie composée exige d’élaguer régulièrement le contexte qui ne justifie plus son coût en tokens.
La budgétisation du contexte reflète le même compromis qui guide l’indexation des bases de données, les stratégies de cache et la gestion de la mémoire dans le logiciel traditionnel.8 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 lance un sous-agent via l’outil Task, le choix du contexte à propager conditionne 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 aboutissent à des conclusions identiques.
Les règles de propagation :
| Type de contexte | Propagé ? | Pourquoi |
|---|---|---|
| Philosophie fondamentale | Oui | Cohérence entre les agents |
| Règles de domaine | Oui | Normes de qualité partagées |
| Instructions propres à la tâche | Oui | Le travail lui-même |
| Historique de conversation | Non | L’indépendance exige l’isolation |
| Conclusions des autres agents | Non (jusqu’à la synthèse) | Empêche une 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 voisin : la propagation du contexte dans le temps (les itérations), et non entre agents (les processus parallèles). Les deux partagent le même principe : propager les contraintes et les principes, isoler les détails d’implémentation.
La propagation en pratique
Un exemple concret éclaire le compromis. Lorsque l’agent principal lance un sous-agent de revue de sécurité, le prompt Task comprend :
## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py
## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)
Le relecteur de sécurité reçoit 2 000 tokens de contexte au lieu de 40 000. Il évalue le code selon des critères de sécurité, sans être distrait par les décisions d’interface ni biaisé par les conclusions d’un autre agent. L’isolation produit une évaluation indépendante. Si le relecteur de sécurité et le relecteur d’architecture signalent le même problème chacun de leur côté, la conclusion est plus fiable que si l’un avait vu le rapport de l’autre et l’avait approuvé.
Observer la qualité du contexte
Le nombre de tokens est un indicateur indirect. La vraie mesure de la qualité du contexte est la suivante : l’agent produit-il le bon résultat du premier coup ?
Après avoir suivi 50 sessions, j’ai identifié trois signaux de qualité :
Taux de réussite au premier essai. À quelle fréquence la première réponse de l’agent ne nécessite-t-elle aucune correction ? Avec le CLAUDE.md monolithique, le taux tournait autour de 60 %. Après le passage à l’architecture à sept couches, il est monté à environ 80 %. L’amélioration est venue de la suppression du contexte non pertinent (moins de distractions) et de l’ajout de skills propres à chaque domaine (davantage de connaissances pertinentes).9
Voici un avant/après représentatif tiré du journal de suivi. La tâche est identique : « ajouter une limitation de débit (rate limiting) à un endpoint d’API ».
Avant (CLAUDE.md monolithique, juillet 2025). La première réponse de l’agent importait une bibliothèque de limitation de débit que le projet n’utilisait pas (il suivait un exemple du skill FastAPI obsolète, chargé en même temps que les règles iOS, les règles de sécurité et 150 lignes de contenu sans rapport). La correction : « utilisez la classe RateLimiter existante dans app/middleware.py ». Une correction, classée comme « erreur factuelle : contexte de la base de code manquant ».
Après (architecture à sept couches, novembre 2025). Même type de tâche, endpoint différent. La première réponse de l’agent utilisait le middleware RateLimiter existant, reprenait la convention de nommage des paramètres des endpoints voisins et citait la source du modèle : « following the rate limiting pattern in app/middleware.py:42 ». Aucune correction nécessaire. Le skill FastAPI (couche 3) s’est chargé à la demande et contenait des modèles à jour ; les règles iOS ne se sont pas chargées, car la session ne comportait aucun travail iOS.
Pour suivre cela vous-même : étiquetez chaque session d’agent dans un journal comme « acceptée » ou « corrigée » après la première réponse, puis calculez le ratio chaque mois. La granularité n’a pas besoin d’être précise : les tendances sur 20 sessions ou plus sont plus utiles que des pourcentages exacts.
Type de correction. Lorsque l’agent a besoin d’une correction, l’erreur est-elle factuelle (mauvaise API, mauvais modèle) ou relève-t-elle du jugement (mauvaise approche, mauvaise priorité) ? Les erreurs factuelles signalent un contexte manquant : l’agent ne disposait pas des informations nécessaires pour produire la bonne réponse. Les erreurs de jugement signalent un contexte contradictoire ou ambigu : l’agent disposait des informations mais a mal pondéré des instructions concurrentes. La distinction compte, car la correction diffère : les erreurs factuelles demandent d’ajouter du contexte (une nouvelle règle ou un nouveau skill), tandis que les erreurs de jugement demandent de clarifier le contexte (résoudre un conflit entre couches existantes). Suivre les types de correction révèle quelle couche demande de l’attention.
Pression sur le contexte à la fin de la tâche. Quelle part du budget de contexte reste-t-il quand la tâche se termine ? Si la fenêtre est remplie à 90 % avant que la tâche soit à moitié faite, l’architecture de contexte charge trop de contenu non pertinent. Mon système de hooks comprend un moniteur de pression du contexte qui avertit lorsque l’utilisation dépasse 70 %.
Une session pas à pas : ce qui se charge, et quand
Un déroulé concret montre comment les sept couches interagissent lors d’une tâche réelle. Le scénario : je demande à Claude Code « d’ajouter une limitation de débit à l’endpoint /api/ab/event » dans le projet blakecrosley.com.
Début de session (0 s). Claude Code charge la couche 1 (CLAUDE.md, 205 lignes, ~800 tokens) et la couche 2 (les 9 fichiers de règles, ~3 200 tokens). Contexte total consommé : ~4 000 tokens (2 % de la fenêtre de 200K). L’agent connaît désormais ma philosophie de code, les exigences de sécurité, les conventions de conception d’API et le workflow git, quoi que je lui demande.
Début de la tâche (2 s). L’agent lit la tâche et l’identifie comme une modification d’endpoint FastAPI. La couche 5 (hooks) se déclenche : le hook UserPromptSubmit injecte la date du jour et le contexte de la session (~200 tokens). L’agent ne charge ni le skill SwiftUI, ni les règles de sécurité iOS, ni le skill de prompts Midjourney. Ces fichiers existent mais ne sont pas pertinents. Les exclure économise ~8 000 tokens.
Lectures de fichiers (5-30 s). L’agent lit app/main.py, le code de l’endpoint existant et le fichier de tests. Chaque lecture consomme 5 000 à 15 000 tokens de contexte. Après la lecture de trois fichiers : ~30 000-50 000 tokens consommés (15-25 % de la fenêtre).
Activation d’un skill (si nécessaire). Si l’agent a besoin de modèles propres à FastAPI, il charge la couche 3 (skills/fastapi/SKILL.md, ~2 500 tokens). Le skill se charge parce que la tâche l’exige, et non parce que la session a commencé. S’il s’agissait d’une tâche purement CSS, le skill FastAPI ne se chargerait jamais.
Implémentation et vérification (de 30 s à 5 min). L’agent écrit le code, exécute les tests et rend compte des résultats. À la fin de la tâche, la consommation de contexte se situe généralement entre 60 000 et 100 000 tokens (30-50 % de la fenêtre). Le budget restant laisse de la place pour des questions de suivi, des corrections ou une deuxième tâche dans la même session.
L’observation clé : les couches 1 et 2 consomment 2 % de la fenêtre et s’appliquent à chaque tâche. Le contenu des couches 3 à 7 se charge de manière sélective et ne consomme 5-25 % que lorsqu’il est pertinent. Si les 650 fichiers se chargeaient au début de la session, ils consommeraient environ 150 000-200 000 tokens et ne laisseraient presque aucune place au travail réel.
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 bien établis :
| Modèle logiciel | Équivalent en contexte |
|---|---|
| Variables d’environnement | CLAUDE.md principal (toujours chargé, global) |
| Fichiers de configuration | Règles (chargées au démarrage, propres à un domaine) |
| Bibliothèques/modules | Skills (chargés à la demande, autonomes) |
| Microservices | Agents (isolés, communiquant par 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 d’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.10 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’abondante et persistante.11
Une validation indépendante de cette architecture vient du projet obra/superpowers, qui a fait émerger de son côté une structure multicouche similaire pour le contexte de Claude Code : principes fondamentaux dans un fichier global, skills de domaine chargés à la demande et procédures de vérification séparées des instructions de comportement.12 Cette convergence suggère que l’architecture en couches n’est pas un choix de conception idiosyncrasique, mais une réponse naturelle aux contraintes du substrat.
Points clés à retenir
Pour les ingénieurs qui construisent des systèmes d’agents :
-
Concevez le contexte comme une architecture logicielle, pas comme de la documentation. Ce qui se charge et quand, ce qui prime sur quoi et ce qui se propage aux sous-agents détermine le comportement de l’agent davantage que n’importe quelle instruction isolée. Appliquez la même discipline de séparation des responsabilités que pour le code.
-
Séparez les couches selon leur cycle de vie. Les règles universelles se chargent à chaque session. Les connaissances propres à un domaine se chargent à la demande. L’état propre à une session reste transitoire. Mélanger les cycles de vie dans un seul fichier crée précisément les problèmes de couplage que l’architecture logicielle a pour objet de résoudre.
Pour les équipes qui font passer leurs workflows IA à l’échelle :
-
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 200K tokens. Chaque instruction persistante entre en concurrence 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.
Exercice : auditez votre système de contexte. Créez cette arborescence et remplissez-la avec vos instructions existantes :
mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/
Répondez ensuite à ces questions : quels fichiers se chargent à chaque session alors qu’ils devraient se charger à la demande ? Quels fichiers à la demande manquent ? Consignez les réponses dans un journal simple : étiquetez chaque session « correcte du premier coup » ou « correction nécessaire » et examinez le ratio au bout de 20 sessions.
Questions fréquentes
Comment structurer les fichiers de contexte pour des agents de code IA ?
Extrayez le contenu propre à un domaine dans des fichiers distincts lorsqu’il dépasse 20-30 lignes et qu’il serait inutile dans au moins une partie des sessions. Si vous écrivez des règles propres à iOS et des règles propres au web dans le même CLAUDE.md, l’agent lit les deux, quel que soit le projet en cours. Gardez les contraintes universelles (règles de sécurité, normes de codage, principes philosophiques) dans le fichier principal. Déplacez les modèles propres à un domaine (endpoints FastAPI, conventions SwiftUI, requêtes de base de données) dans des fichiers à la demande qui ne se chargent que lorsque la tâche l’exige.
Comment savoir qu’un skill est devenu obsolète ?
Deux signaux : l’agent produit du code qui fonctionne mais ne correspond pas aux modèles actuels de la base de code, ou l’agent fait référence à des API ou à des modèles d’une ancienne version d’un framework. Ajoutez à chaque skill une date de dernière vérification et contrôlez-la chaque trimestre. Plus important encore, la boucle qualité (le code généré correspond-il aux modèles existants ?) détecte la dérive d’un skill obsolète quel que soit son contenu.
Quelle est la bonne taille pour un budget de contexte ?
Pour une fenêtre de 200K tokens, réservez 4-6 % au prompt système et aux règles (toujours chargés), laissez 40-60 % à l’historique de conversation et aux lectures de fichiers (le travail réel), et prévoyez 10-15 % pour les skills et le contexte d’agents à la demande. Si la pression sur le contexte dépasse 70 % avant que la tâche soit à moitié faite, vous chargez trop de contenu non pertinent. Les pourcentages précis dépendent de la complexité de la tâche : une refactorisation sur plusieurs fichiers consomme plus de contexte que la correction d’un bug dans une seule fonction.
Comment gérer des instructions contradictoires entre couches ?
Appliquez une priorité fondée sur la portée : la couche la plus spécifique l’emporte. Les skills (portée locale) priment sur les règles (portée du module), qui priment elles-mêmes sur CLAUDE.md (portée globale). Lorsque vous découvrez un conflit, rendez la résolution explicite plutôt que de compter sur le modèle pour le résoudre de manière probabiliste. Ajoutez une note dans la couche la plus spécifique : « Ceci prime sur le principe général X dans ce contexte précis, parce que Y. »
Cet article s’appuie sur Gestion de la fenêtre de contexte (économie des tokens) et Le système Ralph (mémoire par système de fichiers). Le système de hooks de 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.
-
Birgitta Böckeler, « Context Engineering for Coding Agents, » martinfowler.com, février 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Bharani Subramaniam, collègue de Böckeler, définit l’ingénierie de contexte comme « curating what the model sees so that you get a better result. » La définition est juste. Le présent article soutient que la structure selon laquelle ces informations sont organisées et fournies relève d’une discipline architecturale, et non d’un exercice de documentation. ↩
-
Daniel Miessler, « How to Talk to AI, » danielmiessler.com, juin 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler soutient que la véritable compétence qui sous-tend à la fois l’ingénierie de prompts et l’ingénierie de contexte est la clarté de pensée : la capacité à formuler exactement ce que l’on veut accomplir. Cette approche complète le présent article, qui se concentre sur la discipline structurelle de l’organisation du contexte plutôt que sur la manière d’y réfléchir clairement. ↩
-
Le parallèle avec l’architecture logicielle est délibéré. Robert C. Martin, Clean Architecture : A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, partie III (Design Principles) et partie V (Architecture). Martin identifie les mêmes forces : couplage, cohésion et séparation des responsabilités. La différence, dans les systèmes de contexte IA, est que la « mémoire » est éphémère et bornée, ce qui ajoute une contrainte que l’architecture traditionnelle ne connaît pas. ↩
-
Le chiffre de 650 fichiers est la mesure de l’auteur en février 2026. Contexte global : ~400 fichiers (règles, skills, agents, hooks, configurations, état, documentation, passations). Contexte propre au projet (blakecrosley.com) : ~250 fichiers (PRD, documentation, plans, workflows, configurations i18n). Seule une fraction se charge à chaque session. ↩
-
La résolution de la portée des variables dans les langages de programmation (locale, englobante, globale, intégrée) est l’analogie directe. La règle LEGB de Python définit la même hiérarchie : portée locale, portée de la fonction englobante, portée globale, portée intégrée. Voir Python Software Foundation, « Execution Model, » section 4.2.2, « Resolution of names. » docs.python.org/3/reference/executionmodel.html. Les skills (portée locale) priment sur les règles (portée du module), qui priment sur CLAUDE.md (portée globale). L’analogie atteint un peu ses limites, car le suivi d’instructions par un LLM est probabiliste et non déterministe, mais le principe architectural tient. ↩
-
Anthropic, « Models overview, » platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. Tous les modèles Claude actuels (Opus 4.6, Sonnet 4.6, Haiku 4.5) indiquent une fenêtre de contexte de 200K tokens, Opus 4.6 et Sonnet 4.6 prenant en charge 1M de tokens en bêta. ↩
-
Mesures de consommation de tokens issues de 50 sessions Claude Code que j’ai suivies entre août 2025 et février 2026. Voir Gestion de la fenêtre de contexte pour la méthodologie complète. ↩
-
L’analogie entre budgets de tokens et hiérarchies mémoire suit le cadre de Hennessy, J.L. et Patterson, D.A., Computer Architecture : A Quantitative Approach, 6e édition, Morgan Kaufmann, 2017, chapitre 2 (Memory Hierarchy Design). Le traitement par Hennessy et Patterson des hiérarchies de cache, de la localité des références et du coût de l’accès mémoire aux différents niveaux se transpose directement à l’ingénierie de contexte : le contexte souvent nécessaire (cache L1 / règles fondamentales) se charge le plus vite, tandis que le contexte rarement nécessaire (disque / skills à la demande) ne se charge que lorsqu’il est référencé. ↩
-
Le taux de réussite au premier essai est une mesure approximative fondée sur l’appréciation subjective de l’auteur quant à la nécessité de corriger la première réponse. Il ne s’agit pas d’une expérience contrôlée. Le sens de l’amélioration (de 60 % à 80 %) est constant d’un type de session à l’autre, mais ne doit pas être cité comme une mesure précise. ↩
-
James Lewis et Martin Fowler, « Microservices, » martinfowler.com, mars 2014. martinfowler.com/articles/microservices.html. Lewis et Fowler définissent les microservices comme « a suite of small services, each running in its own process and communicating with lightweight mechanisms. » Les forces qu’ils identifient (déploiement indépendant, gouvernance décentralisée, contextes délimités) correspondent directement à l’isolation des agents et à la communication par protocoles dans l’architecture de contexte décrite ici. ↩
-
L’idée du « contexte comme architecture » s’inspire de Xu et al., « Everything is Context: Agentic File System Abstraction for Context Engineering, » arXiv, décembre 2025. arxiv.org/abs/2512.05470. L’article propose une abstraction de type système de fichiers pour gérer le contexte dans les systèmes d’IA générative, en traitant des artefacts de connaissance variés, la mémoire et les outils comme du contexte dans les limites des tokens. Ce cadre théorique appuie l’architecture pratique décrite ici. ↩
-
obra/superpowers, github.com/obra/superpowers. Le projet superpowers organise le contexte des agents en instructions fondamentales, skills à la demande et procédures de vérification, une structure qui a convergé avec l’architecture à sept couches décrite ici bien qu’elle ait été développée indépendamment. Cette convergence appuie la thèse selon laquelle le contexte en couches est une réponse architecturale naturelle aux fenêtres de contexte bornées. ↩