Lesson 2/17 8 min

Context engineering

Learn to configure the AI environment so it understands your project before the first prompt.

FR EN

Du prompt engineering au context engineering

En 2024, tout le monde parlait de prompt engineering : l'art de formuler la bonne question. En 2025-2026, le paradigme a changé. La vraie compétence n'est plus d'écrire UN bon prompt, mais de concevoir l'environnement complet que l'IA voit quand elle travaille sur votre projet.

C'est la différence entre donner une consigne à un stagiaire et lui préparer un bureau complet : documentation du projet, conventions de l'équipe, exemples de code, erreurs à éviter. Le stagiaire avec le bureau préparé est autonome. L'autre vous pose 50 questions.

Prompt engineering = formuler une bonne question. Context engineering = configurer tout l'environnement pour que même une question médiocre produise un bon résultat.

CLAUDE.md, .cursorrules, AGENTS.md

Les outils IA modernes lisent automatiquement des fichiers de configuration à chaque session. Ces fichiers sont votre levier principal :

  • CLAUDE.md : lu automatiquement par Claude Code. Décrit votre projet, vos conventions, vos commandes
  • .cursorrules : lu par Cursor. Même principe, format différent
  • .github/copilot-instructions.md : lu par GitHub Copilot
  • AGENTS.md : instructions spécifiques pour les agents autonomes (Claude Code, Codex)

Ce que ces fichiers doivent contenir :

Stack PHP 8, Bootstrap 5, MySQL 8 Conventions snake_case, PSR-12, commentaires FR Commandes npm run build, php artisan test Erreurs Ne jamais utiliser eval(), pas de SELECT * Architecture MVC, services dans /app/Services/

La hiérarchie de contexte

Le contexte n'est pas plat. Il est hiérarchique, du plus général au plus spécifique :

  1. Règles globales (~/.claude/CLAUDE.md) : préférences utilisateur valables partout : langue, style, conventions personnelles
  2. Règles projet (CLAUDE.md à la racine) : stack, architecture, commandes de build du projet
  3. Règles par dossier (src/api/CLAUDE.md) : conventions spécifiques à un module

Chaque niveau surcharge le précédent. Vos règles globales disent « commentaires en français », mais le CLAUDE.md d'un projet open-source peut dire « comments in English ».

La règle des 50 lignes

Un CLAUDE.md de 500 lignes est contre-productif. L'IA a une fenêtre de contexte limitée. Plus vous mettez de texte, plus chaque instruction perd en poids. C'est comme parler à quelqu'un dans une pièce bruyante : plus il y a de bruit, moins votre message passe.

Un bon CLAUDE.md tient en 50 lignes. Si le vôtre en fait 500, l'IA en ignore la moitié. Gardez uniquement ce qui change le comportement de l'IA.

Ce qui va dans le CLAUDE.md :

  • Décisions d'architecture que l'IA ne peut pas deviner
  • Conventions de code spécifiques à votre projet
  • Commandes de build, test, deploy
  • Erreurs connues à éviter

Ce qui ne va PAS dans le CLAUDE.md :

  • Tâches temporaires (« TODO : finir le formulaire »)
  • Documentation exhaustive (c'est le rôle du README)
  • Ce qui est déjà évident dans le code

La technique du mimicry

L'IA apprend par l'exemple. La technique la plus efficace pour obtenir du code cohérent avec votre codebase : lui montrer un exemple existant.

Au lieu de décrire vos conventions en 20 lignes, collez un fichier représentatif de votre projet. L'IA va reproduire le style : nommage, structure, patterns, même les commentaires.

# CLAUDE.md : Exemple concis

## Stack
PHP 8.2, Bootstrap 5, jQuery 3.7, MySQL 8

## Conventions
- snake_case pour variables et fonctions
- PSR-12, commentaires en français
- Toujours htmlspecialchars() sur les sorties

## Commandes
- `php -S localhost:8000 router.php`
- `npm run build` pour les assets

## Exemple de style (copier ce pattern)
Voir `app/Services/UserService.php` comme référence

From prompt engineering to context engineering

In 2024, everyone talked about prompt engineering: the art of asking the right question. In 2025-2026, the paradigm shifted. The real skill is no longer writing ONE good prompt, but designing the complete environment the AI sees when working on your project.

It is the difference between giving an intern a task and setting up their entire desk: project documentation, team conventions, code examples, mistakes to avoid. The intern with the prepared desk is autonomous. The other one asks you 50 questions.

Prompt engineering = asking a good question. Context engineering = configuring the entire environment so that even a mediocre question produces a good result.

CLAUDE.md, .cursorrules, AGENTS.md

Modern AI tools automatically read configuration files at each session. These files are your main lever:

  • CLAUDE.md — automatically read by Claude Code. Describes your project, conventions, commands
  • .cursorrules — read by Cursor. Same principle, different format
  • .github/copilot-instructions.md — read by GitHub Copilot
  • AGENTS.md — specific instructions for autonomous agents (Claude Code, Codex)

What these files should contain:

Stack PHP 8, Bootstrap 5, MySQL 8 Conventions snake_case, PSR-12, comments in FR Commands npm run build, php artisan test Pitfalls Never use eval(), no SELECT * Architecture MVC, services in /app/Services/

The context hierarchy

Context is not flat. It is hierarchical, from most general to most specific:

  1. Global rules (~/.claude/CLAUDE.md) — user preferences valid everywhere: language, style, personal conventions
  2. Project rules (CLAUDE.md at root) — stack, architecture, project build commands
  3. Per-directory rules (src/api/CLAUDE.md) — conventions specific to a module

Each level overrides the previous one. Your global rules say "comments in French", but an open-source project CLAUDE.md can say "comments in English".

The 50-line rule

A 500-line CLAUDE.md is counterproductive. AI has a limited context window. The more text you put in, the less weight each instruction carries. It is like talking to someone in a noisy room: the more noise, the less your message gets through.

A good CLAUDE.md fits in 50 lines. If yours has 500, the AI ignores half of it. Keep only what changes the AI behavior.

What goes in the CLAUDE.md:

  • Architecture decisions the AI cannot guess
  • Code conventions specific to your project
  • Build, test, deploy commands
  • Known pitfalls to avoid

What does NOT go in the CLAUDE.md:

  • Temporary tasks ("TODO: finish the form")
  • Exhaustive documentation (that is the README's job)
  • What is already obvious from the code

The mimicry technique

AI learns by example. The most effective technique to get code consistent with your codebase: show it an existing example.

Instead of describing your conventions in 20 lines, paste a representative file from your project. The AI will reproduce the style: naming, structure, patterns, even the comments.

# CLAUDE.md — Concise example

## Stack
PHP 8.2, Bootstrap 5, jQuery 3.7, MySQL 8

## Conventions
- snake_case for variables and functions
- PSR-12, comments in French
- Always htmlspecialchars() on output

## Commands
- `php -S localhost:8000 router.php`
- `npm run build` for assets

## Style example (copy this pattern)
See `app/Services/UserService.php` as reference
Avec l'IA

Demandez à Claude de générer un CLAUDE.md pour votre projet :

Génère un fichier CLAUDE.md pour mon projet. Voici la description : [décrivez votre projet, stack, conventions]. Le fichier doit tenir en 50 lignes maximum et contenir : la stack technique, les conventions de code, les commandes de build/test, les erreurs courantes à éviter, et un exemple de fichier représentatif du style du projet.
Exercice : Écrivez un CLAUDE.md

Projet : un site e-commerce en Node.js (Express + React) avec PostgreSQL. Écrivez un CLAUDE.md concis (max 50 lignes) qui contient la stack, les conventions, les commandes et au moins une erreur à éviter.

Ré-explique sans regarder

Sans relire la leçon : à un collègue qui démarre, explique pourquoi un CLAUDE.md de 50 lignes bat un CLAUDE.md de 500 lignes. Donne 2 choses qui y vont et 1 qui n'y va pas.

Une bonne explication dit : la fenêtre de contexte est limitée, donc chaque ligne en trop dilue le poids des instructions vraiment importantes (l'IA en ignore une partie). Y vont : décisions d'architecture non devinables, conventions de code du projet, commandes de build/test/deploy, erreurs connues à éviter. N'y vont pas : les TODO et tâches temporaires, la doc exhaustive (rôle du README), ce qui est déjà évident dans le code.
Accepter ou rejeter le CLAUDE.md de l'IA

Tu as demandé à l'IA de générer un CLAUDE.md pour un petit projet. Voici un extrait de ce qu'elle propose. Ton rôle : l'accepter tel quel ou le rejeter, et dire pourquoi.

# CLAUDE.md

## Présentation du projet
Ce projet est une application web. Le web est un ensemble de
technologies permettant d'afficher des pages dans un navigateur.
HTML structure le contenu, CSS le met en forme, et JavaScript
ajoute de l'interactivité. Notre application suit ce modèle...

## Qu'est-ce que le HTTP
HTTP est un protocole de la couche application qui repose sur TCP/IP.
Une requête comporte une méthode (GET, POST, PUT, DELETE)...

## TODO en cours
- [ ] Finir le formulaire de contact
- [ ] Corriger le bug du panier vu hier
Rejeter. Ce CLAUDE.md fait tout l'inverse de ce qu'il devrait : il explique ce que l'IA sait déjà (ce qu'est le web, comment marche HTTP) et noie les vraies instructions sous du remplissage. Pire, il met des TODO dedans, alors que les tâches temporaires n'y ont pas leur place et périment le fichier. Aucune stack précise, aucune convention, aucune commande de build : rien qui change le comportement de l'IA. Le bon réflexe : supprimer tout le cours général, garder 50 lignes utiles (stack, conventions, commandes, erreurs à éviter) et sortir les TODO vers un suivi de tâches.
Rappel libre

Sans remonter dans la leçon : en une phrase, qu'est-ce que le context engineering par rapport au prompt engineering, et cite un fichier que les outils IA lisent automatiquement à chaque session.

Le prompt engineering consiste à formuler une bonne question ponctuelle ; le context engineering configure tout l'environnement que l'IA voit (fichiers de règles, conventions, exemples) pour qu'elle parte juste, même avec une question médiocre. Fichiers lus automatiquement : CLAUDE.md (Claude Code), .cursorrules (Cursor), .github/copilot-instructions.md (Copilot) ou AGENTS.md.
Quelle est la différence entre prompt engineering et context engineering ?
Pourquoi garder un fichier de configuration court ?
Que doit contenir un CLAUDE.md ?
Next step

You can feed the AI the right context. So it will hand you code back, sometimes a lot of it. The next lesson, reading and understanding AI code, teaches you to never paste a block without reviewing it: spotting what it really does before accepting it.

Lesson 3: Reading and understanding AI code →
Besoin d'un développeur pour votre projet ?

Réponse sous 24h · Sans engagement