Une équipe qui travaille avec un agent de code découvre vite un phénomène : elle passe son temps à répéter les mêmes consignes.
Ne commite pas sans mon accord. Ne publie pas cet article. Les commandes passent par le conteneur, pas par la machine hôte. Ce terme est banni de nos contenus. Vérifie que la suite de tests passe avant de proposer une livraison.
Chaque session recommence. L'agent est compétent, il n'est pas amnésique par négligence : il n'a simplement aucun moyen de savoir ce qui a été décidé la veille, sauf si on le lui donne.
Voici comment nous encodons ces règles sur nos projets, et ce que ce travail change réellement.
Trois mécanismes, trois usages distincts
Les outils modernes proposent trois façons de transmettre du contexte, souvent confondues alors qu'elles ne servent pas au même besoin.
Le fichier de contexte projet est lu à chaque session. C'est l'endroit des invariants : la commande pour lancer les tests, la structure des dossiers, les interdits de rédaction, les pièges connus. Tout ce qui est vrai en permanence.
Les skills sont des procédures nommées, chargées à la demande. Une skill décrit une tâche précise avec ses étapes : préparer une mise en production, importer des articles, conduire une revue de sécurité. Elle n'occupe pas le contexte tant qu'on ne l'invoque pas.
Les hooks sont des commandes exécutées automatiquement à un moment donné du cycle : avant l'exécution d'un outil, après une modification de fichier, à la fin d'une session. Ils ne dépendent pas de la bonne volonté du modèle, car c'est l'outil lui-même qui les déclenche.
La distinction essentielle porte sur cette dernière catégorie. Une consigne écrite dans un fichier de contexte est une instruction que le modèle peut interpréter, contourner ou oublier au milieu d'une tâche longue. Un hook est un mécanisme. La différence compte pour tout ce qui ne doit jamais échouer.
Ce qui mérite d'entrer dans un fichier de contexte
L'erreur la plus fréquente consiste à y déverser toute la documentation du projet. Un fichier de contexte trop long dilue les règles importantes et consomme de la place utile.
Quatre familles méritent d'y figurer.
Les commandes exactes. Si les commandes passent par un conteneur, l'écrire évite qu'elles soient lancées sur la machine hôte, où elles échoueront ou, pire, produiront un effet inattendu. Une ligne comme docker compose exec app php artisan test vaut mieux qu'une explication.
Les chemins qui comptent. Où se trouvent les modèles, les vues du back-office, les routes publiques. Cela évite à l'agent d'explorer longuement l'arborescence à chaque session.
Les règles de contenu. Sur nos projets, les contraintes de rédaction sont explicites : certains termes sont bannis, aucun prix n'est affiché, certaines affirmations sont interdites parce qu'elles seraient juridiquement exposées. Ces règles ne se devinent pas, et leur violation se voit publiquement.
Les pièges connus. Un piège est une erreur déjà commise. La documenter évite de la reproduire. C'est la partie qui grossit naturellement avec le projet, et la plus rentable.
Ce qui n'a pas sa place : l'historique du projet, les explications d'architecture disponibles dans le code, et les préférences vagues du type « écris du code propre ».
Les hooks : ce que le modèle ne doit pas pouvoir contourner
Un hook s'exécute que le modèle le veuille ou non. C'est ce qui le rend adapté aux garde-fous.
Trois usages ont une valeur immédiate.
Empêcher une commande dangereuse. Un hook déclenché avant l'exécution d'une commande shell peut inspecter cette commande et la refuser. Une suppression récursive sur un chemin sensible, une opération destructive sur une base de production : ces cas se bloquent par un motif, pas par une consigne écrite.
Vérifier automatiquement après modification. Un hook déclenché après l'écriture d'un fichier peut lancer le formatage, l'analyse statique ou la vérification de syntaxe. L'agent reçoit le retour immédiatement et corrige dans la foulée, au lieu de découvrir le problème trois étapes plus tard.
Rappeler une règle au bon moment. Un hook peut injecter un rappel avant une opération sensible : vérifier la branche courante avant un commit, par exemple.
Ce dernier point mérite un exemple vécu. Sur un projet où la règle est de ne jamais commiter directement sur la branche de production, j'ai malgré tout produit un commit sur cette branche, parce que je m'y étais retrouvé après avoir vérifié l'état du serveur. La règle était écrite. Elle n'a pas suffi.
Un hook déclenché avant tout commit, affichant la branche courante, aurait rendu l'erreur visible avant qu'elle ne se produise. C'est exactement la frontière entre une consigne et un mécanisme.
Les skills : capitaliser sur une procédure
Une skill devient utile quand une tâche est à la fois répétitive et détaillée.
Le déploiement en est l'exemple type. Sur nos projets, il enchaîne une dizaine d'étapes : récupérer la branche, rétablir les propriétaires, ajuster les droits sur les dossiers de cache, recompiler les ressources, régénérer les caches applicatifs, recharger les services, vérifier les pages. Oublier une étape produit une panne dont la cause est difficile à retrouver.
Écrire cette procédure une fois, sous forme de skill, remplace une explication complète à chaque déploiement. Elle sert aussi de documentation pour l'équipe humaine, ce qui n'est pas un effet secondaire mineur.
Une skill utile a trois propriétés. Elle est nommée par la tâche, pas par la technologie. Elle contient les commandes exactes, pas des principes. Et elle précise ce qu'il faut vérifier à la fin, faute de quoi la procédure s'arrête au dernier geste plutôt qu'au résultat.
Ce que ce travail change vraiment
Le bénéfice évident est de ne plus répéter. Il y en a deux autres, moins attendus.
L'écriture des règles clarifie le projet. Formuler explicitement « les commandes passent par le conteneur » ou « aucun prix ne doit apparaître sur le site » oblige à trancher des points restés implicites. Sur plusieurs projets, cet exercice a révélé des désaccords au sein de l'équipe, sur des sujets que personne n'avait jamais eu besoin d'énoncer.
Les règles bénéficient aussi aux humains. Un fichier de contexte bien tenu est la meilleure documentation d'accueil qui soit : commandes réelles, pièges connus, conventions en vigueur. Il est à jour parce qu'il sert tous les jours, contrairement à une documentation séparée.
Les limites, qu'il vaut mieux connaître
Une règle écrite n'est pas une garantie. C'est le point le plus important. Un modèle interprète, priorise, et peut se tromper, surtout sur une tâche longue. Ce qui doit être garanti passe par un hook ou par une vérification automatique dans la chaîne d'intégration, jamais par une phrase dans un fichier.
Un fichier de contexte trop long perd en efficacité. Chaque ligne consomme de la place et dilue les règles importantes. Une règle qui ne sert qu'une fois par trimestre appartient à une skill, pas au contexte permanent.
Les règles vieillissent. Une convention abandonnée mais toujours écrite produit un comportement incohérent, difficile à diagnostiquer parce que la cause est un fichier que personne ne relit. Ces fichiers demandent un entretien, modeste mais réel.
Aucun de ces mécanismes ne remplace la relecture. Ils réduisent le bruit et les erreurs mécaniques. Ils ne jugent pas si le code produit répond au besoin.
Par où commencer
La méthode la plus rapide ne consiste pas à concevoir un système complet.
Elle consiste à noter, pendant une semaine de travail, chaque consigne que vous répétez. La liste se stabilise vite, et elle est plus courte qu'on ne le croit : généralement une dizaine de règles.
Ensuite, trier. Ce qui est vrai en permanence va dans le fichier de contexte. Ce qui décrit une procédure devient une skill. Ce qui ne doit jamais échouer devient un hook.
Puis, à chaque erreur constatée, poser une question : cette erreur relevait-elle d'une consigne manquante, ou d'une consigne présente mais non appliquée ? Dans le premier cas, on écrit. Dans le second, on transforme la consigne en mécanisme.
C'est ainsi que le dispositif grossit, guidé par les incidents réels plutôt que par l'anticipation.
Ce qu'il faut retenir
Travailler avec un agent de code sans encoder ses règles revient à réexpliquer son projet chaque matin. Trois mécanismes complémentaires évitent cela : un fichier de contexte pour les invariants, des skills pour les procédures, des hooks pour ce qui ne doit pas dépendre du jugement du modèle.
La distinction décisive est la dernière. Une consigne écrite peut être oubliée au milieu d'une tâche longue ; un hook s'exécute. Tout ce dont l'échec serait coûteux appartient à la seconde catégorie.
Et le travail d'écriture a une valeur qui dépasse l'outil : il produit la documentation que le projet n'avait jamais pris le temps de rédiger.
