> ## Content Index
> Fetch the complete content index at: https://www.sfeir.dev/llms.txt
> Use this file to discover other available public pages before exploring further.

# Documentation exécutive : vos articles deviennent des compétences IA
- URL: https://www.sfeir.dev/documentation-executive-agents-ia/
- Published: 2026-10-08T13:08:49.000Z
- Updated: 2026-10-08T13:08:49.000Z
- Description: Un « apply <url>.md » suffit à faire appliquer un article de blog par un agent de codage. Ce que cela change pour ceux qui publient de la documentation technique.
- Author: Romain Lespinasse
- Tags: agents IA, LLM, GEO, Documentation, best practices

## Un prompt, une URL

Un lundi matin, je voulais mettre en place sur mon propre dépôt ce que documentait [un article de sfeir.dev sur Dependabot](https://sfeir.dev/automatiser-dependabot-sans-perdre-le-controle-de-vos-mises-a-jour/?ref=sfeir.dev). Le parcours classique consiste à rouvrir l'article, relire chaque étape et la retranscrire dans son code. J'ai plutôt ouvert mon agent de codage et tapé une seule ligne :

```text
> apply https://www.sfeir.dev/automatiser-dependabot-sans-perdre-le-controle-de-vos-mises-a-jour.md

```

Pas de copier-coller ni de relecture pas à pas : le prompt contient une instruction, une URL et un `.md` à la fin, et l'agent a exécuté.

`apply` n'est pas une commande réservée : c'est une instruction en langage naturel, que l'agent interprète lui-même en allant chercher le contenu de l'URL avec son outil de récupération web. La plupart des agents de codage en disposent, avec des limites variables selon l'outil (autorisation par domaine, résumé du contenu, troncature des longs textes). Aucune extension à installer ici, mais le texte brut n'arrive pas forcément tel quel.

Ce geste illustre un changement de destinataire pour tout ce qu'on publie en ligne : un article de blog technique n'est plus seulement écrit *pour* un humain qui va le lire, le comprendre, puis retranscrire ce qu'il a compris dans son code. Il est aussi écrit *pour* une machine qui va le parser, en extraire des instructions, et les appliquer directement.

C'est le passage d'une documentation descriptive à une documentation exécutive. Cet article regarde les deux côtés : ce que fait le lecteur qui confie un article à son agent, et ce que change l'écriture pour ceux qui publient. Le sujet rejoint la réflexion sur la [structure Diátaxis au prisme des LLMs](https://sfeir.dev/diataxis-au-pays-des-llms/?ref=sfeir.dev), qui organise la documentation en tutoriels, guides, explications et références pour un lecteur qui n'est plus seulement humain.

## De l'article-tutoriel à la directive exécutable

Le tutoriel classique fonctionne en trois étapes cognitives : le lecteur lit, comprend le principe général, puis traduit ce principe dans son propre contexte. Cette traduction (adapter le nom des variables, ajuster à la stack du projet, gérer les cas particuliers) a toujours été le vrai travail. L'article donnait la direction, le développeur faisait le chemin.

Un agent de codage procède autrement. Il peut lire les instructions, les confronter au code existant dans le dépôt courant, et produire directement le diff qui applique la recommandation. La traduction n'est plus faite par le lecteur, elle est déléguée à l'agent, à chaque exécution. L'agent peut se tromper : un diff plausible n'est pas forcément un diff correct, et la validation reste humaine, par la revue du diff et la CI. L'article Dependabot lui-même pose des tests fiables comme prérequis à l'auto-merge : sur un dépôt sans tests, un `apply` donnerait un résultat à relire avec d'autant plus d'attention.

Cela change la nature de ce qu'on publie. Un article de blog technique, une ADR (*Architecture Decision Record*), une SOP (*Standard Operating Procedure*) d'équipe, tous ces formats deviennent des sources que l'IA peut ingérer à la volée. Dans cet article, une compétence désigne une procédure documentée qu'un agent peut appliquer. Pas besoin de l'intégrer dans un pipeline d'ingestion, de l'indexer dans une base vectorielle ou de la copier dans un fichier de config local : l'agent va chercher la compétence là où elle vit, au moment où il en a besoin.

Cela ne dispense pas d'écrire pour des humains. Un article qui fonctionne comme compétence pour agent doit d'abord rester lisible, structuré, argumenté : c'est justement cette structure qui le rend exploitable par une machine.

À ne pas confondre avec la skill packagée d'un agent comme Claude Code ([un fichier SKILL.md versionné, chargé selon sa description](https://sfeir.dev/les-skills-donner-un-vrai-metier-a-votre-agent-ia/?ref=sfeir.dev)) : ici, la compétence n'est pas empaquetée pour l'agent, elle est simplement écrite pour des humains et devient exploitable telle quelle. La distinction rejoint celle entre [skills et tools](https://sfeir.dev/skills-vs-tools-la-difference-fondamentale-dans-un-agent-ia/?ref=sfeir.dev) : un article-compétence se rapproche d'une skill (une ressource découverte et chargée à la demande) plutôt que d'un outil appelé de façon déterministe.

## Pourquoi cibler le `.md` brut plutôt que la page web

Le détail qui saute aux yeux dans le prompt d'ouverture, c'est le `.md` collé en fin d'URL : non pas la page HTML publiée, mais sa version Markdown brute. Cette route est exposée par la plateforme qui fait tourner sfeir.dev, qui sert le contenu source de chaque article sur simple ajout de l'extension. Tous les sites ne l'offrent pas. Pour vérifier qu'un site la propose, un `curl https://exemple.com/mon-article.md` suffit : si la réponse est du Markdown, la route existe.

Une page HTML de blog embarque un header de navigation, un footer avec les liens vers les réseaux sociaux, des scripts de tracking, des blocs de suggestions d'articles connexes, parfois un bandeau de cookies. Un agent doit traverser ce bruit pour en extraire le contenu utile, quand il y arrive : le rendu JavaScript ou les protections anti-scraping peuvent bloquer l'accès.

Le Markdown brut écarte ce problème. Titres, listes, blocs de code et citations arrivent déjà dans une structure sémantique claire, sans balise `<nav>` ni `<div class="cookie-banner">` à filtrer. Chaque caractère de markup inutile consommé par le contexte de l'agent est aussi un token (une unité de texte traitée par le modèle) qui aurait pu servir à raisonner sur le vrai contenu, un arbitrage proche de celui qui se joue lorsqu'on [réduit sa consommation de tokens dans Claude Code](https://sfeir.dev/reduire-ses-tokens-claude-code-ce-que-valent-vraiment-les-plugins/?ref=sfeir.dev). Les modèles ont aussi vu beaucoup de Markdown (README, documentation technique, tickets) : c'est un format qu'ils lisent sans nettoyage préalable.

Côté convention, [llms.txt](https://llmstxt.org/?ref=sfeir.dev) est une proposition qui liste explicitement les ressources d'un site à donner à lire à un agent. sfeir.dev l'applique : son [llms.txt](https://sfeir.dev/llms.txt?ref=sfeir.dev) indique justement qu'on obtient le Markdown d'un article en ajoutant `.md` à son URL. L'intention est d'exposer une interface pensée pour un lecteur machine, pas seulement pour un moteur de recherche, dans la logique du passage [du SEO au GEO](https://sfeir.dev/google-est-mort-vive-google/?ref=sfeir.dev) (*Generative Engine Optimization*).

Ce mécanisme relève de la récupération de contexte « juste à temps » (*just-in-time retrieval*) : un agent va chercher une compétence au moment où il en a besoin, directement à la source. Cloudflare propose une approche voisine avec [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/?ref=sfeir.dev), qui sert du Markdown aux agents à la place du HTML. Servir une version `.md` de ses contenus n'est donc plus un détail technique pour les moteurs de recherche, mais une façon d'exposer une interface pour les agents.

## Une compétence « juste à temps », complémentaire du RAG et des fichiers de config

Pour donner du contexte à un agent, plusieurs approches existent. Le RAG (*Retrieval-Augmented Generation*), une forme de [grounding](https://sfeir.dev/quest-ce-que-le-grounding/?ref=sfeir.dev), consiste à découper sa documentation, la transformer en vecteurs (les *embeddings*) et retrouver les passages les plus proches de la question, le plus souvent dans une base vectorielle. Il convient à de grands corpus, et son pipeline demande un entretien continu. Les fichiers de règles locaux comme `.cursorrules`, `CLAUDE.md` ou `AGENTS.md`, lus par l'agent au démarrage, conviennent aux règles permanentes d'un projet : leur contenu est souvent chargé en permanence dans le contexte, même quand la règle ne sert que rarement. D'autres options existent, comme les serveurs MCP de documentation ou les skills packagées.

Le prompt `apply <url>.md` ajoute une voie supplémentaire : la récupération juste à temps d'une compétence. Pas d'indexation préalable, pas de fichier à maintenir localement. La compétence vit à une URL stable, mais son contenu peut changer sans préavis, et l'agent va la chercher uniquement quand elle est pertinente.

Ces approches ne répondent pas exactement à la même question. Le RAG résout un problème de découverte : retrouver, parmi un corpus que l'utilisateur ne connaît pas dans le détail, le document pertinent pour sa requête. Le chargement à la demande résout un problème d'application : une fois qu'on sait déjà quel article documente la pratique voulue, l'exécuter sans étape intermédiaire. Les deux se complètent, un RAG bien construit pouvant très bien restituer l'URL `.md` à charger plutôt que le contenu indexé lui-même.

![Trois robots agents côte à côte, chacun avec sa façon de recevoir du contexte : une base de documents indexée, un fichier de règles local, une fiche unique chargée à la demande via une URL](https://storage.ghost.io/c/0b/31/0b31478e-a66a-46f1-8c34-d44388e21192/content/images/2026/10/approches-image.webp "RAG, config locale ou chargement à la demande")

RAG, config locale ou chargement à la demande

> L'agent n'est plus obligé de charger tout le savoir de l'équipe en permanence : il peut le charger une fois, juste à temps, quand la tâche l'exige.

## Sécurité : charger une URL, c'est charger des instructions

Cette agilité a un coût : pas de garantie de disponibilité de l'URL, pas de contrôle de version local, une dépendance à un service externe, et un contenu qui peut changer entre deux exécutions. C'est aussi la réserve principale de l'approche. Appliquer le contenu d'une URL, c'est donner à un agent qui a accès au dépôt les instructions d'un tiers qu'on ne maîtrise pas. Une source compromise ou malveillante devient un vecteur d'[injection de prompt indirecte](https://sfeir.dev/www-sfeir-dev-ia-securite-chatbot-llm-france-europe/?ref=sfeir.dev), c'est-à-dire un texte hostile glissé dans la page lue par l'agent, qui le prend pour une consigne.

Les enjeux dépassent le diff : un agent peut exécuter des commandes, modifier des workflows CI ou lire des secrets, ce qui compte d'autant plus quand l'exemple touche `.github/workflows`. Quelques précautions limitent l'exposition :

- garder l'approbation des commandes activée dans l'agent ;
- lire le `.md` avant de l'appliquer, surtout si la source n'est pas la vôtre ;
- travailler sur une branche dédiée et relire le diff avant de l'accepter ;
- ne charger que des sources dont l'auteur est connu, sans oublier qu'une source de confiance peut elle aussi être modifiée ou compromise.

Pour des règles critiques et systématiques d'un projet, le fichier de règles local reste le bon outil. Pour diffuser une pratique, une procédure ou une recette qu'on ne veut pas dupliquer dans chaque dépôt, le chargement à la demande est un bon compromis.

## Écrire pour deux lecteurs : humain et agent

Un article de blog technique était avant tout un acte de communication : démontrer une expertise, nourrir la marque employeur, se positionner dans les résultats de recherche. Avec la documentation exécutive, publier un article devient aussi un acte de distribution d'un standard d'ingénierie. Un client, un nouveau collaborateur ou un développeur externe qui découvre l'article n'a plus besoin de le lire ligne par ligne pour en tirer profit : il peut demander à son propre agent de l'appliquer sur son projet.

Cela change deux choses pour les équipes qui publient. La rigueur d'écriture devient une exigence technique, pas seulement éditoriale : un article ambigu ou mal structuré ne se contente plus de perdre un lecteur humain en cours de route, il peut produire une exécution incorrecte côté agent. La granularité compte aussi : une pratique bien isolée, avec ses prérequis et ses limites explicites, s'applique proprement, alors qu'un article qui mélange plusieurs sujets devient plus difficile à transformer en action ciblée.

La rigueur d'écriture technique a toujours demandé de la clarté, une structure explicite et des étapes vérifiables (la même exigence qui veut qu'[un agent de code ne doive jamais affirmer ce qu'il n'a pas vérifié](https://sfeir.dev/agent-code-verification-faits-pull-request/?ref=sfeir.dev)). Pour un article destiné aussi aux agents, quelques pistes peuvent aider, à adapter au sujet sans en faire une obligation :

- une pratique par article, avec un périmètre explicite ;
- les prérequis en tête (versions, outils, tests attendus) ;
- des étapes numérotées et des blocs de code complets ;
- un critère de vérification à la fin ;
- une date de mise à jour, car un article daté s'exécute sans avertissement ;
- les cas où il vaut mieux ne pas appliquer la recette.

Le non-déterminisme reste à prendre en compte : le même `apply` peut produire des diffs différents d'une exécution à l'autre, ce qui rend la relecture indispensable.

## Conclusion

Le prompt `apply <url>.md` illustre une évolution : la frontière entre documentation et outillage s'estompe. Un article technique devient une ressource consultable par des humains et exécutable par des agents, et il gagne à être daté, relu et maintenu avec le même soin que du code.

Les équipes qui publient leurs pratiques dans ce format (Markdown propre, granularité claire et instructions non ambiguës) peuvent distribuer directement leurs standards d'ingénierie, avec la relecture du diff comme garde-fou.