Context Engineering

---

1. Du Prompt Engineering au Context Engineering

La distinction fondamentale

"Context engineering is curating what the model sees so that you get a better result."
— Birgitta Böckeler, Distinguished Engineer, Thoughtworks (Février 2026)

Le problème que ça résout

91% des équipes engineering ont adopté au moins un outil IA. Pourtant, au bout de 3 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
• La duplication de code a augmenté de 4x (GitClear, 2024)

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 commence à zéro. L'IA fait ses propres choix — cohérents avec son entraînement, incohérents 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

Problème : les instructions disparaissent entre les sessions.

Solution : fichiers de contexte persistants, lus automatiquement à chaque session.

Outils :

• 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

Problème : tout inclure noie l'attention du modèle.

Solution : chargement conditionnel, scoping par fichier/répertoire.

Outils :

• 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

Problème : les longues sessions accumulent du bruit — historique, tentatives échouées, fichiers obsolètes.

Solution : résumés intermédiaires, compaction contrôlée.

Outils :

• /compact [instructions] dans Claude Code
• /clear entre tâches non liées
• Résumés de session sauvegardés (/save session-name)
• Prompts de récapitulation en début de nouvelle session

---

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

Problème : mélanger les tâches crée des interférences.

Solution : sessions séparées, agents spécialisés, skills encapsulés.

Outils :

• 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 des sessions Claude parallèles

---

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.

---

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.

Claude Code charge automatiquement le CLAUDE.md du répertoire dans lequel il travaille + tous les parents jusqu'à la racine.

---

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
- Utiliser React.FC<Props> pour les components avec children
- 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 = uniquement ce qui est tool-specific : permissions Claude Code, scoping fin Cursor, etc.
3. Garder AGENTS.md court (< 200 lignes). Si plus, splitter par sous-répertoire (hérité automatiquement).

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

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 8).
• 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

/status         → tokens consommés vs context window
/cost           → coût session courant
/memory         → tokens utilisés par memory tool

La règle 80/20 du contexte

Sur les 200K tokens de Claude :

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

Audit rapide

# Estimation du coût d'un fichier
wc -c CLAUDE.md            # ~ 1 token / 3 caractères en français
# 30 000 caractères ≈ 10 000 tokens — trop

---

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

Métriques de santé du contexte