Contexte et motivation
Claude Code, l’environnement de développement dédié aux agents IA, repose sur un répertoire .claude contenant des fichiers de configuration. Historiquement, le fichier Claude.md était le point d’entrée unique pour déclarer les agents, leurs prompts et leurs paramètres. La page de changelog montre une cadence de mises à jour (versions 2.1.xxx et 2.0.xxx) qui indique un effort continu d’ajustement de la logique de chargement. La dernière modification introduit un comportement de secours : lorsqu’Claude.md est absent, le système recherche automatiquement AGENTS.md.
Mécanisme de détection des fichiers
Le chargeur de configuration parcourt le répertoire .claude à l’initialisation. Il applique l’algorithme suivant : si Claude.md existe, il est lu et parsé ; sinon, le moteur vérifie la présence de AGENTS.md. Cette logique repose sur une simple condition if (exists('Claude.md')) else if (exists('AGENTS.md')), implémentée en JavaScript au sein du SDK. Le fallback évite une erreur d’absence de fichier et permet à des projets existants, qui utilisaient auparavant AGENTS.md, de fonctionner sans migration immédiate.
.claude/
├── Claude.md
└── AGENTS.md
Implications pour les projets
Les développeurs peuvent désormais structurer leurs agents de deux manières : soit en conservant le format historique Claude.md, soit en adoptant AGENTS.md comme fichier principal. Cette flexibilité réduit le risque d’interruption lors de la mise à jour du SDK, car les projets qui n’ont pas encore migré vers Claude.md continuent de charger leurs définitions. En pratique, le temps d’initialisation reste comparable, le moteur ne charge qu’un seul fichier texte, ce qui limite l’impact sur la latence du démarrage.
Limites et bonnes pratiques
Le mécanisme de secours ne résout pas les conflits de définition : si les deux fichiers coexistent, seul Claude.md est pris en compte, les informations de AGENTS.md étant ignorées. Les équipes doivent donc veiller à nettoyer le répertoire pour éviter des configurations orphelines. De plus, aucune documentation supplémentaire n’est fournie sur la syntaxe exacte attendue dans AGENTS.md, ce qui peut entraîner des erreurs de parsing si le format diffère de celui de Claude.md. Enfin, le changelog ne précise pas de version précise pour ce changement, ce qui complique le suivi de compatibilité pour les environnements verrouillés.
