Comment rédiger un bon program.md : guide pratique pour les instructions d'agents IA

L’autoresearch d’Andrej Karpathy a prouvé qu’un fichier Markdown bien rédigé peut diriger des agents IA pour faire de vraies découvertes scientifiques du jour au lendemain. Mais tous les fichiers program.md ne se valent pas.

La qualité de vos instructions Markdown détermine directement la qualité de la sortie de l’agent IA. Un program.md vague produit des expériences aléatoires et sans direction. Un précis produit des améliorations ciblées qui s’accumulent.

Voici comment rédiger un program.md qui fonctionne vraiment.

La structure d’un bon program.md

Chaque program.md efficace a besoin de cinq sections, que vous fassiez de la recherche en ML ou tout autre travail dirigé par un agent.

1. Contexte : que doit savoir l’agent ?

L’agent commence avec une compréhension nulle de votre projet. Votre premier travail est de lui donner suffisamment de contexte pour prendre des décisions intelligentes.

Ce qu’il faut inclure :

Ce que fait le projet
À quoi ressemble la base de code
Les fichiers clés et leurs objectifs
La terminologie spécifique au domaine
L’état actuel et les problèmes connus

Ce qu’il faut omettre :

Les informations évidentes que le LLM connaît déjà
Les détails d’implémentation qu’il peut lire dans le code
L’historique qui n’affecte pas les décisions actuelles

2. Objectifs : que doit optimiser l’agent ?

C’est la section la plus critique. L’agent a besoin d’un objectif clair et mesurable.

Dans l’autoresearch, l’objectif est simple : réduire val_bpb (bits de validation par octet). L’agent peut mesurer cela après chaque run d’entraînement de 5 minutes.

Pour vos propres projets, définissez le succès en termes que l’agent peut évaluer :

« Réduire le temps de chargement de page en dessous de 2 secondes »
« Augmenter la couverture de tests au-dessus de 80 % »
« Réduire la taille du bundle d’au moins 15 % »

Les objectifs vagues comme « améliorer le code » produisent des résultats vagues. Les objectifs mesurables produisent des améliorations ciblées.

3. Contraintes : que l’agent ne doit-il jamais faire ?

Les contraintes sont tout aussi importantes que les objectifs. Sans elles, l’agent pourrait trouver des solutions créatives que vous ne voulez pas — comme supprimer tous les tests pour « améliorer » la vitesse de build.

Contraintes courantes :

Ne pas modifier les fichiers de test ou le code d’évaluation
Ne pas changer l’API publique
Ne pas introduire de nouvelles dépendances
Ne pas dépasser un budget mémoire
Garder le code lisible et maintenable

Dans l’autoresearch, la contrainte clé est que seul train.py peut être modifié. Le pipeline de données, le code d’évaluation et l’ensemble de test sont verrouillés. Cela empêche l’agent de manipuler les métriques.

4. Stratégie : comment l’agent doit-il aborder le problème ?

C’est là que votre expertise du domaine brille. Vous savez des choses que l’agent ne sait pas — quelles directions sont prometteuses et lesquelles sont des impasses.

Bonnes instructions de stratégie :

« Commencer par l’ajustement des hyperparamètres avant les changements architecturaux »
« Se concentrer sur le mécanisme d’attention — l’implémentation actuelle pourrait être sous-optimale »
« Essayer d’abord des techniques de régularisation : dropout, weight decay, layer norm »
« Éviter les changements qui augmentent le temps d’entraînement de plus de 10 % »

Mauvaises instructions de stratégie :

« Tout essayer » (trop vague)
« Changer le taux d’apprentissage à 0.001 » (trop précis — vous micro-managez)

Le bon équilibre est une orientation directionnelle qui laisse l’agent explorer dans des limites productives.

5. Évaluation : comment l’agent doit-il juger le succès ?

L’agent doit savoir comment mesurer si ses changements ont aidé. Dans l’autoresearch, c’est intégré dans la boucle : si val_bpb s’améliore, garder le changement. Sinon, réinitialiser.

Pour d’autres contextes, définissez vos critères d’évaluation :

Quelles métriques comptent ?
Quel seuil compte comme une amélioration ?
Comment l’agent doit-il gérer les résultats ambigus ?
Quand l’agent doit-il s’arrêter et faire un rapport ?

Erreurs courantes

Être trop vague

« Améliorer le modèle » ne donne aucune direction à l’agent. Soyez précis sur ce que « meilleur » signifie, comment le mesurer, et quelles approches essayer en premier.

Être trop précis

« Changer la ligne 47 pour utiliser un taux d’apprentissage de 3e-4 » annule l’objectif de l’Agentic Engineering. Vous êtes censé fixer la direction, pas dicter l’implémentation. Laissez l’agent explorer.

Oublier les contraintes

Sans contraintes, les agents trouveront le chemin de moindre résistance — ce qui n’est souvent pas ce que vous voulez. Un agent à qui on dit de « réduire le temps d’entraînement » pourrait sauter la moitié des données d’entraînement si vous ne l’en empêchez pas.

Ne pas itérer

Votre premier program.md ne sera pas parfait. Observez ce que fait l’agent, voyez où il se trompe, et mettez à jour vos instructions. Les meilleurs fichiers program.md évoluent sur des dizaines d’itérations.

La boucle d’itération

Écrire program.md n’est pas un processus en une seule fois. C’est une boucle :

Écrire votre program.md initial
Exécuter l’agent
Revoir ce que l’agent a fait
Mettre à jour vos instructions en fonction de ce qui a fonctionné et ce qui n’a pas fonctionné
Répéter

Chaque itération rend vos instructions plus précises. Après quelques cycles, vous aurez un program.md qui produit systématiquement de bons résultats.

C’est la compétence centrale de l’Agentic Engineering : pas écrire du code, mais rédiger des instructions d’agents de plus en plus efficaces par l’itération.

Construire votre bibliothèque de référence

Les meilleurs fichiers program.md ne viennent pas de nulle part. Ils se construisent sur une connaissance approfondie du domaine — documentation, articles, bonnes pratiques et exemples.

Quand vous trouvez du matériel de référence utile sur le web, sauvegardez-le en Markdown. Ensuite, quand vous rédigez votre program.md, vous pouvez intégrer le contexte pertinent, citer des techniques spécifiques et donner à l’agent les connaissances de base dont il a besoin.

Les chercheurs qui obtiennent les meilleurs résultats avec l’autoresearch ne sont pas juste de bons rédacteurs. Ce sont des experts du domaine avec du matériel de référence bien organisé qu’ils peuvent synthétiser en instructions claires pour les agents.

Save convertit n’importe quelle page web en Markdown propre — parfait pour construire la bibliothèque de référence qui alimente des fichiers program.md efficaces. Essayez Save gratuitement.