Context Engineering

---

1. Du Prompt Engineering au Context Engineering

La distinction fondamentale

Le travail s'est déplacé : on ne formule plus une bonne requête, on organise ce que le modèle voit pour qu'il produise un bon résultat. C'est l'idée derrière le terme context engineering, popularisé par Birgitta Böckeler (Thoughtworks) dans ses écrits sur l'IA en développement.

Le problème que ça résout

L'adoption des outils IA est devenue quasi générale dans les équipes engineering (≈ 80 %+ selon les enquêtes DORA / Stack Overflow 2024-2025). Pourtant, au bout de quelques mois, beaucoup constatent la même chose :

• L'IA génère du code qui ne suit pas leurs conventions
• Elle ignore les décisions d'architecture du dernier trimestre
• Elle utilise des librairies dépréciées
• Le code dupliqué explose : GitClear mesure les blocs dupliqués au plus haut jamais observé, pendant que la part de code réellement retravaillé s'effondre sur la même période

Sur ce dernier point, ne me crois pas sur parole : GitClear remesure chaque trimestre, sur des dizaines de millions de lignes. Le chiffre du jour est consultable, ce qui vaut mieux qu'une valeur figée dans un guide et fausse dans six mois. La source est dans les références.

Ce n'est pas le modèle qui est mauvais. C'est le contexte qui est manquant ou obsolète.

Sans contexte structuré, chaque session repart de zéro et l'IA tranche selon son entraînement, donc cohérente avec le « web moyen », pas avec ton codebase.

---

2. L'analogie OS (approfondissement)

Reprends l'analogie du Module 1 et pousse-la plus loin :

Là où l'OS décide quel processus charge quelles données, dans quel ordre, pendant combien de temps, le Context Engineer décide quel fichier de contexte charge quelles règles, scopées à quels fichiers, actives quand.

Un bon système de contexte, comme un bon OS :

• Charge uniquement ce qui est pertinent (pas tout en mémoire)
• Décharge ce qui est obsolète (garbage collection = /clear)
• Maintient un état cohérent (conventions versionnées = registry)

---

3. Les 4 stratégies du Context Engineering

Stratégie 1 : ÉCRIRE — Persister l'info hors du contexte

Tes instructions disparaissent entre les sessions ? Écris-les une fois pour toutes dans des fichiers de contexte, que l'outil relit tout seul à chaque démarrage. Selon ton outil :

• CLAUDE.md → lu par Claude Code à chaque démarrage
• .cursor/rules/*.mdc → règles scoped par Cursor
• .github/copilot-instructions.md → instructions Copilot
• GEMINI.md → contexte Gemini CLI

---

Stratégie 2 : SÉLECTIONNER — Ne charger que le pertinent

Tout inclure noie l'attention du modèle. Le geste inverse : ne charger que ce qui sert à la tâche du moment, en ciblant par fichier ou par répertoire.

• Référencement @fichier pour ciblage explicite
• Rules scopées par glob pattern (Cursor)
• Skills chargés on-demand (Claude Code)
• Sous-répertoires avec leur propre CLAUDE.md

---

Stratégie 3 : COMPRIMER — Réduire les tokens, pas l'information

Les longues sessions accumulent du bruit : historique, tentatives ratées, fichiers devenus inutiles. On le résume et on le compacte, sans perdre l'info qui compte.

• /compact [instructions] dans Claude Code
• /clear entre tâches non liées
• Résumés de session écrits dans un fichier du repo (ex. specs/outcome.md) avant de fermer
• Prompts de récapitulation en début de nouvelle session

---

Stratégie 4 : ISOLER — Séparer les types de contexte

Mélanger deux tâches dans la même session, c'est créer des interférences. Sépare : une session par sujet, des agents spécialisés, des skills encapsulés.

• Une tâche = une session
• Subagents pour l'investigation (ne pollue pas le contexte principal)
• Skills thématiques (sécurité, tests, migration...)
• Git worktrees pour faire tourner deux sessions en parallèle sans qu'elles se marchent dessus (Module 6 §8)

---

4. Construire un CLAUDE.md efficace

Structure recommandée

# [Nom du projet]

## Stack technique
- Runtime : Node.js 22 / Python 3.12 / Java 21
- Framework : NestJS 10 / Django / Spring Boot 3
- DB : PostgreSQL 15 + Redis 7
- Tests : Vitest / pytest / JUnit 5
- CI/CD : GitHub Actions + Docker

## Commandes essentielles
\`\`\`bash
npm run dev          # Démarrer en dev
npm run test         # Tests unitaires
npm run test:e2e     # Tests E2E
npm run lint         # Linter
npm run build        # Build production
\`\`\`

## Architecture
- Pattern : Repository + Service + Controller
- Voir @docs/architecture.md pour les décisions ADR

## Conventions de code
- Imports : ES Modules uniquement (pas de CommonJS)
- Nommage : camelCase variables, PascalCase classes, kebab-case fichiers
- Async : async/await uniquement (pas de .then/.catch)
- Erreurs : toujours throw des instances de nos classes d'erreur custom (voir @src/errors/)

## Anti-patterns — NE JAMAIS FAIRE
- Ne pas logger les request bodies (contiennent des données PII)
- Ne pas utiliser console.log — utiliser le logger interne : @src/utils/logger.ts
- Ne pas exposer de stack traces en production
- Ne pas commiter de secrets ou tokens

## Tests
- Chaque service doit avoir ses tests unitaires
- Mocks : utiliser vi.mock() (Vitest), pas de jest.mock()
- Fixtures dans /tests/fixtures/
- Coverage minimum : 80%

## Git
- Branches : feature/[ticket-id]-description, fix/[ticket-id]-description
- Commits : Conventional Commits (feat:, fix:, chore:, docs:)
- PR : toujours une description + lien ticket

## Contexte additionnel
- Conventions Git : @docs/git-workflow.md
- Patterns sécurité : @docs/security-patterns.md
- Guide onboarding : @README.md

Les règles d'un bon CLAUDE.md

À inclure :

• Commandes bash que l'IA ne peut pas deviner
• Règles de style qui diffèrent des conventions standard
• Instructions de test et runner préféré
• Décisions d'architecture spécifiques au projet
• Anti-patterns qu'on a déjà eu à corriger
• Variables d'environnement requises

À exclure :

• Ce que l'IA peut déduire en lisant le code
• Conventions standard du langage
• Documentation d'API (lien plutôt que copier)
• Ce qui change fréquemment
• Tutoriels ou longues explications

Test de chaque ligne : « Si je supprime cette ligne, est-ce que Claude fait des erreurs ? » Si non, supprime.

Tout ceci suppose que tu connais tes conventions. Sur un codebase ancien dont personne n'a jamais écrit les règles, le geste s'inverse : on les extrait du code avant de les rédiger, et le fichier gagne une catégorie qui n'existe pas ailleurs, celle du « on fait comme ça ici, ne le change pas au passage ». C'est le Module 4 §5.

---

5. Architecture en couches

Pour les monorepos ou projets larges, ne mets pas tout dans un seul fichier.

/CLAUDE.md                    → Conventions globales (toujours chargé)
/backend/CLAUDE.md            → Stack, patterns, anti-patterns backend
/frontend/CLAUDE.md           → Composants, state management, CSS
/infrastructure/CLAUDE.md     → Deployment, envs, Docker, K8s
/tests/CLAUDE.md              → Stratégie de test, fixtures, helpers

Chaque couche hérite du contexte parent et ajoute ses spécificités.

Le mécanisme de chargement mérite d'être compris précisément, parce que c'est lui qui rend l'architecture en couches rentable. Claude Code charge au démarrage le CLAUDE.md du répertoire où tu l'as lancé et tous ses parents jusqu'à la racine, concaténés du plus général au plus spécifique. En revanche, les CLAUDE.md des sous-répertoires ne sont pas chargés au démarrage : ils arrivent au moment où Claude lit un fichier dans le répertoire concerné. C'est exactement ce que tu veux, tu ne paies /frontend/CLAUDE.md que les jours où tu touches au frontend.

Conséquence à connaître : après un /compact, le CLAUDE.md racine est relu et réinjecté, mais pas ceux des sous-répertoires. Ils reviendront à la prochaine lecture d'un fichier de leur dossier.

Les règles scopées par chemin

Pour découper plus finement qu'un fichier par répertoire, Claude Code a .claude/rules/. Chaque fichier traite un sujet, et un champ paths en frontmatter décide quand il entre en contexte.

---
paths:
  - "src/api/**/*.ts"
---

# Conventions API

- Tout endpoint valide ses entrées avant traitement.
- Format d'erreur standard, jamais de stack trace renvoyée au client.

Une règle sans champ paths se charge à chaque session, comme le CLAUDE.md. Avec paths, elle ne coûte rien tant que Claude ne touche pas aux fichiers correspondants. C'est la vraie réponse au « mon CLAUDE.md est trop long » : plutôt que d'élaguer des règles utiles, sors-les du chargement permanent. Les rules Cursor (.mdc avec globs) suivent exactement le même principe, ce qui rend les deux configurations faciles à maintenir en parallèle.

---

6. Configuration par outil

Claude Code — CLAUDE.md + Skills + Hooks

.claude/
  skills/
    security-audit/
      SKILL.md          → Instructions spécialisées audit sécu
    test-generator/
      SKILL.md          → Générateur de tests opinionated
    migration-helper/
      SKILL.md          → Helper pour migrations DB
  agents/
    security-reviewer.md  → Subagent dédié à la revue sécurité
  settings.json           → Hooks configuration
CLAUDE.md                 → Contexte global projet

Cursor — .mdc Rules

.cursor/rules/
  global.mdc            → alwaysApply: true → conventions globales
  backend.mdc           → globs: src/api/**/*.ts
  frontend.mdc          → globs: src/components/**/*.tsx
  tests.mdc             → globs: **/*.spec.ts, **/*.test.ts
  security.mdc          → globs: src/auth/**

Structure d'un fichier .mdc :

---
description: Conventions pour les composants React
globs: src/components/**/*.tsx
alwaysApply: false
---

# Conventions React

- Functional components uniquement (pas de class components)
- Props typées avec TypeScript interface (pas de type alias)
- Voir @src/components/Button.tsx comme exemple de référence
- Typer les children explicitement (`children: ReactNode`) — éviter `React.FC`
- Gérer les états de loading/error explicitement dans chaque component

GitHub Copilot

.github/
  copilot-instructions.md    → Instructions globales équipe
  skills/                    → Skills partagés

---

7. AGENTS.md — le standard cross-tool

Fin 2025, plusieurs éditeurs (Anthropic, Cursor, OpenAI Codex CLI, Sourcegraph, JetBrains, OpenCode) ont aligné une convention commune : AGENTS.md, un fichier unique de contexte que tout agent IA sait lire. C'est l'équivalent du README.md pour les humains, mais à destination des agents.

Pourquoi

Chaque outil a son fichier (CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, GEMINI.md). Un dev qui jongle entre Cursor le matin et Claude Code l'après-midi maintient deux copies divergentes. AGENTS.md règle ce problème.

Mapping avec les fichiers historiques

Stratégie recommandée

1. AGENTS.md = tout ce qui est tool-agnostic : stack, conventions, anti-patterns, commandes.
2. CLAUDE.md / .cursor/rules = le pont vers AGENTS.md, plus uniquement ce qui est tool-specific : scoping fin Cursor, plan mode Claude Code.
3. Garder AGENTS.md court (< 200 lignes). Si plus, splitter par sous-répertoire.

Exemple AGENTS.md minimal

# Agent Instructions — projet-x

## Stack
- Backend : NestJS 10 + PostgreSQL 15 + TypeORM
- Frontend : Next.js 15 App Router + Tailwind 3

## Conventions
- Une feature = un module NestJS (`src/<feature>/`)
- DTOs avec class-validator obligatoires sur tous les endpoints
- Tests : Vitest. Unitaires colocalisés (`*.spec.ts`)

## Commandes
- `npm run dev` — démarre l'API et le front
- `npm test` — tests + coverage
- `npm run lint` — eslint + prettier

## Sécurité
IMPORTANT: jamais de raw SQL. Utiliser uniquement le QueryBuilder TypeORM.
IMPORTANT: tout endpoint qui lit des données utilisateur doit vérifier la propriété.

---

8. Memory : la mémoire persistante de l'agent

Au-delà du contexte de session, certains outils permettent de persister des souvenirs entre sessions : préférences utilisateur, décisions architecturales prises, patterns récurrents observés.

Options actuelles

La première ligne surprend souvent : dans Claude Code, la memory n'est pas quelque chose qu'on ajoute, c'est quelque chose qui tourne déjà. Le dossier contient un MEMORY.md qui sert d'index (seules ses ~200 premières lignes sont chargées à chaque session) et des fichiers par sujet, lus à la demande. Tout est en Markdown, lisible et éditable à la main. Elle est locale à ta machine et ne suit pas le dépôt.

Quand l'activer

• Pour les préférences personnelles longues à reconstituer (ex. : « je préfère les exports nommés, pas defaults »).
• Pour les décisions d'architecture validées par l'équipe (ex. : « on a choisi Postgres + Drizzle, pas Prisma, pour la performance »).
• Pour les patterns observés au fil du projet (ex. : « le service X a tendance à timeout sur les requêtes > 30s »).

Quand l'éviter

• Pas pour les secrets ou données sensibles — la memory peut être exfiltrée via prompt injection (voir Module 9).
• Pas comme substitut à CLAUDE.md — la memory est plus dynamique mais moins reviewable.
• Pas sans curation — une memory laissée se peupler toute seule finit pleine de bruit (memory poisoning).

---

9. Mesurer son budget de tokens

Un CLAUDE.md de 8 000 tokens lu à chaque tour de conversation coûte vite, surtout sans prompt caching (voir Module 1).

Mesurer

/context        → ce qui occupe le context window (et combien il en reste)
/usage          → consommation et coût de la session (/cost est un alias)
/memory         → liste et ouvre les fichiers mémoire, bascule l'auto memory

/context est le seul qui répond vraiment à « est-ce que mon fichier est chargé ? » : la section Memory files liste ce qui est réellement entré en contexte. Si ton CLAUDE.md n'y est pas, ce n'est pas la peine de discuter de son contenu.

Répartir son budget de contexte

Une fenêtre de contexte se budgète comme une enveloppe : ce que tu donnes à l'un, tu le retires à l'autre. Voici une répartition qui marche, sur une fenêtre de 200K tokens (le palier de base ; les proportions tiennent quelle que soit la taille, même à 1M) :

Si ton contexte permanent dépasse 10K tokens, tu écris trop dans CLAUDE.md. Diète obligatoire.

Audit rapide

# Estimation grossière du coût d'un fichier
wc -l CLAUDE.md            # au-delà de 200 lignes, la fidélité aux règles baisse
wc -c CLAUDE.md            # compte ~1 token pour 2 à 3 caractères en français

Le ratio caractères/token dépend de la génération du modèle (Module 1, §6) : ne fige pas ta règle de calcul, refais le compte après une montée de version. Et quand le fichier déborde, le premier réflexe n'est pas de couper des règles utiles, c'est de sortir les règles spécialisées vers .claude/rules/ avec un champ paths (§5).

---

10. Les risques du Context Engineering

Context Drift (dérive contextuelle)

Symptôme : la qualité se dégrade progressivement sans raison apparente.
Cause : les fichiers de contexte n'ont pas été mis à jour avec le code.
Fix : toute PR qui change les conventions → met à jour le fichier de contexte correspondant.

Context Poisoning (empoisonnement)

Symptôme : l'IA propage une erreur d'une réponse à toutes les suivantes.
Cause : une hallucination ou une erreur d'analyse a "contaminé" la session.
Fix : valide systématiquement les analyses de l'IA ; redémarre si nécessaire.

Context Distraction

Symptôme : l'IA ignore tes conventions pourtant présentes dans le contexte.
Cause : trop d'informations, tes règles importantes se noient dans le bruit.
Fix : ciblage explicite avec @fichier, préfixe IMPORTANT:, fichier plus court.

Lost-in-the-Middle

Symptôme : l'IA oublie des instructions données tôt dans la session.
Cause : les instructions sont noyées au milieu d'une longue conversation.
Fix : mets les règles critiques dans CLAUDE.md (début) et dans ton prompt final (fin).

---

11. ContextOps : gouvernance à l'échelle de l'équipe

Pour les équipes, le context engineering individuel ne suffit pas. Il faut ContextOps : la gouvernance du contexte à l'échelle organisationnelle.

Principes ContextOps

1. Le contexte est du code

• Tous les fichiers de contexte sont dans Git
• Reviewés comme n'importe quelle PR
• Chaque changement de convention = PR qui met à jour le fichier de contexte

2. Propriété explicite

• Chaque fichier de contexte a un owner nommé
• Owner = responsable de sa précision, pas forcément rédacteur

3. Revue cadencée

• Questions à poser par section : Est-ce encore exact ? Est-ce encore appliqué ? Que manque-t-il ?
• Fréquence recommandée : mensuel pour projets actifs, trimestriel pour projets stables

4. Template de PR

## Checklist
- [ ] Ce changement affecte-t-il des conventions de code documentées ?
- [ ] Si oui, le fichier de contexte correspondant a-t-il été mis à jour ?

5. Signal monitoring

• Tag les commentaires de code review liés à des violations de contexte
• Un cluster de commentaires sur le même pattern → convention manquante dans le contexte

Signaux de santé du contexte

Pas de cible chiffrée universelle ici (ce serait inventer un seuil), juste des signaux à surveiller sur ta baseline :