AGENTS.md

Los archivos AGENTS.md proporcionan una forma sencilla de darle a Cascade instrucciones sensibles al contexto que se aplican automáticamente según dónde se encuentre el archivo dentro de tu proyecto. Esto es especialmente útil para definir guías de codificación específicas de un directorio, decisiones de arquitectura o convenciones del proyecto.

Cómo funciona

Cuando creas un archivo AGENTS.md (o agents.md), Windsurf lo detecta automáticamente y lo incorpora al mismo motor de Rules que impulsa .windsurf/rules/, solo que con el modo de activación inferido a partir de la ubicación del archivo en lugar del frontmatter:

Directorio raíz: Se trata como una regla siempre activa — el contenido completo se incluye en el prompt del sistema de Cascade en cada mensaje.
Subdirectorios: Se tratan como una regla glob con un patrón generado automáticamente de <directory>/** — el contenido se aplica solo cuando Cascade lee o edita archivos dentro de ese directorio.

Este alcance basado en la ubicación hace que AGENTS.md sea ideal para proporcionar instrucciones específicas sin sobrecargar un único archivo de configuración global.

Creación de un archivo AGENTS.md

Basta con crear un archivo llamado AGENTS.md o agents.md en el directorio deseado. El archivo usa Markdown normal y no requiere ningún frontmatter especial.

Ejemplo de estructura

my-project/
├── AGENTS.md                    # Instrucciones globales para todo el proyecto
├── frontend/
│   ├── AGENTS.md                # Instrucciones específicas para el código del frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instrucciones específicas para los componentes
├── backend/
│   └── AGENTS.md                # Instrucciones específicas para el código del backend
└── docs/
    └── AGENTS.md                # Instrucciones para la documentación

Contenido de ejemplo

Aquí tienes un ejemplo de archivo AGENTS.md para un directorio de componentes de 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

Descubrimiento y definición del alcance

Windsurf detecta automáticamente archivos AGENTS.md en todo tu workspace:

Escaneo del workspace: Se detectan todos los archivos AGENTS.md dentro de tu workspace y sus subdirectorios
Compatibilidad con repositorios Git: Para repositorios Git, Windsurf también busca en los directorios padre hasta la raíz del repositorio
Sin distinción entre mayúsculas y minúsculas: Se reconocen tanto AGENTS.md como agents.md

Alcance automático

El beneficio principal de AGENTS.md es el alcance automático basado en la ubicación de los archivos:

Ubicación del archivo	Alcance
Raíz del workspace	Se aplica a todos los archivos (siempre activo)
`/frontend/`	Se aplica al trabajar con archivos en `/frontend/**`
`/frontend/components/`	Se aplica al trabajar con archivos en `/frontend/components/**`

Esto significa que puedes tener varios archivos AGENTS.md en distintos niveles, cada uno proporcionando instrucciones cada vez más específicas para sus respectivos directorios.

Mejores prácticas

Para aprovechar al máximo los archivos AGENTS.md:

Mantén las instrucciones bien enfocadas: Cada AGENTS.md debe contener instrucciones relevantes para el propósito de su directorio
Usa un formato claro: Las viñetas, encabezados y bloques de código hacen que a Cascade le resulte más fácil seguir las instrucciones
Sé específico: Los ejemplos concretos y las convenciones explícitas funcionan mejor que las pautas vagas
Evita la redundancia: No repitas instrucciones globales en los archivos de subdirectorios; estos las heredan de los directorios padre

Pautas de contenido

# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints

# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices

Comparación con Rules

Si bien tanto AGENTS.md como Rules proporcionan instrucciones a Cascade, tienen propósitos diferentes:

Característica	AGENTS.md	Rules
Ubicación	En los directorios del proyecto	`.windsurf/rules/` o global
Alcance	Automático según la ubicación del archivo	Manual (glob, siempre activo, decisión del modelo, manual)
Formato	Markdown sin metadatos	Markdown con frontmatter
Mejor para	Convenciones específicas de un directorio	Aspectos transversales, lógica de activación compleja

Usa AGENTS.md cuando quieras instrucciones simples basadas en la ubicación. Usa Rules cuando necesites más control sobre cuándo y cómo se aplican las instrucciones.

Editor

Cascade

Cuentas

Conocimiento del contexto

Resolución de problemas

Seguridad

Cómo funciona

Creación de un archivo AGENTS.md

Ejemplo de estructura

Contenido de ejemplo

Descubrimiento y definición del alcance

Alcance automático

Mejores prácticas

Pautas de contenido

Comparación con Rules

​Cómo funciona

​Creación de un archivo AGENTS.md

​Ejemplo de estructura

​Contenido de ejemplo

​Descubrimiento y definición del alcance

​Alcance automático

​Mejores prácticas

​Pautas de contenido

​Comparación con Rules

Cómo funciona

Creación de un archivo AGENTS.md

Ejemplo de estructura

Contenido de ejemplo

Descubrimiento y definición del alcance

Alcance automático

Mejores prácticas

Pautas de contenido

Comparación con Rules