Optimiser son AGENTS.md avec les principes d'Andrej Karpathy

187 lignes. C'était la taille de mon fichier AGENTS.md. Un monstre qui mélangeait règles comportementales, topologie réseau, commandes SSH, credentials dynamiques et procédures de sauvegarde. Pire : il était chargé en intégralité à chaque démarrage de session, réduisant la fenêtre de contexte disponible pour le code.

Andrej Karpathy, dans ses observations sur les défauts des LLM en programmation, a posé un diagnostic simple : "Les modèles font des hypothèses silencieuses et foncent sans vérifier. Ils ne gèrent pas leur confusion, ne demandent pas de clarifications, ne présentent pas de compromis, ne contredisent pas quand ils devraient."

Ce diagnostic s'applique aussi bien au code généré qu'au prompt système qui guide l'agent. J'ai décidé d'auditer mon propre fichier sous cet angle. Voici ce que j'ai découvert, corrigé, et pourquoi je pense que tout développeur utilisant un agent IA devrait faire de même.

Le déclencheur : un bug de traduction

Le problème est apparu lors d'une session de maintenance sur ExploDev. Mon agent devait réparer un pipeline de traduction EN→FR pour un brief IA quotidien. Au lieu de rester sur une solution simple, il a oscillé entre trois approches (Ollama local, Workers AI Cloudflare, retour à Ollama) sans jamais poser la question fondamentale : "Quelle latence est acceptable pour ce use-case ?"

Résultat : un déploiement bancal, des allers-retours inutiles, et une frustration de mon côté. Karpathy aurait appelé ça un classique "wrong assumption without push back".

L'audit : les 5 angles morts de mon AGENTS.md

Angle mort 1 — Le fichier est trop gros (Context Rot)

187 lignes dans le prompt système, plus les skills qui se chargent en parallèle. Des recherches récentes montrent qu'après ~113k tokens de contexte, la précision d'un LLM chute de 30%. Chaque ligne de mon fichier "mangeait" de l'espace disponible pour analyser le code.

Pire : le fichier mélangeait deux choses radicalement différentes :

• Des règles comportementales (comment l'agent doit penser et agir)
• Des données référentielles (IPs, commandes SSH, procédures RAG)

Les secondes n'ont rien à faire dans un prompt système. Elles devraient être dans une base de connaissances (RAG) et chargées à la demande.

Angle mort 2 — Pas de "Push Back" explicite

Mon fichier disait : "Dire 'je ne sais pas' est correct." Mais il ne disait jamais : "Si la demande contredit l'architecture ou une décision passée, conteste-la."

Conséquence concrète : quand j'ai demandé "remets Ollama en place peu importe le modèle", l'agent a obéi sans me prévenir que le modèle choisi (gemma4:12b, 44 secondes par réponse) allait dépasser le timeout du Worker Cloudflare. Il aurait dû dire "Non, ce modèle est trop lent pour ce use-case. Voici pourquoi, et voici l'alternative."

Angle mort 3 — Absence de critères de succès vérifiables

Les règles disaient : "Tester le composant isolément + intégration end-to-end." Mais il n'y avait aucun format standard pour dire ce qu'est une tâche terminée. "Déployer et tester" est vague. "Déployer → curl retourne 200 → logs sans erreur → traduction retourne texte français + noms propres préservés" est vérifiable.

Angle mort 4 — Le biais du "budget temps"

Les LLM utilisent des excuses de temps pour justifier des raccourcis : "On va gagner du temps en utilisant Workers AI" ou "C'est plus rapide comme ça." Sauf qu'une IA n'a pas de contrainte temps réel. Un refactor propre qui prend 10 minutes de génération vaut mieux qu'un hack qui en prend 2 mais casse tout dans 3 jours.

Angle mort 5 — Redondance Skills / Prompt système

J'avais des skills inactifs (security-specialist, code-architect-auditor) qui contenaient des règles de qualité. Mais mon AGENTS.md répétait certaines de ces règles (sauvegarde, scope, réseau). Résultat : bruit cognitif et risque de conflit si un skill dit une chose et AGENTS.md dit l'inverse.

La solution : scinder et appliquer les 6 principes Karpathy

J'ai décidé de scinder le fichier en deux :

• AGENTS.md (97 lignes) : uniquement les règles comportementales
• AGENTS-REF.md (150 lignes) : le référentiel technique complet

Le second n'est pas chargé automatiquement à chaque session. Il est indexé dans le RAG (kimi-rag) et consulté uniquement quand l'agent en a besoin.

Les 6 principes intégrés

Avant / Après : la structure

# Agent Instructions — Eddie

## Langue & Environnement
## Données (chargement dynamique)
## Skills disponibles
## Réseau (9 serveurs, IPs, tunnels)
## Continuité (RAG, MCP, handover)
## Auto-amélioration
## Règles d'or (12 règles détaillées)
## Règles opérationnelles
## Modes de travail
## Session Management

# Agent Instructions — Eddie

## Langue
## Principes Karpathy (6)
  1. Think Before Coding
  2. Push Back
  3. Simplicity First
  4. Surgical Changes
  5. Goal-Driven Execution
  6. No Time Budget Excuses
## Règles d'or (4 condensées)
## Règles opérationnelles
## Modes de travail
## Session Management

→ Référence : AGENTS-REF.md

L'intégration dans le RAG

Le fichier AGENTS-REF.md n'est pas inerte. Il est indexé dans la base de connaissances (kimi-rag, PostgreSQL + vectoriel bge-m3). Quand l'agent a besoin d'une information technique précise — par exemple "Quelle est l'IP du serveur de base de données ?" ou "Comment activer le skill security-specialist ?" — il la récupère via recherche sémantique au lieu de l'avoir en mémoire permanente.

C'est le cœur du context engineering : ne pas remplir la fenêtre de contexte avec des données référentielles, mais la garder disponible juste à temps.

Le résultat concret

La session qui a suivi la mise à jour a été radicalement différente. Quand j'ai demandé de résoudre le même problème de traduction :

• L'agent a d'abord testé la latence du modèle Ollama proposé (3s vs 44s)
• Il a contesté l'idée d'utiliser un modèle trop lent pour un Worker Cloudflare
• Il a proposé une architecture hybride (Ollama rapide pour la qualité, Workers AI en fallback)
• Chaque étape s'est terminée par un critère vérifiable : curl /api/tags → 200, test de traduction → nom propre préservé

Finalement, le pipeline de traduction a été stabilisé avec une solution résiliente : qwen2.5:3b sur un serveur local (via tunnel Cloudflare) comme couche primaire, Workers AI m2m100 comme fallback automatique, et un dictionnaire de post-traitement pour préserver les noms propres.

Ce que vous pouvez appliquer demain

Vous n'avez pas besoin de 9 serveurs pour mettre en place ces principes. Voici les 3 actions immédiates :

1. Auditez la taille de votre prompt système. Si votre AGENTS.md, .cursorrules ou CLAUDE.md dépasse 100 lignes, scindez-le en "comportemental" vs "référentiel".
2. Ajoutez une règle de "Push Back". Autorisez explicitement votre agent à dire "non" quand une demande contredit l'architecture ou les décisions passées.
3. Instaurez des critères de succès vérifiables. Transformez "déployer et tester" en "déployer → curl retourne 200 → logs sans erreur".

"Le code le plus simple qui résout le problème." — Ce principe s'applique aussi bien au code qu'au prompt qui génère le code.

Aller plus loin : le fichier CLAUDE.md de Karpathy est excellent, mais il a ses limites. J'ai publié une relecture critique approfondie qui identifie 7 angles morts et propose une version révisée avec garde-fous pour les agents IA actuels.

Les fichiers complets (sans données sensibles) sont disponibles dans le dépôt du projet. Si vous voulez creuser le sujet du context engineering au-delà du simple fichier de règles, je vous recommande l'article sur notre architecture RAG hybride PostgreSQL + SQLite + graphe AGE.