06 - Fichiers de contexte : CLAUDE.md, AGENTS.md et au-delà

Fichiers de contexte : CLAUDE.md, AGENTS.md et au-delà

Hermes Agent ne se contente pas d'exécuter vos commandes : il comprend votre projet grâce à un système de fichiers de contexte qui guident son comportement à chaque session. Plutôt que de répéter les mêmes consignes tour après tour, vous déposez vos préférences dans un fichier markdown, et l'agent les intègre automatiquement à son prompt système.

Cet article explore en profondeur le mécanisme de fichiers de contexte d'Hermes Agent : les types supportés, la hiérarchie de priorité, la découverte progressive des sous-répertoires, et les bonnes pratiques pour tirer le maximum de cette fonctionnalité.

Qu'est-ce qu'un fichier de contexte ?

Un fichier de contexte est un simple fichier Markdown placé à la racine (ou dans un sous-répertoire) de votre projet. Il contient des instructions que l'agent lit automatiquement et injecte dans son prompt système. Cela lui permet de « connaître » votre projet sans que vous ayez à lui expliquer à chaque session.

Concrètement, ces fichiers peuvent contenir :
- L'architecture technique du projet
- Les conventions de code et de nommage
- Les outils de build, les ports, les commandes de test
- Les restrictions et les choses à ne jamais faire
- Des notes spécifiques au déploiement ou à l'environnement

Les fichiers de contexte supportés

Hermes Agent reconnaît plusieurs formats de fichiers de contexte, chacun avec son origine et sa priorité :

.hermes.md ou HERMES.md — Priorité maximale

C'est le fichier dédié à Hermes Agent. S'il est présent à la racine de votre projet (ou remonté jusqu'à la racine Git), il est chargé en priorité absolue. C'est le choix recommandé si vous utilisez exclusivement Hermes Agent sur un projet.

Où le placer : à la racine du projet ou n'importe où dans l'arborescence, Hermes remonte jusqu'à la racine Git pour le trouver.

AGENTS.md — Le standard multi-agents

AGENTS.md est le fichier de contexte principal par défaut. Il est conçu pour être partagé entre différents agents IA (Hermes, Claude Code, Codex, etc.). Il décrit la structure du projet, les conventions à suivre et les instructions spéciales.

Où le placer : à la racine du projet et/ou dans les sous-répertoires pour des instructions locales.

Exemple concret :

Un fichier AGENTS.md typique pour une application Next.js 14 avec backend FastAPI contient généralement les types de contenus suivants : une section d'architecture détaillant le découpage frontend/backend et le choix de la base de données (par exemple PostgreSQL 16 en 2025), une section de conventions précisant l'usage du mode strict TypeScript et des annotations de type Python PEP 8, le format standardisé des réponses API (par exemple {data, error, meta}), l'emplacement des tests, et des notes importantes sur les migrations de base de données ou la gestion des variables d'environnement secrètes.

CLAUDE.md — Compatibilité Claude Code

CLAUDE.md est le format utilisé par Claude Code d'Anthropic. Hermes Agent le détecte automatiquement, ce qui signifie que vos projets existants configurés pour Claude Code fonctionnent immédiatement avec Hermes, sans aucune adaptation.

Quand l'utiliser : si vous utilisez déjà Claude Code et que vous souhaitez la compatibilité entre les deux outils.

.cursorrules et .cursor/rules/*.mdc — Compatibilité Cursor

Hermes Agent est aussi compatible avec les fichiers de règles de Cursor IDE. Si votre projet contient un .cursorrules à la racine ou des modules de règles dans .cursor/rules/, Hermes les chargera automatiquement — à condition qu'aucun fichier de priorité supérieure ne soit présent.

Cas d'usage typique : vous avez un projet existant configuré pour Cursor et vous voulez tester Hermes Agent sans duplication de configuration.

La hiérarchie de priorité

Un point crucial : un seul type de contexte projet est chargé par session. Le premier fichier trouvé l'emporte, selon cet ordre de priorité :

1. .hermes.md / HERMES.md — Priorité maximale
2. AGENTS.md — Standard multi-agents
3. CLAUDE.md — Compatibilité Claude Code
4. .cursorrules — Compatibilité Cursor

Exception : SOUL.md est toujours chargé indépendamment, en slot #1, comme identité de l'agent. Il n'entre pas dans cette compétition.

Cette conception est intelligente : elle évite les conflits entre différentes conventions et garantit un comportement prévisible.

SOUL.md : la personnalité globale

Contrairement aux autres fichiers de contexte qui sont locaux au projet, SOUL.md est global à l'instance Hermes. Il se place uniquement dans HERMES_HOME (par défaut ~/.hermes/) :

• ~/.hermes/SOUL.md
• ou $HERMES_HOME/SOUL.md si vous utilisez un répertoire home personnalisé

Points importants :
- Hermes génère un SOUL.md par défaut s'il n'existe pas
- Hermes ne cherche pas SOUL.md dans le répertoire de travail
- Si le fichier est vide, rien n'est injecté dans le prompt
- S'il contient du texte, il est injecté tel quel après analyse de sécurité

SOUL.md contrôle la personnalité, le ton et le style de communication de l'agent — pas les règles techniques du projet.

Découverte progressive des sous-répertoires

C'est l'une des fonctionnalités les plus élégantes d'Hermes Agent. Au démarrage, seul le fichier de contexte à la racine est chargé. Ensuite, au fil de la session, lorsque l'agent navigue dans les sous-répertoires (via read_file, terminal, search_files, etc.), il découvre progressivement les fichiers de contexte locaux.

Exemple de structure monorepo :

mon-projet/
├── AGENTS.md              ← Chargé au démarrage (prompt système)
├── frontend/
│   └── AGENTS.md          ← Découvert quand l'agent lit des fichiers frontend/
├── backend/
│   └── AGENTS.md          ← Découvert quand l'agent lit des fichiers backend/
└── shared/
    └── AGENTS.md          ← Découvert quand l'agent lit des fichiers shared/

Exemple de sous-répertoire frontend :

Le fichier de contexte frontend précise généralement le gestionnaire de paquets à utiliser (comme pnpm plutôt que npm), l'organisation des composants et des pages selon le pattern du framework, l'usage exclusif d'un utilitaire CSS comme Tailwind sans styles inline, et la commande spécifique pour lancer les tests.

Exemple de sous-répertoire backend :

Le fichier de contexte backend définit typiquement l'outil de gestion des dépendances (comme poetry), la commande de lancement du serveur de développement, l'obligation de documenter tous les endpoints avec des docstrings OpenAPI, et l'arborescence standard des modèles et schémas de données.

Avantages de l'approche progressive

• Pas de gonflement du prompt système — les hints des sous-répertoires n'apparaissent que quand c'est pertinent
• Préservation du cache de prompt — le prompt système reste stable entre les tours
• Chaque sous-répertoire est vérifié au plus une fois par session
• La remontée des répertoires parents fonctionne aussi : lire backend/src/main.py découvrira backend/AGENTS.md même si backend/src/ n'a pas de fichier de contexte

Injection automatique dans le prompt système

Le processus de chargement, implémenté dans agent/prompt_builder.py, suit ces étapes :

1. Scan du répertoire de travail selon la priorité (.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules)
2. Lecture du fichier en UTF-8
3. Scan de sécurité pour détecter les tentatives d'injection de prompt
4. Troncature si le fichier dépasse 20 000 caractères (70% début, 20% fin, 10% marqueur)
5. Assemblage sous un header # Project Context
6. Injection dans le prompt système

Le prompt final ressemble à ceci :

# Project Context
The following project context files have been loaded and should be followed:

## AGENTS.md
[Votre contenu AGENTS.md]

[Contenu SOUL.md inséré directement]

Différence entre fichiers de contexte et mémoire persistante

Il est essentiel de distinguer deux mécanismes souvent confondus :

Les fichiers de contexte définissent les règles du jeu. La mémoire persistante enregistre ce que l'agent a appris en jouant.

Sécurité : protection contre l'injection de prompt

Hermes Agent intègre un scanner de sécurité qui analyse tous les fichiers de contexte avant injection. Il détecte :

• Les tentatives de surcharge d'instructions : « ignore previous instructions »
• Les patterns de tromperie : « do not tell the user »
• Les surcharges de prompt système
• Les commentaires HTML cachés ou les divs invisibles
• Les tentatives d'exfiltration d'identifiants
• L'accès à des fichiers secrets (cat .env)
• Les caractères invisibles (espaces zero-width, overrides bidirectionnels)

Si une menace est détectée, le fichier est bloqué avec un message clair : [BLOCKED: AGENTS.md contained potential prompt injection...].

Recommandation : ce scanner protège contre les patterns courants, mais ne remplace pas la vigilance. Validez toujours le contenu des AGENTS.md dans les projets que vous n'avez pas créés.

Limites de taille

Les fichiers de sous-répertoires sont limités à 8 000 caractères chacun.

HERMES_HOME et organisation des fichiers

La variable d'environnement HERMES_HOME définit le répertoire personnel d'Hermes Agent (par défaut ~/.hermes/). C'est là que se trouvent :

• SOUL.md — La personnalité globale de l'agent
• skills/ — Les compétences installées
• La configuration globale
• La base de données de mémoire persistante

Structure typique :

• SOUL.md : fichier définissant la personnalité et le ton de l'agent
• skills/ : répertoire contenant les compétences installées (comme sat-content-creator)
• config.toml : fichier de configuration globale
• memory.db : base de données de la mémoire persistante

Les fichiers de contexte projet restent dans le dépôt Git du projet. Seuls SOUL.md et la configuration globale vivent dans HERMES_HOME.

Bonnes pratiques

Faire :
- Garder les fichiers de contexte concis — bien en dessous de 20 000 caractères
- Structurer avec des headers ## pour chaque section (architecture, conventions, notes)
- Inclure des exemples concrets de patterns de code préférés
- Mentionner explicitement ce qu'il ne faut pas faire
- Lister les chemins clés et les ports de service
- Mettre à jour le fichier quand le projet évolue — un contexte obsolète est pire que pas de contexte du tout
- Utiliser des AGENTS.md par sous-répertoire pour les monorepos
- Committer les fichiers de contexte dans Git pour le partage d'équipe

Éviter :
- Dupliquer les informations entre AGENTS.md et SOUL.md
- Mettre des secrets ou des clés API dans les fichiers de contexte
- Écrire des instructions contradictoires dans les sous-répertoires
- Ignorer la taille maximale — un fichier trop long sera tronqué et perdra de l'information
- Placer des fichiers AGENTS.md ou CLAUDE.md hors de votre projet — Hermes pourrait les charger par erreur (cf. issue #14471 sur GitHub)

Pièges à éviter

1. Le contexte obsolète — un fichier de contexte qui ne correspond plus au projet induit l'agent en erreur. Prenez l'habitude de le réviser lors des grandes refactors.

2. La surcharge d'instructions — trop de règles noient l'agent dans les détails. Concentrez-vous sur ce qui est réellement discriminant : les conventions de code, les chemins critiques et les interdictions.

3. Conflits entre fichiers — avec la découverte progressive des sous-répertoires, un AGENTS.md dans un sous-dossier peut contredire celui de la racine. Assurez-vous de la cohérence.

4. Fichiers AGENTS.md parasites — si vous travaillez dans un répertoire parent contenant un AGENTS.md pour un autre projet, Hermes pourrait le charger accidentellement. Travaillez toujours depuis la racine de votre projet.

Conclusion

Les fichiers de contexte sont l'un des piliers de la productivité avec Hermes Agent. Ils transforment chaque session en un agent qui « connaît » votre projet, sans effort de répétition. La hiérarchie de priorité (.hermes.md > AGENTS.md > CLAUDE.md > .cursorrules) assure la compatibilité avec les autres outils du marché, tandis que la découverte progressive des sous-répertoires optimise l'utilisation du contexte sans surcharger le prompt.

Pour aller plus loin dans votre maîtrise d'Hermes Agent, consultez notre article sur la maîtrise du CLI.