J'ai renommé tous mes fichiers Markdown — et mon agent IA est devenu 10 fois plus utile

Je vais vous partager une leçon qu'il m'a fallu trois semaines pour assimiler. Et quand l'évidence m'a frappé, j'étais furieux contre moi-même.

Mon OpenClaw tournait. Le modèle était excellent (Sonnet), bien configuré. Le moteur de recherche, Sonar Pro Search, était opérationnel. Le heartbeat battait toutes les 15 minutes. Slack était connecté, l'équipe pouvait interagir avec l'agent. Tout l'édifice était en place. Et pourtant — l'agent retrouvait mal les fichiers. Il confondait les données. Il me ressortait des informations issues du mauvais document. Parfois, il hallucinait purement et simplement des chemins d'accès inexistants.

J'ai passé des heures à accuser le modèle. Ou le moteur d'embeddings. Ou une variable obscure. En réalité, le problème était sous mon nez depuis le début.

Mes fichiers s'appelaient YouTube Secrets.md. Business Ideas (v2).md. Notes réunion 14 mars.md. Avec des espaces. Des parenthèses. Des accents. Des majuscules aléatoires. Un chaos total. Et c'est ce chaos structurel qui rendait mon agent à moitié aveugle.

Le parallèle qui a tout changé

Venant du SEO, j'ai eu un déclic en observant l'arborescence de mon serveur. C'est l'exact équivalent du problème des "URL slugs". Il y a 15 ans, le web était rempli d'URLs du style /Notre Offre Spéciale!/ et on s'étonnait que Google indexe mal nos pages. Il a fallu une décennie pour que toute l'industrie comprenne que /offre-speciale/ est la norme absolue, et que les espaces, les accents ou les majuscules dans une URL constituent une hérésie technique.

Nous en sommes exactement au même point avec les fichiers Markdown hébergés sur nos serveurs. À la différence que cette fois, ce n'est pas Googlebot qui lit les fichiers, c'est l'agent IA. Et la réaction est identique : un nom de fichier standardisé, il le comprend instantanément. Un nom de fichier erratique le ralentit, gaspille de la puissance de calcul (compute), et dans le pire des cas, génère des hallucinations.

Le jour où j'ai fait ce parallèle, j'ai tout renommé. La différence a été immédiate.

Ce qui se passe techniquement quand vous mettez un espace dans un nom de fichier

Pour ceux qui souhaitent comprendre la mécanique sous-jacente : lorsque vous créez un fichier YouTube Secrets.md sur un serveur Linux, trois phénomènes se produisent en coulisse.

D'abord, Linux encode l'espace en %20 ou exige des guillemets d'échappement à chaque commande. Chaque fois que l'agent doit manipuler ce fichier — le lire, le déplacer, le référencer dans un script — il doit gérer cette ambiguïté. Ce n'est pas une incapacité technique de sa part. C'est de la puissance de calcul gaspillée pour résoudre une friction que vous avez vous-même introduite.

Ensuite — et c'est le point qui a mis du temps à m'apparaître clairement — le moteur de vector embeddings d'OpenClaw indexe les noms de fichiers comme des tokens sémantiques. youtube-secrets.md produit deux tokens propres : "youtube" et "secrets". L'intention est claire. En revanche, YouTube Secrets (draft v2 final).md produit une bouillie de tokens parasites — "draft", "v2", "final" — qui polluent l'espace vectoriel. Quand vous effectuez ensuite une requête liée à YouTube, le moteur doit filtrer ce bruit. Et la précision s'effondre.

Le troisième phénomène est le plus insidieux. L'agent raisonne par analogie structurelle. Si vos fichiers suivent un modèle cohérent, il peut prédire l'emplacement d'un fichier avant même de le chercher. Par exemple, si votre convention est business/research/paul-graham-startup-advice.md, l'agent va inférer que votre recherche sur les prix se trouve dans business/research/pricing-strategy-saas.md. Il va directement au bon endroit. Mais si vos nomenclatures sont anarchiques — un fichier en majuscules, un autre avec des espaces, un troisième avec des parenthèses — l'inférence est brisée. L'agent doit scanner tout le dossier comme un stagiaire qui ouvrirait chaque tiroir un par un.

Les règles que j'applique désormais (et que je fais respecter par l'agent)

Après avoir tout renommé — et je ne vous cache pas que l'opération m'a pris une bonne demi-journée —, j'ai instauré des règles. Six règles non négociables. Fondamentalement, elles se résument à un seul principe : traitez chaque nom de fichier comme un URL slug. Si vous ne l'intégreriez pas dans une URL, ne le mettez pas dans un nom de fichier.

L'arborescence — et comment j'ai structuré la mienne

Le nommage ne se limite pas aux fichiers. Les dossiers obéissent à la même exigence.

Un dossier bien nommé devient un "namespace sémantique". Quand un collaborateur demande à l'agent "trouve-moi notre stratégie de pricing", l'IA devrait pouvoir naviguer vers business/sales/pricing-strategy.md par pure déduction, sans scanner l'intégralité du serveur. Cela ne fonctionne que si l'architecture est logique et les noms prévisibles.

Voici ma structure actuelle. Elle évolue régulièrement, mais le squelette reste intact :

Aucun espace. Aucune majuscule. Aucun accent. Chaque dossier est un mot unique ou un terme composé relié par des tirets. C'est le même principe qu'un fichier robots.txt à la racine d'un site web : une structure optimisée pour la lecture machine. Nous avons passé 30 ans à structurer le web pour Googlebot. Aujourd'hui, nous structurons nos serveurs pour nos agents IA. La logique est strictement identique.

Les fichiers à la racine — ceux situés directement sous business/ et non dans un sous-dossier — sont les fichiers stratégiques. C'est l'équivalent de la page d'accueil de votre site. L'agent les consulte en priorité.

La méthode qui a révolutionné mes recherches

Il existe un scénario que tout le monde accepte par défaut. Vous effectuez une recherche complexe sur Perplexity ou ChatGPT (par exemple : "comment Paul Graham recommande aux startups de parler à leurs premiers clients"). Vous obtenez une excellente synthèse. Vous la lisez. Vous fermez l'onglet.

Et l'information meurt. Le fichier est perdu dans l'historique d'un chatbot que personne n'ouvrira plus jamais.

Trois mois plus tard, le même sujet revient sur la table lors d'une réunion. Les détails se sont évaporés. On relance la recherche. On perd 30 minutes. C'est une déperdition de temps aberrante que tout le monde subit comme une fatalité.

Désormais, mon protocole est le suivant :

Le résumé dans le chat, je le lis et je passe à autre chose. L'enjeu n'est pas là. L'enjeu, c'est que paul-graham-customer-development.md existe désormais sur le serveur. Le moteur d'embeddings l'a indexé. La prochaine fois que quelqu'un abordera le sujet du customer development, ce fichier remontera automatiquement pour fournir du contexte. Sans requête préalable.

Et c'est ici que la nomenclature prend tout son sens. paul-graham-customer-development.md contient quatre tokens sémantiques denses. Le moteur peut le corréler à n'importe quelle question future sur la validation client ou les startups early-stage. Si j'avais nommé ce document recherche-3.md ou notes-pg.md, l'agent ne ferait jamais la connexion. C'est du pur SEO interne : /blog/paul-graham-customer-development/ se positionne. /blog/post-3/ reste invisible. Le nommage est l'optimisation.

Le heartbeat comme gardien de l'arborescence

Une mécanique que j'ai découverte par accident : le heartbeat (ce fichier exécuté automatiquement toutes les 15 minutes) peut servir à bien d'autres choses qu'aux simples mises à jour du système.

J'y ai intégré une instruction forçant l'agent à auditer la cohérence de l'arborescence à chaque battement. Il détecte les doublons. Il repère les fichiers non modifiés depuis plus de 90 jours (candidats à l'archivage). Et surtout, il sanctionne les violations de convention de nommage. Si un collaborateur crée un fichier contenant un espace ou une majuscule, l'agent le renomme automatiquement et envoie une notification sur Slack.

Cela semble mineur en apparence. Mais passé le cap des 200 fichiers Markdown, c'est la frontière entre un système pérenne et un marécage de données. Sans cette surveillance automatisée, l'entropie l'emporte toujours. Un collaborateur est pressé, il crée Notes call vendredi.md, et la corruption de l'index commence.

L'impact sur Slack — la validation par l'usage

Cette discipline de nommage révèle sa véritable puissance lorsque l'agent est déployé sur Slack et que l'équipe commence à le solliciter.

Récemment, mon développeur a tapé : @OC1 montre-moi le playbook d'onboarding. L'agent a navigué directement vers business/playbooks/ et a extrait onboarding-new-team-member.md en une fraction de seconde. Pourquoi ? Parce que le nom du fichier contient "onboarding", "new", "team", "member" — soit les tokens exacts de la requête. Si le fichier s'était appelé playbook-7.md, l'agent aurait dû ouvrir et analyser chaque document du dossier pour trouver le bon. C'est chronophage, cela consomme des tokens inutilement, et l'utilisateur patiente.

Autre exemple : un commercial a demandé @OC1 quelles erreurs éviter en négo client ?. L'agent a croisé les données de mistakes.md avec les dossiers sales/ et reminders/ pour formuler une réponse ultra-contextualisée. Cette synthèse n'est possible que parce que les noms de fichiers et de dossiers agissent comme des ancres sémantiques que le moteur d'embeddings relie entre elles. Si les nomenclatures étaient opaques, ce croisement cognitif serait inopérant.

C'est là l'aboutissement de la démarche : bâtir un moteur de recherche interne, alimenté par votre propre capital intellectuel, structuré par vos conventions, et interrogeable en langage naturel par toute l'entreprise. Mais la mécanique exige un carburant irréprochable.

Pour conclure

Le web a mis 15 ans à standardiser les URL slugs. Nous ne disposons pas d'une telle marge avec les agents IA. D'ici six mois, la rigueur de votre nomenclature deviendra un avantage concurrentiel direct et mesurable.

La doctrine est simple : si cela n'a pas sa place dans une URL, cela n'a pas sa place dans le nom de vos fichiers. Des tirets. Des minuscules. De la description. Pas d'espaces. Pas de caractères spéciaux. Pas de versioning manuel.