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 (2024) mesure une forte hausse des blocs copiés-collés, qui dépassent désormais le code déplacé/refactorisé

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 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
- 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 = 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

/context        → ce qui occupe le context window (et combien il en reste)
/cost           → coût de la session courante
/memory         → édite les fichiers mémoire chargés

La règle 80/20 du contexte

Exemple sur une fenêtre de 200K tokens (le palier de base ; le principe tient 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 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

Signaux de santé du contexte

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