Parcours 2 : Context engineering

Étape 1

Du prompt au contexte

Choisir ce que le modèle voit, au lieu de tout lui montrer.

Le context engineering est l'ensemble des moyens qui sélectionnent et entretiennent ce qui se trouve dans le contexte du modèle pendant le travail : consignes, outils, données externes, historique. Le prompt n'en est qu'une partie. L'objectif tient en une phrase : le plus petit ensemble d'informations très utiles qui produit le résultat voulu.

Dans une session d'agent de code, ce qui entre dans la fenêtre vient de six endroits : les consignes du système, vos fichiers d'instructions, les définitions des outils (y compris ceux des serveurs MCP), la liste des skills, l'historique, et les résultats des outils. Quatre techniques gardent le contexte sain, et chacune a son pendant dans l'outil :

Revoyez l'animation de la fenêtre dans le parcours précédent et repérez les deux postes que vous contrôlez le mieux.

Étape 2

Piloter la session

Une session est un outil qu'on conduit : l'effacer, la résumer, la rejouer.

Tout ce que vous venez de voir se joue pendant une session. Les bonnes pratiques de Claude Code tiennent en une contrainte : la fenêtre se remplit vite et la précision baisse quand elle se remplit. Presque chaque commande de session sert donc à garder le contexte utile.

Le flux recommandé tient en quatre temps : explorer, planifier, implémenter, commiter. Si vous pouvez décrire la modification en une phrase, sautez la planification.

Trois mauvaises habitudes reviennent tout le temps :

• La session fourre-tout : une tâche, puis une question sans rapport, puis on revient à la première. Le contexte est plein de bruit. Remède : /clear entre deux sujets.
• Corriger en boucle : l'agent se trompe, on corrige, il se trompe encore. Le contexte est pollué par les essais ratés. Remède : après deux corrections, /clear et un prompt meilleur qui reprend ce qu'on a appris.
• L'exploration sans limite : « investigue » sans cadrer fait lire des centaines de fichiers. Remède : cadrer, ou déléguer à un sous-agent (étape 6).

Exercice : vous avez corrigé trois fois la même erreur et l'agent recommence. Que faites-vous ?

Étape 3

Les fichiers d'instructions

CLAUDE.md et AGENTS.md : du contexte persistant, pas une contrainte.

Chaque session démarre avec une fenêtre vide. Deux mécanismes transmettent la connaissance d'une session à l'autre : les fichiers d'instructions que vous écrivez (CLAUDE.md, ou AGENTS.md que Claude Code peut lire à la place), et la mémoire automatique que Claude écrit lui-même d'après vos corrections.

Deux faits à retenir. D'abord, ces fichiers sont du contexte : l'agent les lit et peut s'en écarter. Pour interdire une action quelle que soit sa décision, il faut un hook (parcours suivant). Ensuite, plus une instruction est précise et courte, plus elle est suivie de manière constante.

Si CLAUDE.md et AGENTS.md existent tous les deux, Claude Code lit CLAUDE.md ; pour partager un seul fichier avec d'autres outils, CLAUDE.md importe l'autre avec une ligne @AGENTS.md. C'est ce que fait ce projet : AGENTS.md porte les consignes, CLAUDE.md n'est qu'un pointeur. Des consignes qui ne concernent qu'une partie du code se rangent à part : c'est l'étape suivante, les règles.

Lequel de ces deux fichiers est le plus utile à un agent qui arrive sur le projet ?

# AGENTS.md

Tu es un expert senior. Écris du code propre, performant et maintenable.
Fais attention à la sécurité. Teste bien ton code. Sois prudent.

# AGENTS.md

Application web (Next.js, pnpm). Répondre en français.

## Vérifier avant de dire « fait »
- `npx tsc --noEmit` puis `pnpm test` : citer le résultat.
- `pnpm lint` signale à tort les fichiers générés : lancer `pnpm lint src`.

## Pièges
- Le serveur de développement écoute sur le port 4000, fixé dans `.env.example`.
- Après un changement de schéma : `pnpm db:migrate:create <nom>` puis `pnpm db:migrate`.

## Interdit
- Pas de commit sur main : une branche par sujet, une PR par branche.

Exercice : écrivez dix lignes d'AGENTS.md pour un projet que vous connaissez, avec uniquement des commandes, des pièges et des interdits.

Étape 4

Les règles

Des instructions rangées par sujet, chargées au bon moment.

Quand AGENTS.md grossit, tout y est lu à chaque session, même ce qui ne concerne qu'une partie du code. Les règles répondent à ce problème : un fichier Markdown par sujet dans .claude/rules/ (tests.md, api.md, securite.md), découverts récursivement. Elles sont du contexte, comme les fichiers d'instructions : l'agent les lit et peut s'en écarter.

Deux comportements, selon l'en-tête du fichier :

---
paths:
  - "src/**/*.tsx"
---

# Composants React

- Tester avec Testing Library, jamais avec Enzyme.
- Un composant par fichier, nommé comme le fichier.
- Pas de style en ligne : les classes du design system.

Le champ paths accepte des motifs comme src/**/*.{ts,tsx} ; c'est le seul champ que Claude Code lit dans une règle. Vos règles personnelles vont dans ~/.claude/rules/ et s'appliquent à tous vos projets ; elles sont chargées avant celles du projet, et si les deux se contredisent, l'agent peut suivre l'une ou l'autre : gardez-les cohérentes.

Où ranger quoi ? Lisez les cinq cas puis pronostiquez :

À ne pas confondre : les « règles de permission » (deny, ask, allow) de l'étape 9 sont appliquées par l'outil, dans les réglages. Les règles de cette étape sont des instructions lues par le modèle.

Exercice : prenez votre AGENTS.md et repérez deux paragraphes qui ne concernent qu'un type de fichier. Déplacez-les dans une règle avec paths.

Étape 5

Les skills

Une procédure chargée seulement quand elle sert.

Une skill est un dossier avec un fichier SKILL.md : un en-tête qui dit quand l'appeler, un corps qui dit comment. Claude l'invoque quand la description correspond à la conversation, ou vous la tapez avec /nom.

---
name: release-notes
description: Rédiger les notes de version à partir des PR fusionnées. À utiliser quand l'utilisateur demande « les notes de version », « le changelog » ou « qu'est-ce qui part en prod ».
---

# Notes de version

1. Lister les PR fusionnées depuis la dernière étiquette :
   `gh pr list --state merged --search "merged:>=<date>"`.
2. Les classer : nouveautés, corrections, technique.
3. Une ligne par PR, au présent, sans jargon interne.
4. Suivre le gabarit de `modele.md` (dans ce dossier).

Le point clé est le chargement progressif : seule la description reste toujours dans le contexte ; le corps n'est lu qu'à l'appel, et les fichiers annexes seulement au besoin. Une skill volumineuse ne coûte donc rien tant qu'on ne s'en sert pas ; une fois appelée, son corps reste dans la conversation jusqu'à la fin de la session.

Champs utiles : disable-model-invocation: true pour ne la lancer que par commande (le modèle ne la déclenche jamais seul), allowed-tools pour pré-autoriser des outils pendant son exécution.

Exercice : transformez une tâche que vous répétez (relance, compte rendu, revue) en skill. Écrivez d'abord la description : elle doit dire quand, jamais le déroulé.

Étape 6

Les agents

Un second collaborateur avec sa propre fenêtre de contexte.

Un sous-agent est un assistant spécialisé qui travaille dans une fenêtre de contexte isolée, avec ses propres consignes, ses propres outils et éventuellement un autre modèle. Il fait la tâche et ne renvoie qu'un résumé : la lecture de trente fichiers ne pollue pas la conversation principale. C'est la technique « déléguer à un contexte propre » du début du parcours.

Dans un schéma orchestrateur, l'agent principal ne lit pas tout : il distribue à chaque sous-agent le minimum dont il a besoin (la tâche, les critères, les fichiers utiles), puis ne reçoit que des résumés. Comparez les deux modes :

---
name: security-reviewer
description: Relit un diff sous l'angle de la sécurité (entrées non validées, secrets, droits). À utiliser avant une PR qui touche l'authentification, les paiements ou les données personnelles.
tools: Read, Grep, Glob
model: sonnet
---

Tu relis un changement sans le modifier. Pour chaque constat : le fichier et la
ligne, ce qui peut arriver, comment le reproduire, la gravité. Si rien ne pose
problème, dis-le en une phrase : n'invente pas de constat.

Le fichier vit dans .claude/agents/ (projet) ou ~/.claude/agents/ (personnel). Les champs obligatoires sont name et description ; tools restreint ses outils (ici, lecture seule) et hérite de tout si on l'omet. On l'invoque en le nommant (« utilise security-reviewer »), par mention (@agent-security-reviewer relis mon diff, ou @ puis le choisir dans la liste), ou pour toute la session.

Limites à connaître : un sous-agent n'a pas votre conversation et chaque nouvel appel démarre sans mémoire des appels précédents, sauf si l'on demande explicitement de reprendre le même sous-agent, il consomme du quota comme la session principale, et le nombre d'agents simultanés et la profondeur d'imbrication sont bornés.

Exercice : écrivez un agent « relecteur » en lecture seule pour votre projet. Quelles sont les trois informations que vous lui donnez avec sa tâche, puisqu'il n'a pas votre conversation ?

Étape 7

MCP : brancher des outils

Un protocole commun pour donner à l'agent l'accès à des données et à des services.

Le Model Context Protocol (MCP) permet à l'agent d'utiliser des serveurs externes : base de données, tracker, documentation, navigateur.

Une API, pour un agent

Vous connaissez déjà le principe : un service expose des opérations, un client les appelle. MCP est ce contrat, pensé pour un agent plutôt que pour votre code. Les différences tiennent à une idée : c'est le modèle qui découvre les opérations et décide de les appeler pendant la session, au lieu d'un développeur qui les a codées à l'avance.

Un serveur MCP expose trois choses, chacune déclenchée par quelqu'un de différent :

GET /orders/42 HTTP/1.1
Authorization: Bearer <jeton>

200 OK
{ "id": 42, "status": "shipped" }

-> {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

<- {"jsonrpc": "2.0", "id": 1, "result": {"tools": [{
     "name": "get_order",
     "description": "Retourne une commande à partir de son numéro.",
     "inputSchema": {"type": "object",
       "properties": {"id": {"type": "integer"}}, "required": ["id"]}
   }]}}

-> {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "get_order", "arguments": {"id": 42}}}

<- {"jsonrpc": "2.0", "id": 2, "result": {
     "content": [{"type": "text", "text": "Commande 42 : expédiée"}],
     "isError": false}}

Deux conséquences pour vous. Leurs outils coûtent du contexte, mais peu : par défaut, la recherche d'outils ne charge au démarrage que les noms, et les définitions complètes seulement au moment du besoin. Et ils peuvent agir (lire des données, écrire, supprimer) : on n'installe donc que des serveurs de confiance, avec l'accès minimal.

Un fichier .mcp.json de projet :

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CONTEXT7_API_KEY}"
      }
    },
    "base": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "${DB_URL}"
      }
    }
  }
}

Remarquez les ${...} : les secrets viennent de variables d'environnement, jamais du fichier versionné. Un serveur de portée projet demande une approbation avant son premier usage.

$ claude mcp add --transport http <nom> <url>

$ claude mcp list

$ claude mcp remove <nom>

Dans les règles de permission, un outil MCP se nomme mcp__<serveur>__<outil> (par exemple mcp__notion__* ou simplement mcp__notion pour tous les outils d'un serveur ; une règle mcp__ avec des parenthèses est ignorée).

Exercice : écrivez le .mcp.json d'un serveur en lecture seule sur une base de test. Où va le mot de passe ?

Étape 8

Context7, Playwright et Graphify

Trois outils qui attaquent trois défauts d'un agent : la doc à jour, un navigateur pour vérifier, une carte du dépôt.

Parmi tous les serveurs MCP possibles, deux changent le quotidien d'un développeur web, parce qu'ils attaquent deux défauts classiques d'un agent : il code avec des API périmées, et il affirme que l'interface marche sans l'avoir vue.

Context7 : la documentation à jour, à la version

Un modèle a été entraîné jusqu'à une date. Une bibliothèque a changé depuis : il écrit alors une API qui n'existe plus, avec assurance (c'est une hallucination, parcours Culture). Context7 est un service qui fournit à l'agent la documentation et des exemples de code de la version voulue. Il expose deux outils : resolve-library-id (trouver l'identifiant d'une bibliothèque à partir de son nom) et query-docs (interroger sa documentation). On l'appelle en ajoutant « use context7 » à la demande, ou en nommant l'identifiant (/supabase/supabase) pour sauter la recherche. Une clé d'API gratuite relève les limites d'usage.

Le plus utile : l'écrire une fois dans AGENTS.md (« pour toute API de bibliothèque, consulter Context7 avant d'écrire du code »), pour ne plus avoir à le demander. Limite à garder en tête : ces documentations sont alimentées par la communauté et ne sont pas garanties exactes ; c'est une source à citer et à vérifier, qui reste du texte non fiable (voir l'injection de prompt).

Playwright : un navigateur que l'agent pilote

Le serveur MCP Playwright donne à l'agent un vrai navigateur : ouvrir une page, cliquer, remplir un formulaire, lire la console et les requêtes réseau, prendre une capture. Il travaille surtout à partir d'instantanés d'accessibilité (l'arbre de la page, en texte), pas de pixels : l'agent n'a pas besoin de « voir » l'image pour agir. La capture sert à montrer le résultat, à vous comme à un agent vérificateur. Outils principaux : browser_navigate, browser_snapshot, browser_click, browser_type, browser_take_screenshot, browser_console_messages, browser_network_requests.

Un fichier .mcp.json avec les deux, plus un second navigateur configuré en mobile (le serveur se lance avec --viewport-size ou --device) :

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CONTEXT7_API_KEY}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--viewport-size",
        "1280x720",
        "--output-dir",
        "./captures"
      ]
    },
    "playwright-mobile": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--device",
        "iPhone 15",
        "--output-dir",
        "./captures"
      ]
    }
  }
}

Variante sans serveur MCP : Context7 propose aussi un mode « CLI + skill » (npx ctx7 setup --claude), et Claude Code peut piloter votre navigateur Chrome via son extension. Le principe reste le même : donner à l'agent un moyen de vérifier.

Voici ce que ça donne en pratique. Demandez, avec ces deux serveurs branchés :

Ajoute la pagination à la liste des commandes avec TanStack Query. use context7

Puis ouvre http://localhost:3100/commandes, prends une capture à 1280 px et une en mobile, et liste les erreurs de la console.

L'agent lit la documentation de la bonne version, écrit le code, ouvre la page, capture les deux tailles et rapporte les erreurs. Vous relisez des preuves.

Exercice : branchez les deux serveurs sur un projet jetable, demandez une petite évolution d'interface, et obtenez deux captures (bureau et mobile) sans aucune erreur de console.

Graphify : une carte du dépôt, plutôt que relire les fichiers

Troisième défaut : sur un gros dépôt, l'agent cherche à l'aveugle. Graphify n'est pas un serveur MCP : c'est un outil en ligne de commande, livré avec une skill et un hook pour Claude Code. Pour comprendre « qui appelle quoi », il enchaîne les recherches de texte et relit des fichiers entiers, et chaque lecture remplit la fenêtre de contexte (étape 1). Graphify (open source) construit d'abord une carte du dépôt : un graphe de connaissances où les fonctions, les classes, les fichiers et les concepts sont des nœuds, reliés par leurs appels, leurs imports et leurs références. L'agent interroge la carte et n'ouvre ensuite que les fichiers utiles.

• Le code est analysé sur votre machine, par l'analyseur syntaxique tree-sitter : sans modèle, sans clé, sans que rien ne sorte de la machine.
• La documentation, les PDF et les images passent par un modèle (celui de l'agent, ou une clé d'API) pour en extraire les concepts : c'est payant, et leur contenu sort de la machine.
• Chaque lien porte son origine : EXTRACTED s'il est écrit dans le code, INFERRED s'il est déduit par Graphify. Un lien déduit est une hypothèse à vérifier dans le fichier.
• Le résultat va dans graphify-out/ : graph.json (le graphe), GRAPH_REPORT.md (les concepts clés et des questions suggérées) et graph.html, une carte interactive à ouvrir dans un navigateur.

Installation, une fois par machine (le paquet s'appelle graphifyy sur PyPI, avec deux « y » ; les autres paquets graphify* ne sont pas du même projet), puis la skill /graphify pour Claude Code seulement :

$ uv tool install graphifyy

$ graphify install --platform claude

Dans une session ouverte sur le projet, /graphify . construit la carte. Ensuite, en ligne de commande ou par l'agent :

graphify query "qu'est-ce qui relie l'authentification à la base ?"
graphify path "LoginForm" "users"      # le plus court chemin entre deux nœuds
graphify explain "useSession"          # un nœud et ses voisins, en clair
graphify update .                      # refaire la carte du code, sans modèle

Pour Claude Code, l'installation ajoute aussi un hook qui rappelle à l'agent de consulter la carte avant de chercher ou de lire des fichiers un par un (parcours Harness : un hook est exécuté par l'outil, pas par le modèle).

Exercice : construisez la carte d'un projet que vous connaissez, ouvrez graph.html, puis posez la même question (« d'où vient le titre de la page d'accueil ? ») à l'agent avec et sans la carte. Comparez les fichiers qu'il a lus.

Étape 9

Permissions et réglages

Ce que l'agent peut faire, décidé hors de son texte.

Contrairement aux fichiers d'instructions, les règles de permission sont appliquées par l'outil, pas suggérées au modèle. Elles vivent dans les fichiers de réglages : .claude/settings.json (projet, partagé), .claude/settings.local.json (vos choix locaux, à garder hors du dépôt), ~/.claude/settings.json (personnel), et des réglages d'organisation qui priment.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(secrets/**)",
      "Bash(rm -rf *)",
      "mcp__playwright__browser_run_code_unsafe"
    ]
  }
}

Trois listes, évaluées dans cet ordre : deny, puis ask, puis allow. La première qui correspond décide, quelle que soit la précision des règles. Pronostiquez :

Les modes règlent le niveau d'autonomie : default (le mode « Manuel » dans l'interface : demande à la première utilisation), acceptEdits (accepte les modifications de fichiers), plan (explore sans modifier), auto (un classifieur vérifie les actions), dontAsk (refuse ce qui demanderait), bypassPermissions (aucune demande : réservé aux environnements isolés).

Limite à connaître : une règle sur une commande shell lit le texte que l'agent écrit. Elle couvre la forme habituelle d'un appel, pas toutes ses variantes : ce n'est pas une frontière de sécurité autour d'un programme. Pour bloquer la lecture d'un fichier par les outils de fichiers, on écrit une règle Read sur son chemin.

Ce que les règles ne savent pas dire (« pas de commit sur main », « une PR doit être liée à une issue ») se règle avec des hooks. Un hook est un script que l'outil lance à un moment précis du travail (avant un outil, après une modification, à la fin d'une réponse). Il reçoit du JSON sur son entrée, et s'il termine avec le code 2, l'action est bloquée et son message d'erreur revient à l'agent comme retour. C'est l'objet du parcours Harness, où l'on en écrit un.

Étape 10

Choisir le bon mécanisme

Chaque besoin a son bon support : la synthèse du parcours.

Vous connaissez maintenant les mécanismes, qui ont chacun leur fiche, avec un fichier d'exemple, sur la page Les briques. Le piège classique est d'utiliser le mauvais : tout mettre dans AGENTS.md, ou espérer qu'une instruction tienne lieu d'interdiction. Un critère simple : à quelle fréquence l'agent en a-t-il besoin, et est-ce une suggestion ou une garantie ?

Cas pratique : « les composants React se testent avec Testing Library, jamais avec Enzyme ». Où l'écrire ? Une règle avec paths: src/**/*.tsx, parce que cela ne concerne que ces fichiers. Et « ne jamais supprimer une migration » ? Une permission deny ne lit que le texte de la commande : rm serait bloqué, mais git rm, mv ou un chemin écrit autrement lui échapperaient. Un hook, lui, peut regarder quels fichiers la commande vise et refuser si l'un d'eux est dans migrations/ : il reconnaît bien plus de formes de commande, sans être infaillible. C'est une décision qui dépend du contexte.

Pour la gestion d'équipe, deux compléments existent : les plugins (un paquet installable qui regroupe skills, hooks, sous-agents et serveurs MCP) et les réglages gérés par l'organisation. Le parcours Harness montre comment l'ensemble s'assemble.