DeepSeek Harness : AGENTS.md ne s’applique pas en 2026

Votre fichier AGENTS.md existe, mais DeepSeek Harness se comporte comme s’il ne l’avait jamais lu.

La solution la plus rapide consiste à vérifier, dans cet ordre, le dossier de lancement, la racine de projet réellement sélectionnée, les fichiers d’instructions candidats, le contenu effectivement injecté, puis à refaire le test dans une nouvelle session après toute modification.

Cet article s’adresse à trois profils précis :

• vous avez déjà créé un AGENTS.md, mais l’Agent ne respecte toujours pas les règles du projet ;
• vous maintenez plusieurs niveaux d’instructions dans un monorepo ou une arborescence complexe ;
• vous avez déplacé le workspace vers un Mac distant et le comportement n’est plus identique.

Le problème n’est généralement pas la qualité rédactionnelle de la règle. Il vient plus souvent d’un mauvais chemin, d’une racine mal identifiée, d’un fichier concurrent, d’un contenu partiellement ignoré ou d’un ancien contexte de session.

Pourquoi un fichier présent peut-il rester invisible ?

Un scénario typique suffit à reproduire la panne : vous placez AGENTS.md à la racine du dépôt, vous le voyez dans votre éditeur, puis vous ouvrez une session DeepSeek Harness depuis un répertoire parent ou depuis un autre workspace sélectionné dans l’interface Web. Le fichier est bien présent sur le disque, mais il n’appartient pas forcément au contexte de travail utilisé par la session.

La documentation officielle précise que le processus dsh utilise son répertoire d’invocation comme emplacement système par défaut, tandis qu’une interface Web fraîche ne possède pas encore de workspace sélectionné. Vous devez donc distinguer trois éléments qui sont souvent confondus :

• le dossier depuis lequel dsh a été lancé ;
• le workspace choisi dans l’interface Web ;
• la racine effective du dépôt, repérée par un marqueur de projet ou par la configuration utilisée.

Le fichier peut aussi être ignoré pour des raisons plus discrètes :

• le nom est presque correct, mais la casse ou l’extension diffère ;
• le fichier appartient à un dépôt voisin dans un dossier parent ;
• un sous-projet possède ses propres instructions ;
• CLAUDE.md et AGENTS.md existent simultanément sans rôle clairement défini ;
• le contenu est lisible par le système de fichiers, mais dépasse ce que le chargeur peut intégrer au contexte ;
• la session a été créée avant la modification et conserve son ancien contexte.

DeepSeek Harness est encore présenté comme une version en développement, avec des changements incompatibles possibles. Il faut donc éviter d’attribuer à toutes les versions un ordre de recherche ou un comportement de surveillance des fichiers qui n’est pas confirmé par la documentation de votre installation. Consultez le référentiel officiel du projet et sa documentation d’architecture lorsque vous devez vérifier une évolution du chargeur.

DeepSeek Harness lit-il automatiquement AGENTS.md ?

Vous ne devez pas répondre simplement « oui » ou « non ». Le point vérifiable est que le projet officiel utilise bien AGENTS.md comme fichier d’instructions pour les Agents et documente également une relation avec CLAUDE.md. Cela ne prouve pas que chaque session, chaque profil et chaque répertoire le chargeront automatiquement dans toutes les versions. Le test utile consiste à observer une règle volontairement distinctive dans un dépôt de test, puis à demander à l’Agent de la restituer ou de l’appliquer sans lui donner le contenu dans votre message.

Avant la session : figez le workspace et la racine

Commencez par établir une trace minimale, avant d’ouvrir le compositeur de session. Ne modifiez encore aucun fichier de règles : vous cherchez d’abord à savoir quel environnement vous testez.

Dans un terminal, notez le chemin absolu du lancement :

pwd
printf '%s\n' "$DSH_HOME"

Si DSH_HOME est vide, ne le remplacez pas immédiatement par une valeur supposée. Notez simplement ce résultat et vérifiez ensuite la configuration réellement utilisée par votre profil. La documentation officielle indique que les profils et certains fichiers de configuration sont liés à $DSH_HOME, mais elle ne justifie pas de déduire une valeur universelle pour toutes les installations.

Dans l’interface Web, vérifiez ensuite le workspace sélectionné. Le guide utilisateur indique que vous devez ajouter et sélectionner le répertoire du projet avant de pouvoir composer une session. Comparez ce chemin avec celui obtenu dans le terminal, puis avec la racine du dépôt :

git rev-parse --show-toplevel

Cette commande n’est pas une preuve que DeepSeek Harness utilise automatiquement cette racine. Elle sert à comparer les trois repères et à révéler un décalage.

Vous pouvez aussi créer un dépôt de test indépendant, suffisamment petit pour éliminer les effets du code métier :

dsh-rule-test/
├── AGENTS.md
└── src/
    └── exemple.txt

Dans AGENTS.md, ajoutez une règle sans risque, par exemple : « Avant toute modification, l’Agent doit signaler le mot de contrôle LUMIÈRE-17 ». N’utilisez pas une règle destructive ou une instruction qui modifie réellement le dépôt. Le but est d’observer le chargement, pas de tester une permission.

Attention : un marqueur de projet peut empêcher la recherche de continuer vers un parent, mais vous ne devez pas supposer que le même mécanisme existe dans tous les profils. Vérifiez le réglage de racine dans la configuration officielle correspondant à votre version.

La restauration à ce stade est simple : si les chemins ne correspondent pas, arrêtez la session, relancez dsh depuis la bonne racine, sélectionnez explicitement le même dossier dans l’interface Web et recommencez avec le dépôt minimal.

Au premier chargement : identifiez le fichier réellement candidat

Une fois le workspace fixé, inventoriez les fichiers possibles avant de conclure à un défaut de DeepSeek Harness :

find .. -name AGENTS.md -o -name CLAUDE.md

Examinez les résultats dans leur ordre de proximité avec la racine effective. Dans un environnement réel, vous pouvez rencontrer :

• un fichier global dans votre répertoire utilisateur ;
• un fichier au niveau du dépôt ;
• un fichier dans un sous-projet ;
• un fichier local associé à un profil ou à une surcouche ;
• un lien symbolique dont la cible n’existe plus après migration.

Ne vous contentez pas de la commande ls. Contrôlez la cible des liens, la lisibilité et l’encodage :

ls -l AGENTS.md CLAUDE.md
file AGENTS.md
sed -n '1,80p' AGENTS.md

Le dépôt officiel de DeepSeek Harness est lui-même un cas intéressant : il contient AGENTS.md et CLAUDE.md, et précise que certains CLAUDE.md sont des liens symboliques vers le fichier réel. La règle documentée est d’éditer le fichier source plutôt qu’un lien ou une copie. Vous pouvez consulter les instructions officielles du dépôt pour comparer cette organisation.

Où placer AGENTS.md pour qu’il soit reconnu ?

Placez d’abord le fichier à la racine du workspace que vous avez explicitement sélectionné, puis vérifiez le comportement dans un sous-répertoire. Cette méthode est plus fiable que de commencer par un fichier global ou par une structure complexe. Si vous ajoutez des instructions à un niveau inférieur, considérez-les comme une règle locale à tester séparément, et non comme une extension automatiquement garantie de la règle racine.

La vérification doit produire un signal observable. Demandez par exemple :

1. de lire la règle de contrôle ;
2. de citer son identifiant ;
3. d’expliquer si elle vient du dépôt ou d’un niveau supérieur ;
4. de proposer une action qui respecte la règle sans exécuter cette action.

Si l’Agent répond seulement qu’il « suivra les conventions du projet », le test n’est pas concluant. Une réponse vérifiable doit reprendre le marqueur ou décrire une contrainte précise.

Dans un monorepo : comparez la racine et le sous-projet

Les erreurs de hiérarchie apparaissent souvent après un changement de répertoire. Une session ouverte depuis packages/audio peut ne pas présenter le même workspace context qu’une session ouverte depuis la racine du monorepo, même si vous voyez les mêmes fichiers dans l’explorateur.

Réalisez deux sessions distinctes :

• session A : workspace défini sur la racine du monorepo ;
• session B : workspace défini sur le sous-projet ;
• même demande de contrôle ;
• même fichier témoin ;
• même règle distinctive.

Ne comparez pas uniquement la réponse finale. Notez aussi :

• le chemin que l’Agent tente de lire ;
• la manière dont il nomme le projet ;
• les fichiers qu’il affirme avoir consultés ;
• les commandes qu’il propose ;
• la présence ou l’absence de la règle de contrôle.

Dans le dépôt officiel, les instructions de la racine renvoient à des instructions spécifiques pour packages/ et examples/, ce qui illustre une organisation par zones plutôt qu’un unique fichier géant. Un contenu répété peut être replié, résumé ou rendu moins visible lorsqu’il est présent à plusieurs niveaux. Le fait qu’une règle ne soit pas répétée mot pour mot dans la réponse ne prouve donc pas à lui seul qu’elle a été ignorée.

Que se passe-t-il si AGENTS.md et CLAUDE.md existent ensemble ?

Traitez cette coexistence comme une hypothèse à tester, pas comme une priorité universelle. Dans le projet officiel, CLAUDE.md peut être un lien vers AGENTS.md, ce qui évite deux sources concurrentes. Dans votre dépôt, deux fichiers indépendants peuvent contenir des règles contradictoires, des commandes différentes ou des consignes destinées à des outils distincts.

Pour isoler la cause, renommez temporairement l’un des deux fichiers dans le dépôt de test, puis recréez une session. Si le comportement change, vous avez identifié un conflit de candidats. La correction durable consiste à choisir une source principale, à reléguer les variantes dans des fichiers locaux clairement nommés et à éviter de répéter la même règle avec des formulations différentes.

Contenu et format : vérifiez la frontière d’ignorance

Un fichier peut être découvert, mais ne pas être entièrement exploitable. Plusieurs causes sont possibles :

• encodage inhabituel ou caractères de contrôle ;
• fichier tronqué pendant une synchronisation ;
• permissions différentes entre l’utilisateur du terminal et le processus Web ;
• contenu trop long par rapport au budget de contexte disponible ;
• mélange de règles permanentes, de documentation détaillée et d’exemples historiques ;
• sections contradictoires qui rendent la règle opérationnellement ambiguë.

Ne cherchez pas à résoudre le problème en agrandissant sans limite AGENTS.md. Une instruction stable doit rester courte, testable et applicable. Séparez plutôt :

• les invariants du projet : architecture, commandes obligatoires, restrictions ;
• les procédures détaillées : guide de publication, dépannage audio, pipeline vidéo ;
• les informations de contexte : historique, décisions anciennes, explications longues.

Pour contrôler les propriétés de base :

wc -l -c AGENTS.md
file --mime AGENTS.md
sed -n '1,120p' AGENTS.md

Le nombre d’octets obtenu est une observation de votre fichier, pas une limite officielle. Ne transformez donc pas une taille mesurée localement en seuil général. Le dépôt officiel documente des budgets de documentation et des mécanismes de vérification propres à son propre fonctionnement, mais ces règles ne constituent pas automatiquement les limites du chargeur de votre version.

Expérience utile : réduisez le fichier à trois règles non dangereuses et à un identifiant unique, puis ouvrez une session neuve. Si le test redevient concluant, réintroduisez les sections une par une. Vous saurez si le problème vient de la taille, d’un format particulier ou d’une contradiction.

La restauration est validée lorsque l’Agent restitue l’identifiant, applique la contrainte et continue à reconnaître le même fichier après une demande portant sur un autre sujet, par exemple une tâche de design, de montage vidéo ou d’organisation d’un projet audio.

Après modification : distinguez ancien contexte et défaut de surveillance

Modifier AGENTS.md pendant une session active ne permet pas de conclure que le chargeur surveille ou ne surveille pas le fichier. Votre session possède déjà un historique et peut conserver une représentation précédente des instructions.

Utilisez trois tests séparés :

1. Continuer la session existante. Demandez à l’Agent de comparer l’ancienne et la nouvelle règle, sans lui fournir le texte.
2. Créer une nouvelle session dans le même workspace. Répétez exactement la même demande de contrôle.
3. Redémarrer le processus ou le profil, puis créer une nouvelle session. Répétez encore le test.

Conservez les éléments observables :

• date et heure de la modification ;
• empreinte du fichier avant et après ;
• chemin du workspace ;
• identifiant de session ;
• réponse exacte de l’Agent ;
• action proposée ou exécutée.

Vous pouvez produire une empreinte sans exposer le contenu :

shasum -a 256 AGENTS.md

La différence entre les trois résultats vous indique où chercher. Si seule la nouvelle session voit la règle, l’ancien historique est l’explication la plus probable. Si aucune session ne la voit, revenez à la racine et aux candidats. Si le redémarrage du processus est nécessaire, inspectez le comportement du profil et sa configuration avant de parler de panne de surveillance.

La documentation du lanceur officiel indique que le répertoire d’invocation sert de workspace par défaut et que les profils composent plusieurs couches de configuration. Elle fournit également des commandes permettant d’inspecter une configuration composée sans démarrer complètement l’application. Utilisez la référence officielle du lanceur pour vérifier les options correspondant à votre profil.

Migration distante : vérifiez l’environnement avant le prompt

Après un déplacement vers un Mac distant, les règles peuvent sembler avoir disparu alors que le problème concerne la livraison du dépôt ou de l’environnement. Contrôlez systématiquement :

• le chemin absolu du workspace distant ;
• la valeur effective de DSH_HOME ;
• l’utilisateur qui lance le processus ;
• les permissions de lecture du fichier ;
• les liens symboliques et leurs cibles ;
• la présence du même commit ou de la même archive ;
• la configuration du profil utilisé ;
• la session réellement créée après le redémarrage.

Comparez localement et à distance un dépôt de référence contenant un seul fichier AGENTS.md, une règle de contrôle et une tâche sans risque. Ne comparez pas deux projets différents, car une différence de réponse pourrait venir du contenu ou du modèle plutôt que de l’environnement.

Pour les permissions, vérifiez à la fois le propriétaire et la lecture effective :

id
ls -l AGENTS.md
test -r AGENTS.md && echo "lecture OK" || echo "lecture refusée"

Le guide officiel de configuration indique que $DSH_HOME héberge notamment les fichiers de réglages et les références de credentials. Cela ne signifie pas que vous devez copier aveuglément tout le répertoire lors d’une migration : les secrets, les sessions et les profils n’ont pas le même rôle. Consultez la documentation officielle de configuration, puis livrez séparément le code, les règles, la configuration nécessaire et les secrets gérés par votre procédure d’exploitation.

Si l’environnement distant ne peut pas être rendu identique, adoptez un retour propre :

• workspace temporaire dédié ;
• copie contrôlée du dépôt ;
• règle minimale ;
• nouvelle session ;
• test de référence ;
• ajout progressif des fichiers locaux.

La séquence de validation à conserver

Utilisez cette liste avant de modifier encore vos consignes :

• [ ] J’ai noté le dossier depuis lequel dsh est lancé.
• [ ] J’ai relevé le workspace choisi dans l’interface Web.
• [ ] J’ai comparé ces chemins avec la racine du dépôt.
• [ ] J’ai vérifié le marqueur ou le mécanisme de racine utilisé par mon profil.
• [ ] J’ai listé les fichiers AGENTS.md et CLAUDE.md accessibles.
• [ ] J’ai contrôlé les liens symboliques, l’encodage et les permissions.
• [ ] J’ai testé une règle distinctive dans un dépôt minimal.
• [ ] J’ai comparé la session racine et la session ouverte dans un sous-répertoire.
• [ ] J’ai séparé les règles stables du contexte documentaire volumineux.
• [ ] J’ai testé ancienne session, nouvelle session et redémarrage.
• [ ] J’ai conservé les chemins, empreintes et réponses observées.
• [ ] J’ai répété le même test après migration vers l’environnement distant.

Si une seule case importante reste indéterminée, ne réécrivez pas encore le prompt. Vous risquez de masquer la cause au lieu de la corriger.

Pour organiser une utilisation distante ou plusieurs environnements de développement, vous pouvez aussi comparer les scénarios proposés dans nos cas d’usage de Mac distant et consulter la FAQ de KVMFLUX lorsque la question concerne l’accès, la continuité de session ou la livraison de l’environnement.

Quand votre environnement actuel devient-il le vrai problème ?

Si vos tests locaux réussissent mais que les règles disparaissent après migration, votre difficulté n’est probablement plus AGENTS.md. Un poste local peut masquer des dépendances implicites : chemin utilisateur différent, profil conservé, lien symbolique intact, permissions déjà configurées ou processus jamais redémarré.

À l’inverse, un environnement distant mal livré présente souvent quatre défauts concrets : workspace sélectionné au mauvais endroit, DSH_HOME non aligné, droits de lecture incomplets et sessions anciennes réutilisées. Les corrections de prompt ne répareront aucun de ces écarts.

La location d’un Mac via KVMFLUX devient intéressante si vous avez besoin d’un environnement temporaire pour valider un dépôt, reproduire une migration, tester un monorepo ou comparer un flux audio, vidéo ou design avec un workspace stable. Vous évitez alors de consacrer un poste local à une configuration provisoire, tout en gardant la possibilité de vérifier précisément les chemins, les permissions et les nouvelles sessions. En revanche, l’achat d’un Mac reste plus cohérent pour une charge lourde permanente, un usage quotidien sans interruption ou un besoin d’accès physique aux périphériques. Pour un essai court et contrôlé, consultez les options de location Mac seulement après avoir défini votre protocole de validation : le matériel ne compensera pas une racine de projet mal sélectionnée.

Pour aller plus loin

• Guide de configuration de DeepSeek Harness dans un pipeline automatisé
• Mettre en place un runner auto-hébergé sur un Mac distant
• Comprendre les plugins et les standards des agents IA