Créer un fichier AGENTS.md de haute qualité

Vous êtes un agent de code. Votre tâche est de créer un fichier AGENTS.md complet et précis à la racine de ce référentiel qui suit les conseils publics sur https://agents.md/.

AGENTS.md est un format ouvert conçu pour fournir aux agents de codage le contexte et les instructions dont ils ont besoin pour travailler efficacement sur un projet.

Qu'est-ce que AGENTS.md ?

AGENTS.md est un fichier Markdown qui sert de « README pour les agents » - un endroit dédié et prévisible pour fournir du contexte et des instructions afin d'aider les agents de codage IA à travailler sur votre projet. Il complète README.md en contenant un contexte technique détaillé dont les agents de codage ont besoin mais qui pourrait encombrer un README axé sur l'humain.

Principes clés

Axé sur les agents : Contient des instructions techniques détaillées pour les outils automatisés
Complète README.md : Ne remplace pas la documentation humaine mais ajoute du contexte spécifique aux agents
Emplacement standardisé : Placé à la racine du référentiel (ou aux racines des sous-projets pour les monorepos)
Format ouvert : Utilise Markdown standard avec une structure flexible
Compatibilité écosystème : Fonctionne avec plus de 20 outils et agents IA différents

Directives de structure et de contenu de fichier

1. Configuration requise

Créer le fichier en tant que AGENTS.md à la racine du référentiel
Utiliser le formatage Markdown standard
Aucun champ obligatoire - structure flexible selon les besoins du projet

2. Sections essentielles à inclure

Aperçu du projet

Brève description de ce que fait le projet
Aperçu de l'architecture si complexe
Technologies clés et frameworks utilisés

Commandes de configuration

Instructions d'installation
Étapes de configuration de l'environnement
Commandes de gestion des dépendances
Configuration de la base de données le cas échéant

Flux de travail de développement

Comment démarrer le serveur de développement
Commandes de build
Configuration de watch/hot-reload
Spécificités du gestionnaire de packages (npm, pnpm, yarn, etc.)

Instructions de test

Comment exécuter les tests (unitaires, intégration, e2e)
Emplacements et conventions de dénomination des fichiers de test
Exigences de couverture
Patterns ou frameworks de test spécifiques utilisés
Comment exécuter un sous-ensemble de tests ou se concentrer sur des zones spécifiques

Directives de style de code

Conventions spécifiques au langage
Règles de linting et de formatage
Patterns d'organisation des fichiers
Conventions de dénomination
Patterns d'import/export

Build et déploiement

Commandes de build et sorties
Configurations d'environnement
Étapes et exigences de déploiement
Informations du pipeline CI/CD

3. Sections optionnelles mais recommandées

Considérations de sécurité

Exigences de test de sécurité
Gestion des secrets
Patterns d'authentification
Modèles de permissions

Instructions Monorepo (le cas échéant)

Comment travailler avec plusieurs packages
Dépendances inter-packages
Build/test sélectifs
Commandes spécifiques aux packages

Directives de Pull Request

Exigences de format du titre
Vérifications requises avant soumission
Processus d'examen
Conventions de messages de commit

Débogage et dépannage

Problèmes courants et solutions
Patterns de logging
Configuration de débogage
Considérations de performance

Modèle d'exemple

Utilisez ceci comme modèle de démarrage et personnalisez en fonction du projet spécifique :

# AGENTS.md

## Aperçu du projet

[Brève description du projet, de son objectif et des technologies clés]

## Commandes de configuration

- Installer les dépendances : `[gestionnaire de packages] install`
- Démarrer le serveur de développement : `[commande]`
- Build pour la production : `[commande]`

## Flux de travail de développement

- [Instructions de démarrage du serveur de développement]
- [Informations sur le hot reload/mode watch]
- [Configuration des variables d'environnement]

## Instructions de test

- Exécuter tous les tests : `[commande]`
- Exécuter les tests unitaires : `[commande]`
- Exécuter les tests d'intégration : `[commande]`
- Couverture de test : `[commande]`
- [Patterns ou exigences de test spécifiques]

## Style de code

- [Conventions du langage et du framework]
- [Règles de linting et commandes]
- [Exigences de formatage]
- [Patterns d'organisation des fichiers]

## Build et déploiement

- [Détails du processus de build]
- [Répertoires de sortie]
- [Builds spécifiques à l'environnement]
- [Commandes de déploiement]

## Directives de Pull Request

- Format du titre : [composant] Brève description
- Vérifications requises : `[commande lint]`, `[commande test]`
- [Exigences d'examen]

## Notes supplémentaires

- [Contexte spécifique au projet]
- [Pièges courants ou conseils de dépannage]
- [Considérations de performance]

Exemple concret provenant d'agents.md

Voici un exemple réel du site agents.md :

# Exemple de fichier AGENTS.md

## Conseils pour l'environnement de développement

- Utilisez `pnpm dlx turbo run where <project_name>` pour accéder à un package au lieu de scanner avec `ls`.
- Exécutez `pnpm install --filter <project_name>` pour ajouter le package à votre workspace afin que Vite, ESLint et TypeScript le voient.
- Utilisez `pnpm create vite@latest <project_name> -- --template react-ts` pour créer un nouveau package React + Vite avec les vérifications TypeScript prêtes.
- Vérifiez le champ name dans le package.json de chaque package pour confirmer le bon nom—ignorez celui de niveau supérieur.

## Instructions de test

- Trouvez le plan CI dans le dossier .github/workflows.
- Exécutez `pnpm turbo run test --filter <project_name>` pour exécuter chaque vérification définie pour ce package.
- À partir de la racine du package, vous pouvez simplement appeler `pnpm test`. Le commit doit réussir tous les tests avant de fusionner.
- Pour vous concentrer sur une étape, ajoutez le pattern Vitest : `pnpm vitest run -t "<test name>"`.
- Corrigez tous les tests ou erreurs de type jusqu'à ce que la suite entière soit au vert.
- Après avoir déplacé des fichiers ou changé des imports, exécutez `pnpm lint --filter <project_name>` pour vérifier que les règles ESLint et TypeScript passent toujours.
- Ajoutez ou mettez à jour les tests pour le code que vous changez, même si personne ne l'a demandé.

## Instructions de PR

- Format du titre : [<project_name>] <Title>
- Exécutez toujours `pnpm lint` et `pnpm test` avant de committer.

Étapes d'implémentation

Analyser la structure du projet pour comprendre :
- Langages de programmation et frameworks utilisés
- Gestionnaires de packages et outils de build
- Frameworks de test
- Architecture du projet (monorepo, package unique, etc.)
Identifier les flux de travail clés en examinant :
- Les scripts package.json
- Makefile ou autres fichiers de build
- Fichiers de configuration CI/CD
- Fichiers de documentation
Créer des sections complètes couvrant :
- Toutes les commandes essentielles de configuration et de développement
- Stratégies et commandes de test
- Style de code et conventions
- Processus de build et de déploiement
Inclure des commandes spécifiques et actionnables que les agents peuvent exécuter directement
Tester les instructions en vous assurant que toutes les commandes fonctionnent comme documenté
Rester concentré sur ce que les agents ont besoin de savoir, pas les informations générales du projet

Bonnes pratiques

Soyez spécifique : Incluez les commandes exactes, pas des descriptions vagues
Utilisez des blocs de code : Enveloppez les commandes dans des backticks pour plus de clarté
Incluez du contexte : Expliquez pourquoi certaines étapes sont nécessaires
Restez à jour : Mettez à jour à mesure que le projet évolue
Testez les commandes : Assurez-vous que toutes les commandes listées fonctionnent réellement
Considérez les fichiers imbriqués : Pour les monorepos, créez des fichiers AGENTS.md dans les sous-projets selon les besoins

Considérations pour les monorepos

Pour les grands monorepos :

Placez un AGENTS.md principal à la racine du référentiel
Créez des fichiers AGENTS.md supplémentaires dans les répertoires des sous-projets
Le fichier AGENTS.md le plus proche a priorité pour tout emplacement donné
Incluez des conseils de navigation entre les packages/projets

Remarques finales

AGENTS.md fonctionne avec plus de 20 outils de codage IA incluant Cursor, Aider, Gemini CLI et bien d'autres
Le format est intentionnellement flexible - adaptez-le aux besoins de votre projet
Concentrez-vous sur les instructions actionnables qui aident les agents à comprendre et travailler avec votre codebase
Ceci est une documentation vivante - mettez-la à jour à mesure que votre projet évolue

Lors de la création du fichier AGENTS.md, privilégiez la clarté, l'exhaustivité et l'actionnabilité. L'objectif est de donner à tout agent de codage suffisamment de contexte pour contribuer efficacement au projet sans avoir besoin de conseils humains supplémentaires.

create-agentsmd