AGENTS.md

Les fichiers AGENTS.md offrent un moyen simple de fournir à Cascade des instructions contextualisées qui s’appliquent automatiquement en fonction de l’emplacement du fichier dans votre projet. Cela est particulièrement utile pour définir des directives de code spécifiques à un répertoire, des décisions d’architecture ou des conventions de projet.

Fonctionnement

Lorsque vous créez un fichier AGENTS.md (ou agents.md), Windsurf le découvre automatiquement et l’intègre au même moteur de Rules qui alimente .windsurf/rules/ — à ceci près que le mode d’activation est déduit de l’emplacement du fichier plutôt que du frontmatter :

Répertoire racine : traité comme une règle toujours active — l’intégralité du contenu est incluse dans le prompt système de Cascade à chaque message.
Sous-répertoires : traités comme une règle glob avec un motif généré automatiquement de <directory>/** — le contenu n’est appliqué que lorsque Cascade lit ou modifie des fichiers dans ce répertoire.

Cette portée définie par l’emplacement fait de AGENTS.md un choix idéal pour fournir des instructions ciblées sans encombrer un unique fichier de configuration global.

Création d’un fichier AGENTS.md

Créez simplement un fichier nommé AGENTS.md ou agents.md dans le répertoire souhaité. Le fichier est un simple fichier Markdown, sans front matter particulière requise.

Structure d’exemple

my-project/
├── AGENTS.md                    # Instructions globales pour l'ensemble du projet
├── frontend/
│   ├── AGENTS.md                # Instructions spécifiques au code frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instructions spécifiques aux composants
├── backend/
│   └── AGENTS.md                # Instructions spécifiques au code backend
└── docs/
    └── AGENTS.md                # Instructions pour la documentation

Exemple de contenu

Voici un exemple de fichier AGENTS.md pour un répertoire de composants React :

# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports

Découverte et définition du périmètre

Windsurf découvre automatiquement les fichiers AGENTS.md dans l’ensemble de votre workspace :

Analyse du workspace : Tous les fichiers AGENTS.md présents dans votre workspace et ses sous-répertoires sont détectés
Prise en charge des dépôts Git : Pour les dépôts Git, Windsurf recherche également dans les répertoires parents jusqu’à la racine du dépôt Git
Insensible à la casse : Les fichiers AGENTS.md et agents.md sont tous deux reconnus

Portée automatique

Le principal avantage de AGENTS.md est la portée automatique basée sur l’emplacement des fichiers :

Emplacement du fichier	Portée
Racine du workspace	S’applique à tous les fichiers (toujours actif)
`/frontend/`	S’applique lorsque vous travaillez avec des fichiers dans `/frontend/**`
`/frontend/components/`	S’applique lorsque vous travaillez avec des fichiers dans `/frontend/components/**`

Cela signifie que vous pouvez avoir plusieurs fichiers AGENTS.md à différents niveaux, chacun fournissant des recommandations de plus en plus spécifiques pour ses répertoires respectifs.

Bonnes pratiques

Pour tirer pleinement parti des fichiers AGENTS.md :

Gardez des instructions ciblées : chaque AGENTS.md doit contenir des instructions pertinentes pour la finalité de son répertoire
Utilisez un formatage clair : les listes à puces, les titres et les blocs de code facilitent la compréhension des instructions par Cascade
Soyez précis : des exemples concrets et des conventions explicites fonctionnent mieux que des consignes vagues
Évitez les redondances : ne répétez pas les instructions globales dans les fichiers des sous-répertoires ; elles sont héritées des répertoires parents

Consignes de contenu

# Bon exemple
- Utiliser le mode strict de TypeScript
- Toutes les réponses API doivent inclure la gestion des erreurs
- Suivre les conventions de nommage REST pour les endpoints

# Exemple moins efficace
- Écrire du bon code
- Faire attention aux erreurs
- Utiliser les bonnes pratiques

Comparaison avec Rules

Bien que AGENTS.md et Rules fournissent tous deux des instructions à Cascade, ils ont des objectifs différents :

Fonctionnalité	AGENTS.md	Rules
Emplacement	Dans les répertoires du projet	`.windsurf/rules/` ou global
Portée	Automatique en fonction de l’emplacement du fichier	Manuel (glob, toujours activé, décision du modèle d’IA, manuel)
Format	Markdown simple	Markdown avec frontmatter
Idéal pour	Conventions spécifiques à un répertoire	Préoccupations transversales, logique d’activation complexe

Utilisez AGENTS.md lorsque vous voulez des instructions simples basées sur l’emplacement. Utilisez Rules lorsque vous avez besoin de plus de contrôle sur le moment et la manière dont les instructions sont appliquées.

Éditeur

Cascade

Comptes

Gestion du contexte

Dépannage

Sécurité

Fonctionnement

Création d’un fichier AGENTS.md

Structure d’exemple

Exemple de contenu

Découverte et définition du périmètre

Portée automatique

Bonnes pratiques

Consignes de contenu

Comparaison avec Rules

​Fonctionnement

​Création d’un fichier AGENTS.md

​Structure d’exemple

​Exemple de contenu

​Découverte et définition du périmètre

​Portée automatique

​Bonnes pratiques

​Consignes de contenu

​Comparaison avec Rules

Fonctionnement

Création d’un fichier AGENTS.md

Structure d’exemple

Exemple de contenu

Découverte et définition du périmètre

Portée automatique

Bonnes pratiques

Consignes de contenu

Comparaison avec Rules