Les deux canaux de livraison¶

Un agent de code a besoin de deux choses très différentes, et les confondre est l'erreur classique de ce genre de système.

	Pack statique	Recherche à la demande
Contenu	Les ~100 faits qui s'appliquent toujours	Les milliers de détails qui s'appliquent parfois
Livraison	Fichiers dans le dépôt, lus à chaque session	Appel d'outil MCP
Coût	Payé une fois par session	Payé seulement quand utile
Exemple	« Les handlers HTTP vont dans `internal/api/`, jamais dans `pkg/` »	« Quelle est la procédure exacte de rollback du service paiement ? »

Le pack statique fait l'essentiel du gain : il empêche l'agent de se tromper par défaut. La recherche couvre la longue traîne. Les deux sortent de la même base de faits, ce qui garantit qu'ils ne divergent jamais.

Pourquoi pas uniquement du statique¶

Parce que la place est limitée et que la dilution est réelle. Au-delà de quelques centaines de lignes, un fichier d'instructions se fait lire mais plus appliquer. Le budget par défaut est de 500 lignes, réglable par client.

Ce qui n'entre pas dans le pack n'est pas perdu : il reste interrogeable par le MCP. Le pack le dit explicitement à l'agent, dans une section finale qui l'invite à chercher plutôt qu'à supposer.

Pourquoi pas uniquement du MCP¶

Parce qu'un agent ne cherche que s'il sait qu'il ignore quelque chose. Une règle de nommage de fichiers ou une interdiction de logger un numéro de carte ne déclenchent aucune question : l'agent écrit, en toute confiance, quelque chose de non conforme.

Ces règles-là doivent être présentes avant qu'il commence.

Ce que produit la compilation¶

flowchart TD
    F[Base de faits] --> S{Sélection<br/>par priorité}
    S -->|dans le budget| P[Pack statique]
    S -->|au-delà| M[Accessible par MCP]
    S -->|runbooks détaillés| K[Skills]
    P --> C[CLAUDE.md]
    P --> A[AGENTS.md]
    P --> G[copilot-instructions.md]
    P --> I[".github/instructions/*<br/>par zone de chemin"]
    K --> C

Claude Code¶

CLAUDE.md — le pack, chargé à chaque session.
.claude/skills/<nom>/SKILL.md — un Skill par procédure détaillée. Un runbook n'a de valeur que déplié, mais on n'en a besoin qu'au moment de l'exécuter : c'est exactement le cas d'usage du chargement à la demande.

OpenCode et tout agent lisant `AGENTS.md`¶

AGENTS.md — le pack, procédures dépliées à l'intérieur. Sans mécanisme de chargement conditionnel, les replier ailleurs les rendrait inaccessibles.

GitHub Copilot¶

.github/copilot-instructions.md — les règles seules, sans les explications : Copilot dilue vite.
.github/instructions/<zone>.instructions.md — les conventions scopées, regroupées par zone de code et non par combinaison exacte de globs. Sans ce regroupement, chaque fait produirait son propre fichier, ce qui annulerait tout l'intérêt du filtrage par chemin.

Régénérer, jamais éditer¶

Les fichiers produits portent un en-tête qui le dit. Les modifier à la main fonctionne jusqu'au prochain aim sync, qui les écrase.

Quand une règle est fausse, la bonne réaction est de remonter à sa provenance et de corriger la source, ou de rejeter le fait avec aim review. C'est plus lent la première fois, et c'est la seule façon que la correction survive.