AGENTS.md avec Hermes : donner un cadre local sans réécrire le brief à chaque fois

Tu lances un agent IA sur un projet. Tu lui expliques le contexte, les conventions, les pièges à éviter. Il bosse, c’est propre. Tu fermes la session.

Le lendemain, tu rouvres un terminal dans le même dossier. L’agent a tout oublié. Tu recommences l’explication.

C’est le problème que règle AGENTS.md. Pas en ajoutant une couche magique de mémoire, mais en posant un fichier texte dans ton projet. Un fichier que l’agent lit à chaque session, sans que tu aies à répéter quoi que ce soit.

Communauté Kavyro

Le vrai sujet n’est pas d’ajouter un agent de plus.

Si tu veux construire un système d’agents utile, il te faut surtout une structure claire, de bons arbitrages et des retours terrain. C’est exactement ce qu’on partage dans Kavyro.

Cas concrets
Arbitrages utiles
Questions réelles
Accès gratuit

Rejoindre la communauté

Tu arrives avec ton sujet, tu repars avec plus de clarté.

AGENTS.md, c’est quoi exactement ?

AGENTS.md est un fichier de contexte projet. Tu le poses à la racine de ton repo, et Hermes le charge automatiquement au démarrage. Il contient ce que l’agent doit savoir pour bosser sur ton projet sans que tu lui réexpliques à chaque fois : architecture, conventions, règles métier, dépendances, ports, ce qu’il ne faut surtout pas toucher.

Ce n’est pas une formule miracle. Ce n’est pas une mémoire universelle. C’est un cadre local, limité au dossier dans lequel tu travailles.

Hermes reconnaît plusieurs formats de contexte projet. Le premier trouvé dans cet ordre est chargé : .hermes.md d’abord, puis AGENTS.md, puis CLAUDE.md, puis .cursorrules. Un seul est actif par session. Si tu as déjà un CLAUDE.md pour Claude Code, il sera lu automatiquement. Mais si tu veux un fichier dédié à Hermes, crée un AGENTS.md.

Petite subtilité utile : la découverte est progressive. Si ton projet a des sous-dossiers avec leurs propres règles (un frontend/AGENTS.md, un backend/AGENTS.md), Hermes les découvre au fur et à mesure qu’il navigue dans ces dossiers. Tu n’as pas besoin de tout mettre dans un fichier monstre à la racine.

Un exemple concret, pas une dissertation

Voici à quoi ressemble un AGENTS.md utile. Pas de littérature, pas de manifeste. Juste ce que l’agent a besoin de savoir pour ne pas casser ton projet.

# Contexte projet

Application Next.js 14 avec backend FastAPI.

## Architecture
- Frontend : Next.js 14 App Router dans /frontend
- Backend : FastAPI dans /backend, SQLAlchemy ORM
- Base de données : PostgreSQL 16
- Déploiement : Docker Compose sur VPS Hetzner

## Conventions
- TypeScript strict pour tout le frontend
- Python PEP 8, type hints obligatoires
- Toutes les API renvoient du JSON au format {data, error, meta}
- Tests dans __tests__/ (frontend) ou tests/ (backend)

## À ne pas toucher
- Ne jamais modifier les fichiers de migration directement, utiliser Alembic
- Le fichier .env.local contient les vraies clés API, ne pas le commiter
- Ports : frontend 3000, backend 8000, base de données 5432

Ce fichier fait 20 lignes. Il couvre l’architecture, les conventions, et les interdits. Un agent qui le lit sait où il est, comment le code est organisé, et ce qu’il ne doit pas casser. Tu peux l’écrire en 5 minutes et le faire évoluer avec le projet.

Piège classique : ne pas confondre AGENTS.md et SOUL.md

AGENTS.md est un fichier de projet. Il dit « voici comment ce code est structuré, voici les règles ». Il vit dans ton repo, change avec ton projet, et ne concerne que ce projet-là.

SOUL.md est tout autre chose. C’est un fichier global qui définit la personnalité et le ton de ton instance Hermes, quel que soit le projet sur lequel tu travailles. Il est stocké dans HERMES_HOME (~/.hermes/SOUL.md), pas dans ton repo. Il ne contient pas d’instructions projet.

Si tu mets tes conventions de code dans SOUL.md, elles s’appliqueront à tous tes projets, y compris ceux où elles n’ont aucun sens. Si tu mets la personnalité de ton agent dans AGENTS.md, tu pollues le contexte projet avec du bruit inutile. Deux fichiers, deux jobs différents.

Ce qu’il ne faut pas mettre dans un AGENTS.md

Le fichier a une limite de taille : 20 000 caractères par défaut. Ce n’est pas une contrainte arbitraire, c’est une protection. Un fichier trop long dilue l’information utile et consomme du contexte précieux dans la fenêtre de l’agent.

Ce qui n’a pas sa place dans un AGENTS.md :

Des prompts conversationnels. « Tu es un expert en React, sois concis et pédagogue. » Ce n’est pas le rôle d’un fichier de contexte projet. Pour ça, il y a SOUL.md ou les instructions de session.
Des morceaux de code. Un AGENTS.md n’est pas une base de connaissances. Si tu veux documenter des patterns de code, fais-le dans la doc du projet et référence-la.
L’historique du projet. L’agent n’a pas besoin de savoir que le projet a démarré en 2019 avec Create React App avant de migrer vers Next.js en 2022. Ce qui compte, c’est l’état actuel.
Des règles qui changent selon l’humeur. Si une règle n’est pas stable, ne la mets pas dans AGENTS.md. Le fichier doit pouvoir être lu par n’importe quel agent, n’importe quel jour, avec le même résultat.

La règle simple : si tu ne le dirais pas à un nouveau dev qui débarque sur le projet, ne le mets pas dans AGENTS.md.

Le scan de sécurité : ce qui se passe avant que le fichier soit chargé

Avant d’inclure un AGENTS.md dans le contexte de l’agent, Hermes le scanne. Le scanner cherche des patterns d’injection de prompt : des instructions cachées dans des commentaires HTML, des tentatives d’exfiltration de variables d’environnement, des commandes shell déguisées.

Si un pattern suspect est détecté, le fichier est bloqué. L’agent reçoit un message clair : [BLOCKED: AGENTS.md contained potential prompt injection. Content not loaded.].

C’est une protection utile, surtout si tu travailles sur des projets open source ou des repos partagés où tu n’as pas écrit tous les fichiers toi-même. Mais ce n’est pas une garantie absolue. Le scanner couvre les patterns d’attaque connus, pas toutes les formes d’injection possibles. Si tu récupères un AGENTS.md d’un projet que tu ne connais pas, lis-le avant de lancer un agent dessus. La revue humaine reste la dernière barrière.

Comment vérifier que ton AGENTS.md est bien pris en compte

Deux méthodes simples.

La première : lance Hermes dans ton projet et demande-lui « quelles sont les conventions du projet ? ». S’il te répond avec le contenu de ton AGENTS.md, c’est chargé. S’il improvise, c’est que le fichier n’a pas été trouvé ou a été bloqué par le scan de sécurité.

La deuxième : vérifie le nom et l’emplacement. Le fichier doit s’appeler exactement AGENTS.md (ou .hermes.md si tu veux la priorité maximale) et être à la racine du projet ou dans un sous-dossier pertinent. Hermes remonte jusqu’à la racine git pour trouver le fichier principal, donc pas besoin de le dupliquer partout.

Si ton fichier fait plus de 20 000 caractères, il sera tronqué. Tu verras un message du type [...truncated AGENTS.md: kept 14000+4000 of 25000 chars]. Dans ce cas, coupe le superflu plutôt que d’augmenter la limite.

Définir le cadre avant d’automatiser

Un AGENTS.md bien écrit, c’est 5 minutes de boulot et des heures de « je n’ai pas à réexpliquer le contexte à chaque session ». Ce n’est pas un fichier magique qui rend l’agent intelligent. C’est un fichier pragmatique qui lui évite de bosser à l’aveugle.

Si tu utilises déjà un agent IA pour coder, commence par ça. Écris les 10 lignes qui décrivent ton architecture, tes conventions, et ce qu’il ne faut pas casser. Pose le fichier à la racine. Lance une session et vérifie que l’agent le lit.

Ensuite, si tu veux aller plus loin et comprendre comment configurer un agent Hermes de A à Z, contexte projet, personnalité, outils, automatisations, la formation Hermes Agent couvre tout le cycle. Tu peux faire une demande d’accès directement sur la page de la formation.

Pour approfondir la logique de briefing d’un agent IA au-delà du simple fichier de contexte, j’ai détaillé la méthode complète dans comment briefer un agent IA sans lui écrire un roman.

Trinity