Donner du contexte à une IA de code — les leviers (prompt, skill, instructions, agents…)

1Glossaire

• Token — unité de découpage du texte ; la fenêtre de contexte en contient un nombre fini, et chaque token coûte (latence + argent).
• Progressive disclosure — ne charger une information dans le contexte que lorsqu'elle devient nécessaire, plutôt que tout garder en permanence.
• Knowledge graph — représentation du code (ou d'un savoir) en nœuds reliés par des relations explicites ; sert de plan interrogeable.
• Spec-driven development — écrire la spécification avant le code et en faire la source de vérité versionnée.
• Agent de code — assistant qui a accès au dépôt (lecture/écriture de fichiers, exécution de commandes), par opposition à un simple client de chat.

2Vue d'ensemble — externaliser le contexte

Chaque levier se définit par ce qu'il externalise. Les outils ne sont que des illustrations d'une catégorie.

flowchart TD
    P["LLM sans mémoire<br/>contexte → texte"] --> Q["Comment remettre<br/>le bon contexte ?"]
    Q --> M1["Prompt<br/>intention immédiate"]
    Q --> M2["Skill<br/>procédure réutilisable"]
    Q --> M3["Fichier d'instructions<br/>règles du projet"]
    Q --> M4["Hook<br/>garantie d'exécution"]
    Q --> M5["Graphe de code<br/>structure"]
    Q --> M6["Spec versionnée<br/>intention d'une feature"]
    Q --> M7["Subagent<br/>rôle isolé"]
    T["Tokens : budget transversal"] -.contraint.-> Q

3Le prompt — injecter l'intention immédiate

Ce qu'on injecte à la main, pour une requête donnée. Le levier de base, et l'essentiel du gain quand on débute. Bien prompter = être explicite sur l'objectif, le format attendu, les contraintes, et donner des exemples.

Tu es un relecteur de code.
Liste UNIQUEMENT les problèmes de correction (pas de style).
Pour chacun : ligne, problème, correctif. Format : tableau Markdown.

[code]

Limite : rien n'est mémorisé d'une requête à l'autre. Pour réutiliser, on passe à un skill ou un fichier d'instructions.

4Le skill — capitaliser une procédure réutilisable

Une procédure réutilisable, chargée à la demande quand sa description correspond à la tâche. Au lieu de re-prompter le même template à chaque fois, on le capitalise une fois. En pratique : un fichier (type SKILL.md) avec une description (qui décide du déclenchement) + le corps (la procédure).

---
name: bug-ticket
description: Déclenche pour rédiger un ticket de bug. Mots-clés : "ticket", "bug".
---
# Format de ticket
Impact → Comportement attendu → Étapes de repro → Données

Tout se joue sur la description : trop vague, il ne se déclenche pas ; trop large, il se déclenche à tort.

5Le fichier d'instructions — donner les règles du projet

Un fichier Markdown, versionné dans Git, qui dit à un agent de code comment travailler sur le projet : un « README pour agents » (setup, tests, conventions), distinct du README destiné aux humains. Il résout le problème de la page blanche au niveau projet : l'agent sait coder en général, mais ignore les conventions locales.

⚠️ À ne pas confondre avec « les agents ». Ce fichier ne crée aucun agent ; il dit à un agent comment se comporter.

Le même fichier, un nom par outil

Le contenu est identique (du Markdown) ; seul le nom change selon l'outil. Exemples :

Quand un outil lit plusieurs fichiers (cas de Copilot avec AGENTS.md + copilot-instructions.md), ils sont fusionnés, le plus spécifique l'emportant en cas de conflit. En environnement multi-outils, maintenir une seule source et la partager par symlink :

ln -s AGENTS.md CLAUDE.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md

Bonnes pratiques

• L'écrire à la main, court. Les fichiers générés par LLM dégradent souvent les performances (étude ETH Zurich) ; les fichiers humains aident, mais seulement concis.
• Pas de chemins de fichiers : ils bougent. Documenter les capacités et concepts (stables), pas la structure.
• Découper quand la racine dépasse ~150-200 lignes : un fichier par sous-projet (l'agent lit le plus proche).
• Le fichier est envoyé à chaque appel → minimal, et lier les détails vers d'autres fichiers.

# Mon service — instructions agent

## Stack
- Node.js / TypeScript, Express ; PostgreSQL ; build via pnpm

## Commandes
- Tests : `pnpm test`   // ✓ à lancer avant toute PR
- Lint  : `pnpm lint`

## Conventions
- Le client HTTP ne lève jamais d'exception : il renvoie un Result.  // ✓ concept stable
- Ne jamais modifier le dossier `vendor/`.

## Détails
- Conventions de test : voir docs/TESTING.md

6Skill vs fichier d'instructions — la confusion à lever

Les deux sont du Markdown qui « donne des instructions au modèle » — d'où la confusion permanente. Mais ils répondent à deux questions différentes :

• Fichier d'instructions → « Comment travailler sur CE projet ? » Toujours présent dans le contexte. Le décor permanent : conventions, commandes, règles. Passif.
• Skill → « Comment faire CETTE tâche ? » Chargé seulement quand sa description correspond. Un savoir-faire qu'on sort au besoin. Actif.

flowchart TD
    Q["Nouvelle requête"]
    subgraph ALWAYS["Toujours dans le contexte"]
        A["Fichier d'instructions<br/>règles du projet"]
    end
    subgraph LIB["Bibliothèque de skills (au repos, hors contexte)"]
        S1["skill : ticket"]
        S2["skill : doc PDF"]
        S3["skill : ..."]
    end
    Q --> A
    Q --> T{"La description<br/>d'un skill<br/>correspond ?"}
    T -- oui --> LOAD["Skill chargé<br/>le temps de la tâche"]
    T -- non --> SKIP["Aucun skill chargé"]
    S1 -.à la demande.-> LOAD

7Le hook — garantir une exécution

De l'automatisation déterministe autour d'une action (avant / après). Ce n'est pas du LLM : c'est du code qui s'exécute à coup sûr — lancer les tests après une modif, bloquer un commit si le lint échoue, journaliser une action. Exemples : hooks d'agent de code, git hooks.

Différence avec un skill : un skill peut se déclencher (le modèle décide), un hook s'exécute toujours. Dès qu'on veut une garantie, c'est un hook.

Suppose un agent avec accès au dépôt ; indisponible en simple client de chat.

8Externaliser un grand savoir — graphe de code & spec versionnée

Quand le savoir à donner est trop gros pour tenir dans le contexte, on l'externalise dans un artefact interrogeable plutôt que de le réinjecter à chaque fois.

Externaliser la structure du code → le graphe de code

Principe : transformer la codebase en graphe interrogeable (chaque fonction/fichier devient un nœud). L'IA interroge une représentation compacte au lieu de relire tout le code, et ne régénère que ce qui a changé — ce qui réduit le « token tax » et rend explicites les dépendances entre modules.

Exemple d'outil : Graphify — /graphify produit un graphe navigable, polyglotte, en local.

Externaliser l'intention d'une feature → la spec versionnée

Principe (spec-driven development) : écrire la spécification avant le code et en faire la source de vérité versionnée. On s'accorde sur quoi construire avant qu'une ligne soit produite. Bénéfice : sans spec écrite, impossible de comparer ce que l'IA produit à une attente — la spec devient l'artefact de revue.

Exemple d'outil : OpenSpec — déroule un cycle en trois temps :

flowchart LR
    A["propose<br/>specs + plan de tâches"] --> B["apply<br/>implémente, coche la checklist"]
    B --> C["archive<br/>rejoint les specs vivantes"]

Ces deux leviers donnent leur plein effet avec un agent qui a accès au dépôt.

9L'agent / subagent — déléguer un rôle isolé

Un agent autonome est un processus avec un rôle et un prompt propres, qui enchaîne des actions vers un objectif. Un subagent est un agent spécialisé, invoqué par l'agent principal, avec son propre contexte isolé. Intérêt principal : isoler le contexte. Un subagent « revue de code » ou « rédaction de tests » fait son travail dans sa fenêtre et ne renvoie que sa conclusion, sans polluer le contexte principal — c'est autant un outil d'organisation que de gestion des tokens.

Exemple : un subagent défini par un fichier (rôle + outils autorisés + prompt système).

---
name: code-reviewer
description: Relit un diff et signale les problèmes de correction.
tools: [read, grep]
---
Tu relis du code. Pour chaque problème : fichier, ligne, raison, correctif.
Ne signale que des problèmes de correction, pas de style.

À introduire une fois le socle en place (fichier d'instructions + bons prompts), pas avant.

10Tableau de synthèse

Sources

• AGENTS.md — spec et gouvernance (Agentic AI Foundation / Linux Foundation)
• GitHub Copilot — custom instructions — fichier .github/copilot-instructions.md
• Graphify — exemple de graphe de code (PyPI : graphifyy)
• OpenSpec — exemple de framework spec-driven (propose / apply / archive)
• MCP — Model Context Protocol (Anthropic), sous la même fondation qu'AGENTS.md