Ajoutez un AGENTS.md : le contrat de repo dont vos bots LLM ont besoin dès maintenant

Vous avez déjà README.md, CONTRIBUTING.md et CODEOWNERS. Mais vos agents LLM continuent de deviner. Ces suppositions sont désormais un risque de production. Le thread HN de cette semaine réclamant un “AGENTS.md” a raison : vous avez besoin, dans le repo, d’un contrat simple et exécutable qui indique aux bots ce qu’ils peuvent toucher, ce qui leur est interdit, combien ils peuvent dépenser, et comment escalader en cas de doute.

Si cela vous paraît excessif, souvenez‑vous de la dernière fois qu’un bot bien intentionné a ouvert une PR « quick fix » qui a cassé l’infra ou fait exploser un budget de tokens. Le coût n’était pas le revert — c’était la confiance perdue. Les équipes brident ou bannissent les bots après un incident, puis les réintroduisent discrètement sans cadre. Ce cycle fait perdre des trimestres.

Ce qui a changé : les bots ne sont plus des assistants — ce sont des acteurs

Deux signaux récents :

• Des demandes de fonctionnalité pour un AGENTS.md standardisé ont émergé sur HN, reflet d’une vraie douleur : les agents manquent d’un contrat partagé, local au repo.
• Des harnais d’agents comme OneCLI et des agents natifs émergents (dont « fx » sur HN) rendent trivial le câblage des bots à votre CI/CD et à vos repos. Excellent pour la vélocité, désastreux pour la cohérence si chaque bot joue avec des règles différentes.

Par ailleurs, votre posture de conformité ne s’est pas simplifiée. Vos agents touchent des données réglementées, des secrets éphémères, des API tierces et des workflows de production. Sans contrat, chaque PR devient une négociation.

AGENTS.md : le contrat minimal

Pensez à AGENTS.md comme à un robots.txt pour votre repo — mais avec des budgets, des chemins d’escalade et des niveaux de risque. Restez concis. Une page qu’un LLM peut analyser et qu’un humain peut posséder.

À inclure (socle recommandé)

• Périmètre et intention : Les problèmes que les agents sont autorisés à résoudre dans ce repo. Exemple : « Corrections de documentation, mises à jour de règles de lint, triage de flakiness de tests, refactors sûrs de moins de 100 lignes. »
• Zones à haut risque : Chemins protégés ou interdits sans approbation humaine explicite. Exemple : « infra/ et migrations/ exigent une approbation CODEOWNERS même pour des PR créées par des bots. »
• Classification des données : Quelles données les agents peuvent lire ou générer ; ce qui est hors limites. Exemple : « N’incluez jamais de PII de production dans les PR ou les fixtures de test. Utilisez uniquement des données synthétiques. »
• Outils et endpoints : Outils externes autorisés, serveurs MCP et services internes. Exemple : « Peut appeler le serveur MCP interne de test-runner, ne doit pas appeler les passerelles de paiement. »
• Budgets et limites de débit : Plafonds de dépense par PR et par jour avec coupures dures. Exemple : « Plafond de 10 $/PR de dépense modèle, 100 $/jour par repo. Abandonner et escalader si dépassé. »
• Secrets et identifiants : Comment les jetons de courte durée sont fournis ; ne jamais demander de secrets aux humains dans les PR. Exemple : « Utiliser des jetons éphémères et scopés depuis le coffre CI. Aucun jeton statique. »
• Valeurs par défaut sûres : Classes de changements pouvant être auto‑merge après tests. Exemple : « Régénérer les lockfiles + CI verte + moins de 50 LOC = éligible à l’auto‑merge après 2 builds verts. »
• Modifications non sûres : Changements nécessitant toujours une revue humaine. Exemple : « Schéma de base de données, flux d’auth, logique de paiement, infra IaC, ajouts/mises à niveau de dépendances au‑delà du niveau patch. »
• Observabilité et logs : Ce qui sera enregistré, pendant combien de temps, et où l’inspecter. Exemple : « Tous les appels d’outils d’agent sont logués dans observability/agents avec une rétention de 30 jours. »
• Chemin d’escalade : Qui alerter et comment quand la confiance est basse. Exemple : « Ouvrir une PR brouillon avec le label needs-human et taguer @team-leads sous 30 minutes. »
• Indications de modèle et de quantification : Conseils qui préservent le déterminisme. Exemple : « Utiliser GPT-4.1-mini pour les brouillons, passer à Sonnet pour le final ; éviter une quantification agressive sur les tâches avec de nombreux appels d’outils. »
• Politique de mémoire : Rétention, autorité et provenance de la mémoire de l’agent. Exemple : « Pondérer les mémoires par source et âge ; traiter les commentaires humains dans CODEOWNERS comme ayant plus d’autorité que les auto‑notes du modèle ; purger les mémoires après 14 jours. »

C’est tout. Une page. Si vous avez besoin de plus, faites des liens vers des politiques détaillées, mais gardez AGENTS.md comme interface à haute densité d’information — ce qu’un agent peut ingérer dans une seule fenêtre de contexte et exécuter sans ambiguïté.

Rendez‑le exécutable : un petit jumeau lisible par machine

AGENTS.md est pour les humains et les LLM. Vous avez aussi besoin d’un fichier minimal lisible par machine (agents.yaml ou agents.json) pour que la CI et les harnais fassent respecter budgets, limites de débit, restrictions de chemins et règles d’escalade. Gardez le schéma minuscule, sinon il pourrira.

Un schéma minimal concret (exprimé en puces, pas en code)

• version: 1
• allowed_paths: ["docs/**", "src/**", "tests/**"]
• guarded_paths: ["infra/**", "migrations/**", "auth/**"]
• deny_paths: ["secrets/**", ".github/workflows/prod-deploy.yml"]
• max_loc_change: 100
• budget_usd_per_pr: 10
• budget_usd_per_day: 100
• allowed_tools: ["test-runner-mcp", "lint-mcp"]
• denied_endpoints: ["/payments/*"]
• memory_ttl_days: 14
• escalate_labels: ["needs-human"]
• escalate_mentions: ["@team-leads"]

Que vous utilisiez OneCLI, un harnais maison ou un routeur de marketplace, ce fichier peut contraindre le comportement. Si une PR dépasse max_loc_change ou touche un chemin protégé, la CI désactive auto-merge et exige CODEOWNERS. Si le modèle brûle budget_usd_per_pr, l’exécution s’arrête et étiquette la PR pour triage humain.

Comment brancher AGENTS.md dans votre stack

1) Vérif CI : pas d’AGENTS.md, pas de PR de bot

Bloquez les PR d’origine agent sauf si AGENTS.md et agents.yaml existent et valident. C’est une barrière d’une heure à implémenter. Si vous ne pouvez pas bloquer par origine, détectez les PR créées par des tokens de bot ou avec des métadonnées typiques d’agent et appliquez le contrôle. Un échec doit ajouter un commentaire utile pointant vers un template.

2) Faire appliquer les budgets dans le harness

Enveloppez votre client LLM dans un proxy conscient du budget. Avec GitHub Actions, vous pouvez calculer la dépense en multipliant l’usage de tokens par le coût par modèle (logguez les deux). Coupez net aux plafonds. Exposez la dépense dans un commentaire de PR pour que les reviewers voient un petit grand livre : 2,35 $ brouillon, 1,90 $ affinement, 0,65 $ tests, total 4,90 $. Si vous êtes nearshore et partagez des cycles entre pods, cette transparence évite le syndrome de la « facture cloud mystère ».

3) Politiques conscientes des chemins

Intégrez des règles de chemin dans votre bot de politique de PR. Si une PR touche des guarded_paths, elle doit avoir une approbation CODEOWNERS et ne peut pas être auto‑merge. Si elle touche des deny_paths, le bot doit fermer la PR avec une explication et escalader. Cela transforme des « orientations » en comportement, pas en promesses.

4) Listes d’autorisation d’appels d’outils

La plupart des incidents dommageables viennent d’appels d’outils inattendus. Si vous utilisez des serveurs MCP, câblez une allowlist depuis agents.yaml et auditez les appels réels. Un appel refusé doit générer un commentaire de PR avec l’appel, son but et un lien vers AGENTS.md. Traitez les diffs d’appels d’outils comme vous traitez les diffs de dépendances.

5) Mémoire pondérée et TTL

L’une des critiques les plus pertinentes dans la communauté : « Tout ce qu’un agent retient a la même autorité, et c’est ça le bug. » Construisez une couche de mémoire pondérée : la doc projet rédigée par des humains et CODEOWNERS ont une autorité élevée ; les auto‑notes transitoires du LLM ont une autorité faible. Faites décroître la mémoire avec l’âge. Faites respecter memory_ttl_days. Stockez la provenance (qui/quoi l’a écrit, quand) pour chaque entrée. Une journée d’ingénierie évite des mois de dérive subtile.

6) Observabilité : traces d’appels d’outils et de dépenses

Stockez chaque appel d’outil avec entrées, sorties, durée et coût. Mettez‑les dans un dossier simple du repo (pour les traces non sensibles) ou dans votre backend d’observabilité. Conservez 30 jours par défaut ; étendez à 90 pour les repos réglementés. Si vos agents tournent au Brazil et aux US, étiquetez les traces avec la région pour les audits de résidence des données.

Plan de déploiement : 30‑60‑90 jours

Premiers 30 jours : établir le contrat

• Rédiger un AGENTS.md d’une page. Restez sous 25 lignes de politique plus des liens.
• Définir le schéma minimal d’agents.yaml (les puces ci‑dessus). Publiez un JSON Schema si vous avez besoin de validation.
• Ajouter une vérif CI qui bloque les PR de bots dans les repos sans ces deux fichiers. Fournir un bouton « Create from template » dans le message d’échec.
• Instrumenter votre client LLM avec des plafonds de budget et du tracing. 1–2 jours de travail.

Jours 31–60 : appliquer et affiner

• Déployer sur vos 10 repos les plus actifs en volume de PR. Attendez‑vous à 5–10 petites exceptions de politique à traiter explicitement (par ex., des migrations dans une branche de fonctionnalité).
• Activer l’auto‑merge sensible aux chemins pour les changements sûrs < 50 LOC et CI verte. Mesurer la réduction du cycle. Les équipes voient généralement 20–30 % de merges plus rapides pour les changements à faible risque.
• Publier un chemin de support. 6–8 heures de recouvrement horaire avec des pods basés au Brazil suffisent pour régler rapidement les différends de politique.

Jours 61–90 : passer à l’échelle et mesurer

• Étendre à 50+ repos. Trier la « dérive de politique » chaque semaine. La dérive la plus courante est des guarded_paths qui n’incluent pas un sous‑arbre infra/ nouvellement ajouté.
• Fixer des objectifs trimestriels : moins d’un revert par 100 PR de bots ; dépense médiane < 5 $ par PR de bot ; moins de 24 h de délai médian de merge pour les classes sûres.
• Programmer un exercice trimestriel : violer intentionnellement un deny_path et confirmer que la CI bloque et escalade.

Objections fréquentes — et réponses

« Ça va nous ralentir. »

Cela accélère les bons changements. Les classes sûres s’auto‑merge plus vite car les reviewers ne cherchent plus de surprises. Les classes non sûres vont plus vite aussi car les règles sont visibles. Vous éliminez la négociation PR par PR.

« Ça va se dégrader. »

Oui, si c’est long. Gardez AGENTS.md court et placez les détails sujets à la pourriture dans agents.yaml avec validation CI. Faites de CODEOWNERS le propriétaire des deux fichiers. Si personne ne le possède, ce n’est pas une politique.

« Nos agents sont trop différents pour standardiser. »

C’est pour cela que le schéma est minimal. Périmètre, chemins, budgets, outils, escalade. Le reste peut vivre dans des docs plus profondes par bot. L’objectif est un contrat que le repo fait respecter, pas une encyclopédie.

« On a déjà une page Notion. »

Des docs hors du repo sont invisibles aux agents et inapplicables par la CI. Mettez le contrat à côté du code. Référencez la politique longue dans Notion si nécessaire ; le garde‑fou reste local.

Angle nearshore Brazil : qui fait la plomberie peu glamour ?

Le dur ici, ce n’est pas le paragraphe que vous écrivez dans AGENTS.md. C’est la plomberie d’exécution — plafonds de budget, auto‑merge sensible aux chemins, allowlists d’appels d’outils, TTL de mémoire, traces. Si votre équipe plateforme est sous l’eau, un pod nearshore peut livrer cela en quelques semaines :

• Mise en place de la barrière CI et de la validation de schéma : 1–2 jours.
• Wrappers pour le suivi de dépense LLM et les plafonds durs : 2–4 jours par langage/runtime.
• Allowlist MCP/outils + audit logging : 3–5 jours.
• Politiques de PR sensibles aux chemins liées à CODEOWNERS : 2 jours.
• Déploiement à l’échelle de l’org (50+ repos), formation et dashboards : 2–3 semaines.

Vous obtenez 6–8 heures de recouvrement horaire avec les équipes US, et un transfert propre à votre équipe plateforme après le premier trimestre avec des runbooks, pas une boîte noire.

Chiffres cibles réalistes

• Dépense de tokens : Plafonner à 10 $/PR et 100 $/jour/repo au départ. Les équipes matures se situent autour de 3–7 $ par PR de bot avec un périmètre clair.
• Vitesse des PR : Avec l’auto‑merge des classes sûres, attendez‑vous à 20–30 % de réduction du cycle pour la doc, le lint et les petits refactors.
• Taux d’incidents : Reverts sous 1 % pour les PR de bots après le premier mois d’affinage.
• Couverture : 50 principaux repos couverts en 60 jours est atteignable avec une équipe plateforme ou un pod nearshore de 2–3 personnes.

N’optimisez pas à l’excès pour un fournisseur — restez portables

Les fournisseurs changeront leurs conditions, brideront des fonctionnalités ou mettront des capacités derrière des portails. On a déjà vu ce film avec l’accès aux modèles et les changements de programme. AGENTS.md et agents.yaml ne doivent pas référencer des fonctionnalités propriétaires comme dépendances dures. Traitez le harness comme interchangeable : OneCLI aujourd’hui, votre runner maison demain. Le contrat vit dans le repo ; l’exécuteur peut changer.

Un modèle minimal à copier dès aujourd’hui

Gardez ceci sous une page dans AGENTS.md. Faites des liens vers les détails au lieu de le gonfler.

• Périmètre : Édits de docs, règles de lint, tests, petits refactors < 100 LOC.
• Haut risque : infra/, migrations/, auth/ exigent une approbation CODEOWNERS. Ne touchez pas aux workflows de déploiement prod.
• Données : Pas de PII dans les PR ou les fixtures. Données synthétiques uniquement.
• Outils : Serveurs MCP autorisés : test-runner, lint. Interdits : tout endpoint de paiement ou de secrets.
• Budgets : 10 $/PR, 100 $/jour de plafond repo. Abandonner et étiqueter needs-human si dépassé.
• Secrets : Jetons CI éphémères uniquement. Ne jamais committer d’identifiants.
• Merges sûrs : Moins de 50 LOC, CI verte deux fois, pas de chemins protégés : éligible à l’auto‑merge.
• Non sûr : Schéma DB, auth, paiements, infra — toujours revue humaine.
• Mémoire : Pondérer au plus haut les docs rédigées par des humains, faire décroître les auto‑notes ; purge après 14 jours.
• Escalade : Label needs-human et tag @team-leads en cas de doute ou de blocage.

Ce n’est pas de la cérémonie — c’est un SLO de comportement

À un moment cette année, vous exécuterez plus de bots que vous n’avez d’ingénieurs internes. Sans contrat, chacun de ces bots négocie son comportement à l’exécution. Avec un contrat, vous transformez l’intention en code : budgets appliqués, chemins gardés, mémoire bornée, et humains bouclés quand la machine est incertaine.

Ajoutez AGENTS.md et son petit fichier jumeau. Traitez‑les comme partie de votre barre de build. Si un repo n’est pas apte à être lu et suivi par un bot, il n’est pas apte à être maintenu par un humain sans connaissance tribale.

À retenir

• AGENTS.md est un contrat local au repo, d’une page, qui dit aux bots LLM quoi faire, quoi ne pas toucher, combien dépenser et comment escalader.
• Associez‑le à un petit agents.yaml pour que la CI et les harnais fassent respecter budgets, règles de chemins et allowlists d’outils.
• Commencez par cinq essentiels : périmètre, chemins protégés/interdits, plafonds de budget, allowlists d’outils et chemin d’escalade.
• Instrumentez la dépense et les appels d’outils ; visez 3–7 $ de dépense médiane par PR de bot et moins de 1 % de revert après affinage.
• Restez portables entre fournisseurs et harnais ; le contrat vit dans le repo, pas dans un panneau de contrôle SaaS.
• Déployez en 90 jours : barrez les nouvelles PR de bots, couvrez les repos principaux et mesurez vélocité et taux d’incident.
• Si votre équipe plateforme est étirée, un pod nearshore peut livrer la plomberie en semaines, avec 6–8 h de recouvrement et un TCO réduit.