SOUL.md et contexte projet : répartir la voix et les règles sans contradictions
Tu as un SOUL.md qui définit le ton de ton agent. Tu as un AGENTS.md qui décrit les conventions de ton projet. Et un matin, l’agent répond avec une personnalité qui n’a rien à voir avec ce que tu avais prévu, ou pire, il ignore une règle projet que tu croyais active.
Le problème n’est pas un bug. C’est une confusion entre deux couches de contexte qui n’ont pas le même rôle, pas la même portée, et pas le même mécanisme de chargement.
Hermes Agent distingue clairement l’identité globale de l’instance et les instructions locales d’un projet. Si tu mélanges les deux, tu obtiens des comportements incohérents. Si tu les répartis correctement, chaque couche fait exactement ce qu’elle doit faire.
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.
Arbitrages utiles
Questions réelles
Accès gratuit
Tu arrives avec ton sujet, tu repars avec plus de clarté.
SOUL.md : l’identité globale de ton instance Hermes
SOUL.md est le fichier qui contrôle la personnalité, le ton et le style de communication de ton agent, quel que soit le projet sur lequel tu travailles. Il est chargé depuis HERMES_HOME (par défaut ~/.hermes/SOUL.md) et il est toujours actif, indépendamment du répertoire de travail.
C’est le slot numéro 1 du prompt système. Hermes le charge avant toute autre instruction, et il reste présent pendant toute la session.
Ce que tu mets dans SOUL.md :
- Le ton de voix que tu veux pour ton agent (direct, technique, pédagogue, etc.)
- La langue par défaut
- Les règles de communication (tutoiement, vouvoiement, niveau de détail)
- Les préférences de formatage (Markdown, code blocks, etc.)
- Les comportements transversaux (toujours proposer une vérification, toujours citer ses sources, etc.)
Un SOUL.md bien écrit donne une colonne vertébrale à ton agent. Il ne change pas d’un projet à l’autre, et c’est normal : c’est ta configuration personnelle, pas celle du codebase.
Ce que SOUL.md n’est pas : une règle projet. N’y mets pas les conventions de ton repo, les ports de ton serveur, ou le nom de ton ORM. Ce n’est pas son rôle.
Un changement dans SOUL.md prend effet à la prochaine session. Si tu modifies le fichier en cours de session, l’agent ne le verra pas avant le prochain démarrage.
AGENTS.md et .hermes.md : les règles locales du projet
Les fichiers de contexte projet (AGENTS.md, .hermes.md, CLAUDE.md, .cursorrules) sont découverts automatiquement à partir de ton répertoire de travail. Hermes remonte jusqu’à la racine git pour trouver le premier fichier disponible, et un seul est chargé par session : .hermes.md d’abord, puis AGENTS.md, puis CLAUDE.md, puis .cursorrules. Premier trouvé, premier servi.
Ce que tu mets dans AGENTS.md :
- L’architecture du projet (frontend, backend, base de données)
- Les conventions de code (TypeScript strict, PEP 8, etc.)
- Les commandes utiles (build, test, déploiement)
- Les règles spécifiques au projet (ne pas modifier les migrations, ne pas commit le .env)
- Les dépendances et versions
AGENTS.md est aussi découvert progressivement dans les sous-répertoires. Si ton projet a un frontend/AGENTS.md et un backend/AGENTS.md, Hermes les charge quand il navigue dans ces dossiers. C’est utile pour les monorepos : chaque sous-projet peut avoir ses propres conventions sans alourdir le fichier racine.
La matrice de répartition
Le tableau ci-dessous t’aide à décider où placer chaque type d’instruction.
| Type d’instruction | SOUL.md | AGENTS.md | Pourquoi |
|---|---|---|---|
| Ton de voix, tutoiement/vouvoiement | Oui | Non | Identité transverse, ne dépend pas du projet |
| Langue par défaut | Oui | Non | Préférence personnelle, pas une règle projet |
| Architecture du projet | Non | Oui | Spécifique au codebase, change d’un repo à l’autre |
| Conventions de code | Non | Oui | Propagées par sous-répertoire si besoin |
| Commandes de build/test | Non | Oui | Propagées par sous-répertoire si besoin |
| Règles de comportement transverse | Oui | Non | « Toujours proposer une vérification » est global |
| Règles métier du projet | Non | Oui | Ex : « ne jamais modifier les migrations directement » |
| Préférences de formatage | Oui | Possible | SOUL.md pour le style global, AGENTS.md si le projet a un format spécifique |
Le piège numéro un : la duplication contradictoire
Ce problème est plus fréquent qu’on ne le croit, surtout quand on commence à multiplier les agents. On crée un SOUL.md pour le ton, puis on ajoute un AGENTS.md par projet, et on se retrouve avec des chevauchements qu’on n’avait pas anticipés.
Audit rapide avant de multiplier les agents
Avant d’ajouter un troisième ou quatrième agent à ton équipe, prends dix minutes pour vérifier l’état de tes fichiers de contexte.
Voici une checklist simple :
- Ouvre ton SOUL.md. Est-ce qu’il contient des instructions qui concernent un projet spécifique ? Si oui, déplace-les dans l’AGENTS.md du projet concerné.
- Ouvre chaque AGENTS.md de chaque projet. Est-ce qu’un de ces fichiers contient des règles de personnalité ou de ton ? Si oui, remonte-les dans SOUL.md.
- Vérifie les chevauchements. Y a-t-il une règle qui apparaît à la fois dans SOUL.md et dans un AGENTS.md ? Choisis le bon emplacement et supprime le doublon.
- Teste sur une session fraîche. Ferme ta session Hermes, rouvre-la, et vérifie que l’agent se comporte comme prévu sur un projet connu.
Cet audit prend peu de temps et évite des heures de débogage de comportement plus tard.
Ce qu’il faut retenir pour la suite
SOUL.md et AGENTS.md ne sont pas deux façons de faire la même chose. Ce sont deux couches distinctes avec des responsabilités claires. SOUL.md définit qui est ton agent. AGENTS.md définit ce qu’il doit savoir sur ton projet.
Si tu veux aller plus loin sur la gouvernance des règles dans Hermes Agent (priorités, surcharges, règles conditionnelles), l’article sur la gouvernance des règles Hermes Agent couvre la mécanique complète.
Et si tu veux apprendre à configurer tout ça correctement dès le départ, la formation Hermes Agent te donne les bases pour construire une équipe d’agents qui ne se contredisent pas. Tu peux faire une demande d’accès directement sur la page de la formation.
