AGENTS IA // WORKFLOWS DÉVELOPPEUR

Arrêtez d'utiliser CLAUDE.md

Vos règles d'ingénierie ne doivent pas appartenir à une IA spécifique. Voici comment standardiser le contexte de vos projets pour l'ère multi-agents avec AGENTS.md.

Florian Métoz · Sep 2026 · 5 min de lecture

Vos règles d'ingénierie ne doivent pas appartenir à une IA spécifique. Voici comment standardiser le contexte de vos projets pour l'ère multi-agents avec AGENTS.md.

Je suis développeur logiciel depuis plus de 20 ans. Ces deux dernières années, j'ai travaillé intensément avec les outils de code assistés par IA.

Savez-vous ce qui a été le plus difficile ? Ce n'était pas d'apprendre à utiliser Claude, Codex, Gemini ou Kimi.

Le plus difficile est de bâtir un workflow qui reste fiable lorsque l'outil change.

Et les outils changent constamment. Les modèles s'améliorent, les grilles tarifaires évoluent et de nouveaux agents apparaissent. Les produits existants introduisent de nouvelles capacités, de nouvelles contraintes et de nouveaux formats de configuration.

Mais nos principes d'ingénierie ne devraient pas avoir à changer chaque fois que notre assistant IA change.

Arrêtez d'utiliser CLAUDE.md — Standardiser le contexte projet avec AGENTS.md

C'est pourquoi je suis convaincu que nous devons cesser de dupliquer les informations entre CODEX.md, KIMI.md, CLAUDE.md et GEMINI.md. À la place, nous devrions utiliser un fichier neutre et portable : AGENTS.md.

Ce n'est pas seulement une question de nom de fichier

CLAUDE.md n'est pas un mauvais fichier en soi. Si votre équipe utilise exclusivement Claude Code, il est très pratique. Il fonctionne parfaitement au sein de l'écosystème Anthropic.

Le problème survient lorsqu'un fichier propriétaire devient le réceptacle canonique de connaissances qui appartiennent en réalité au projet.

Les instructions de votre projet ne sont pas la propriété de Claude. Elles appartiennent à votre équipe. Elles décrivent comment le dépôt doit être compris, modifié, testé et maintenu, quel que soit l'outil d'IA utilisé.

C'est précisément pourquoi AGENTS.md est crucial : il nous offre un espace neutre pour définir comment n'importe quel agent IA doit interagir avec le projet.

Un signal fort de l'industrie

Claude Code prend désormais en charge explicitement AGENTS.md. Lorsqu'aucun CLAUDE.md n'est présent dans un dossier, Claude Code recherche et utilise automatiquement AGENTS.md (un comportement configurable via /config).

« Claude Code supporte désormais AGENTS.md. Nous l'utiliserons en repli si CLAUDE.md n'est pas spécifié. En espérant que cela vous aide :) »
— Addy Osmani sur X (anciennement Twitter)

Même si cela peut ressembler à une simple mise à jour de compatibilité, il s'agit en fait d'un signal majeur : AGENTS.md devient une convention partagée. L'écosystème s'oriente vers un monde où les mêmes instructions de projet peuvent être consommées par différents agents. C'est exactement la direction que nous devons encourager.

Un seul projet, plusieurs agents : le piège de la duplication

Aujourd'hui, un même dépôt peut accumuler une multitude de fichiers d'instructions :

CLAUDE.md
CODEX.md
GEMINI.md
KIMI.md
…

Au début, cela semble inoffensif. On copie les mêmes consignes dans chaque fichier, on adapte quelques détails et on avance. Mais la duplication engendre la dérive.

Un fichier est mis à jour, l'autre non. Une règle de test change à un endroit mais est oubliée ailleurs. Un nouveau développeur lit les instructions d'un outil et pense qu'elles représentent l'ensemble du projet. Au fil du temps, vos agents reçoivent des versions contradictoires des exigences de votre équipe.

Ce n'est pas un problème d'outillage. C'est un problème de gestion des connaissances.

Une architecture plus saine est pourtant simple :

Votre Projet/
├── AGENTS.md      <-- Source unique de vérité
├── README.md
├── docs/
└── .agents/

Un seul projet. Une seule source de vérité. Plusieurs agents compatibles.

Garder la connaissance du projet indépendante de l'outil

J'alterne régulièrement entre différents outils de code IA. Certains excellent dans la phase exploratoire, d'autres sont plus véloces ou disposent de meilleures intégrations. Certains mènent de grands refactorings plus efficacement, tandis que d'autres sont plus économiques ou s'exécutent en local.

Je veux pouvoir choisir le bon outil pour la bonne tâche sans réécrire les instructions du projet chaque fois que je change d'assistant.

Ce principe s'applique à de nombreux domaines du développement logiciel :

Les règles métier ne doivent pas appartenir à un framework.
Les pratiques d'ingénierie ne doivent pas appartenir à un IDE.
Les instructions du projet ne doivent pas appartenir à un seul assistant IA.

Les outils sont interchangeables. La connaissance derrière le projet doit rester portable.

Que doit contenir AGENTS.md ?

La règle d'or : AGENTS.md doit décrire le projet, pas la personnalité du modèle.

Ce fichier ne doit pas être un gigantesque prompt. Il n'a pas besoin de déclarer : « Tu es un développeur senior expert doté d'une capacité de raisonnement exceptionnelle… » Ce genre d'instruction est générique, fragile et au fond inutile.

À la place, AGENTS.md doit expliquer de manière concise le fonctionnement de l'équipe.

Exemple de structure pour AGENTS.md

## Travailler dans ce dépôt

Lire la documentation pertinente avant d'effectuer des modifications structurelles.
Garder les changements courts et ciblés.
Préférer les solutions simples et explicites aux abstractions prématurées.
Ajouter ou mettre à jour les tests lors de chaque modification de comportement.
Ne pas modifier les API publiques sans mettre à jour la documentation.
Respecter la configuration de formatage et de linting versionnée dans le dépôt.

Consignes du projet

Commencer par le README pour les instructions d'installation.
Rechercher les patterns existants avant d'introduire de nouvelles abstractions.
Consulter le répertoire docs/ lors d'interventions sur des zones méconnues.

Le document doit être suffisamment court pour être lu régulièrement, suffisamment précis pour être utile, suffisamment clair pour être relu par des humains et suffisamment structuré pour être suivi par des agents.

La configuration spécifique aux outils a toujours sa place

Adopter AGENTS.md ne signifie pas que chaque outil IA doit se comporter à l'identique. Les répertoires et fichiers dédiés à un outil ont toujours leur utilité :

.claude/
.codex/
.cursor/

C'est tout à fait légitime lorsqu'ils renferment de véritables détails d'intégration — tels que des hooks spécifiques, des commandes personnalisées, la gestion des permissions ou des configurations d'environnement local.

Gardons les instructions du projet portables. Gardons les configurations d'outils spécifiques. Ce que nous devons proscrire, c'est de dupliquer une seconde version des règles d'ingénierie de l'équipe dans chaque répertoire d'outil.

Conseil de pro : Le dossier .agents/ peut également héberger des compétences (skills) multi-LLM. Cela permet de garder votre AGENTS.md épuré tout en étendant facilement les capacités de vos IA avec des scripts et outillages sur mesure.

L'avenir est multi-agents

Je ne crois pas que l'avenir du développement logiciel appartiendra à un seul agent de code IA. Les outils vont continuer à se spécialiser : cadrage, implémentation, revue de code, exécution locale. Les équipes vont les combiner.

Le flux de travail gagnant ne sera pas forcément celui qui utilise le meilleur outil isolé. Ce sera celui qui permet d'interchanger les outils sans perturber le processus d'ingénierie sous-jacent.

Cela exige un socle stable de connaissances projet. AGENTS.md peut incarner ce socle.

Les outils vont changer. Les modèles vont évoluer. Les coûts vont fluctuer. Nos projets ne devraient pas avoir à être réécrits à chaque fois.

Your engineering rules shouldn’t belong to a specific AI. Here is how to standardize your project knowledge for the multi-agent era.

I have been a software developer for more than 20 years. For the last two, I have been working seriously with AI coding tools.

Do you know what the hardest part has been? It hasn’t been learning how to use Claude, Codex, Gemini, or Kimi.

The hardest part is building a workflow that remains reliable when the tool changes.

And the tools do change. Models improve, pricing fluctuates, and new agents appear. Existing products introduce new capabilities, new limitations, and new configuration formats.

But our engineering principles should not have to change every time our AI assistant does.

Stop Using CLAUDE.md — Standardize project knowledge with AGENTS.md

That is why I believe we must stop duplicating information across CODEX.md, KIMI.md, CLAUDE.md, and GEMINI.md. Instead, we should use a neutral, portable file: AGENTS.md.

This Is Not Just About a Filename

CLAUDE.md is not a bad file. If your team uses Claude Code exclusively, it is highly practical. It works perfectly inside the Anthropic ecosystem.

The problem starts when a vendor-specific file becomes the canonical home for knowledge that actually belongs to the project.

Your project’s instructions are not Claude’s property. They belong to your team. They describe how the repository should be understood, changed, tested, and maintained, regardless of which AI tool is being used.

That is why AGENTS.md matters: it gives us a neutral space to describe how any AI agent should interact with a project.

A Strong Signal from the Industry

Claude Code now explicitly supports AGENTS.md. When no CLAUDE.md is present in a folder, Claude Code will look for and use AGENTS.md (a behavior that can also be toggled via /config).

“Claude Code now supports AGENTS.md. We'll fallback to it if CLAUDE.md isn't specified. Hope this helps :)”
— Addy Osmani on X (formerly Twitter)

While this might look like a minor compatibility update, it is actually a major signal: AGENTS.md is becoming a shared convention. The ecosystem is shifting toward a world where the same project instructions can be consumed by different agents. That is exactly the direction we should encourage.

One Project, Multiple Agents: The Duplication Trap

Today, a single repository might contain a clutter of instruction files:

CLAUDE.md
CODEX.md
GEMINI.md
KIMI.md
…

At first, this seems harmless. You copy the same instructions into each file, adapt a few details, and move on. But duplication creates drift.

One file gets updated; another does not. A testing rule changes in one place but is forgotten elsewhere. A new developer reads the instructions for one tool and assumes they represent the whole project. Over time, your agents receive conflicting versions of your team’s expectations.

This is not a tooling problem. It is a knowledge management problem.

A better structure is simple:

Your Project/
├── AGENTS.md      <-- Single source of truth
├── README.md
├── docs/
└── .agents/

One project. One source of truth. Multiple compatible agents.

Keep Project Knowledge Independent from the Tool

I regularly switch between different AI coding tools. Some are better at exploration, while others are faster or boast better integrations. Some handle large refactorings more effectively, whereas others are cheaper or run locally.

I want to choose the right tool for the job without rewriting the project instructions every time I change assistants.

This principle applies to many areas of software development:

Business rules should not belong to a framework.
Engineering practices should not belong to an IDE.
Project instructions should not belong to a single AI assistant.

Tools are replaceable. The knowledge behind the project must be portable.

What Should Go Into AGENTS.md?

The Golden Rule: AGENTS.md should describe the project, not the personality of the model.

This file should not be a giant prompt. It does not need to say: “You are an expert senior developer with exceptional reasoning skills…” That type of instruction is generic, fragile, and ultimately useless.

Instead, AGENTS.md should concisely explain how the team works.

Example Structure for AGENTS.md

## Working in this repository

Read the relevant documentation before making structural changes.
Keep changes small and focused.
Prefer simple, explicit solutions over clever abstractions.
Add or update tests when changing behavior.
Do not modify public APIs without updating the documentation.
Follow the formatting and linting configuration checked into the repository.

Project guidance

Start with the README for setup instructions.
Look for existing patterns before introducing new abstractions.
Check the docs/ directory when working on unfamiliar areas.

It should be short enough to read regularly, specific enough to be useful, clear enough for humans to review, and structured enough for agents to follow.

Tool-Specific Configuration Still Has a Place

Using AGENTS.md does not mean every AI coding tool must behave identically. Tool-specific files still have their place:

.claude/
.codex/
.cursor/

This is completely fine when they contain genuine integration details — such as tool-specific hooks, custom commands, permission settings, or local workflow configurations.

Keep project instructions portable. Keep tool configurations specific. What we must avoid is storing a second version of the team’s engineering rules inside every tool’s directory.

Pro Tip: The .agents/ directory can also host cross-LLM skills. This keeps your core AGENTS.md clean while seamlessly extending your AI's capabilities with custom scripts and tools.

The Future is Multi-Agent

I do not believe the future of software development will belong to one single AI coding agent. Tools will continue to specialize in planning, implementation, code review, or local execution. Teams will combine them.

The winning workflow will not necessarily be the one with the best individual tool. It will be the workflow that allows tools to be swapped out without disrupting the underlying engineering process.

That requires a stable layer of project knowledge. AGENTS.md can be that layer.

The tools will change. The models will evolve. The pricing will fluctuate. Our projects should not have to be rewritten every time they do.