Guía de AGENTS.md: El Archivo de Configuración Universal para Agentes de Codificación de IA

Ayer publiqué nuestra guía de CLAUDE.md para equipos empresariales. En cuestión de horas, tres personas preguntaron lo mismo: “¿Qué pasa con los equipos que no están completamente comprometidos con Claude Code?”

Buen punto. Si tu organización usa GitHub Copilot para algunos equipos, Cursor para otros, Codex para tareas en segundo plano y Claude Code para refactorizaciones complejas — y eso es cada vez más común — necesitas algo que funcione en todas partes.

Eso es AGENTS.md.

Qué es AGENTS.md (y qué no es)

AGENTS.md es un archivo markdown neutro de proveedor que les dice a los agentes de codificación de IA cómo trabajar en tu base de código. Se encuentra en la raíz de tu repositorio (o en subdirectorios para reglas con alcance definido) y contiene el mismo tipo de información que le darías a un nuevo desarrollador en su primer día: comandos de compilación, protocolos de prueba, convenciones de codificación, arquitectura del proyecto y límites explícitos.

La diferencia clave con README.md: está estructurado para máquinas, no para humanos. Donde un README podría decir “usamos React con TypeScript”, un AGENTS.md dice:

## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4

Versiones exactas. Sin narrativa. Los agentes no necesitan tu historia de origen.

El formato surgió de un problema práctico. Antes de AGENTS.md, cada agente tenía su propio archivo de configuración — Aider usaba CONVENTIONS.md, Roo Code usaba archivos .roomodes, Cline usaba directorios .clinerules y Claude Code usaba CLAUDE.md. Los equipos que ejecutaban múltiples agentes mantenían configuraciones redundantes y divergentes. AGENTS.md unifica esto en una única fuente de verdad que más de 60,000 proyectos de código abierto han adoptado.

Por Qué los Equipos Empresariales Deberían Importarse

Los números cuentan la historia. GitHub analizó más de 2,500 repositorios y encontró que las tasas de éxito de los agentes aumentan drásticamente con una guía adecuada:

• Sin AGENTS.md — 40-60% de tasa de éxito en tareas
• AGENTS.md mínimo — 60-70% de tasa de éxito
• AGENTS.md completo — 85-90% de tasa de éxito

Para un equipo empresarial que encola cinco tareas de agente cada mañana (un patrón que el equipo de WorkOS fue pionero con Codex), eso es la diferencia entre dos fallos por día y cero. Multiplícalo en toda tu organización y el ROI se vuelve obvio.

Pero el verdadero valor empresarial no son solo las tasas de éxito. Es la estandarización entre herramientas. Cuando tu equipo de frontend usa Cursor, tu equipo de plataforma usa Claude Code y tu equipo de DevOps experimenta con Codex, un solo AGENTS.md asegura que todos sigan las mismas convenciones. Escríbelo una vez, cada agente lo lee.

Cómo Cada Agente Principal Usa AGENTS.md

No todos los agentes consumen AGENTS.md de manera idéntica. Entender las diferencias te ayuda a escribir archivos que funcionen bien en todas partes.

GitHub Copilot

Copilot descubre automáticamente AGENTS.md desde la raíz del workspace y subdirectorios. El equipo de GitHub analizó esos 2,500+ repositorios específicamente para mejorar cómo Copilot interpreta el formato. Copilot también soporta archivos .agent.md — un formato separado con frontmatter YAML para definir personas de agente personalizadas con herramientas y roles específicos.

Cursor

Cursor descubre automáticamente AGENTS.md y lo alimenta en su sistema de instrucciones. No se necesita configuración — coloca el archivo en tu repositorio y Cursor lo detecta. Simple y efectivo.

Windsurf

Windsurf tiene la integración más sofisticada. Trata AGENTS.md como parte de su motor de Reglas con alcance automático: un archivo raíz se convierte en una regla global siempre activa, mientras que los archivos de subdirectorios aplican automáticamente patrones glob basados en su ubicación. Windsurf escanea todos los archivos AGENTS.md en todo tu workspace.

Claude Code

Claude Code soporta AGENTS.md junto a su formato nativo CLAUDE.md. Los dos se complementan — AGENTS.md para convenciones universales, CLAUDE.md para características específicas de Claude como auto-memoria, declaraciones de servidor MCP y la arquitectura de tres capas que cubrí en La Anatomía de un Proyecto Claude Code.

OpenAI Codex

Codex descubre y carga automáticamente AGENTS.md al inicio, referenciando comandos frecuentemente durante la ejecución de tareas. Aquí es donde brilla el caso de estudio de WorkOS — su equipo encola 4-5 tareas de mantenimiento para Codex cada mañana (correcciones de TypeScript, actualizaciones de webhooks, migraciones de autenticación) y reporta tasas de éxito del 85-90% en trabajo bien definido.

Aider

Aider ya soportaba archivos de convenciones a través de --conventions-file. AGENTS.md se convirtió en la ubicación predeterminada estándar, y los archivos CONVENTIONS.md existentes aún funcionan para compatibilidad hacia atrás.

Otros

Roo Code, Google Jules, Factory.ai Droids y Zed todos soportan AGENTS.md con niveles variables de sofisticación. Factory.ai lo usa como el mecanismo de briefing principal con descubrimiento completo en todos los directorios. La tendencia es clara: AGENTS.md se está convirtiendo en el estándar mínimo.

Las Seis Cosas que Todo AGENTS.md Necesita

El análisis de GitHub de 2,500+ repositorios identificó seis áreas centrales que marcan la mayor diferencia:

1. Comandos Ejecutables

Ponlos primero. Los agentes recurren a ellos constantemente.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test single: `pnpm test -- --grep "test name"`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

2. Instrucciones de Prueba

No solo cómo ejecutar pruebas, sino cómo escribirlas. Qué framework, qué patrones, dónde viven.

## Testing
- Framework: Vitest with React Testing Library
- Location: `__tests__/` directories adjacent to source
- Pattern: one test file per component, named `ComponentName.test.tsx`
- Run single file: `pnpm test src/components/__tests__/Button.test.tsx`

3. Arquitectura del Proyecto

Estructura de archivos con anotaciones breves. Los agentes usan esto para navegar bases de código desconocidas.

## Architecture
- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `src/shared/` — Shared types and utilities
- `infra/` — Terraform modules and Bicep templates
- `scripts/` — CI/CD and automation scripts

4. Estilo de Código (con Ejemplos)

Las reglas abstractas no funcionan. Los ejemplos concretos sí.

## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Example:
  ```tsx
  export function UserCard({ name, role }: UserCardProps) {
    const [expanded, setExpanded] = useState(false);
    return (
      <Card onClick={() => setExpanded(!expanded)}>
        <h3>{name}</h3>
        {expanded && <p>{role}</p>}
      </Card>
    );
  }
  ```

5. Flujos de Trabajo de Git

Estándares de commits, convenciones de ramas, requisitos de PR.

## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks

6. Límites Explícitos

La estructura de restricciones de tres niveles es crítica para equipos empresariales:

## Boundaries
**Always do:**
- Include unit tests for new functions
- Run lint before committing
- Use environment variables for configuration

**Ask first:**
- Database schema changes
- Adding new dependencies
- Modifying CI/CD pipelines
- Changes to authentication or authorization logic

**Never do:**
- Commit secrets, API keys, or connection strings
- Modify files in `vendor/` or `node_modules/`
- Edit generated migration files
- Push directly to main branch
- Modify `.env.production`

Patrones para Monorepos

Aquí es donde AGENTS.md se vuelve interesante para equipos empresariales. El formato soporta anidamiento jerárquico — los archivos de subdirectorios heredan y anulan archivos padre, con el archivo más cercano teniendo prioridad.

/AGENTS.md                          ← Global: security rules, commit conventions
/frontend/AGENTS.md                 ← React patterns, CSS conventions, component rules
/frontend/components/AGENTS.md      ← Component library specifics
/backend/AGENTS.md                  ← API patterns, database rules, service conventions
/infra/AGENTS.md                    ← Terraform/Bicep rules, naming conventions

OpenAI mantiene aproximadamente 88 archivos AGENTS.md anidados en sus repositorios. Eso no es excesivo — es preciso. Cada equipo es dueño de la guía de agente de su subdirectorio, y las reglas globales se propagan desde la raíz.

Para equipos empresariales, esto se mapea naturalmente a la propiedad del equipo. El equipo de plataforma es dueño de las reglas a nivel raíz. Los equipos de frontend, backend e infraestructura son dueños de sus respectivos archivos de subdirectorio. Los cambios pasan por pull requests, igual que el código.

AGENTS.md, CLAUDE.md y SKILL.md — Cómo Encajan

Si estás usando Claude Code (y si leíste nuestra guía de CLAUDE.md, probablemente lo estés), podrías preguntarte cómo se relacionan estos archivos. Aquí está el modelo mental:

• AGENTS.md — “Cómo trabajar con esta base de código.” Neutro de proveedor. Leído por cada agente. Contiene comandos, arquitectura, convenciones y límites.
• CLAUDE.md — “Cómo Claude específicamente debería trabajar aquí.” Solo Claude Code. Añade auto-memoria, declaraciones de servidor MCP, configuración de hooks y optimizaciones específicas de Claude.
• SKILL.md — “Cómo realizar esta categoría de tarea.” Paquetes de experiencia reutilizables — no específicos de base de código sino específicos de tarea. Cubrí el flujo de trabajo de creación de skills en nuestro artículo sobre herramientas de skill de Claude Code y Gemini CLI.

Piénsalo como una pila:

• System prompt — línea base del modelo (no controlas esto)
• AGENTS.md — contexto de la base de código (universal)
• SKILL.md — experiencia en tareas (bajo demanda)
• CLAUDE.md / .agent.md — configuración específica del agente (por herramienta)
• MCP servers — acceso a sistemas externos (datos en vivo)

Para equipos multi-agente, invierte la mayor parte de tu esfuerzo en AGENTS.md. Tiene el alcance más amplio. Luego añade archivos CLAUDE.md o .agent.md para optimizaciones específicas de agente.

Plantilla de Inicio Empresarial

Aquí hay una plantilla lista para copiar y pegar para equipos empresariales. Personaliza los detalles, mantén la estructura:

# AGENTS.md

## Project Overview
[Una oración: qué hace este sistema y a quién sirve]

## Tech Stack
- [Lenguaje] [versión], [Framework] [versión], [Herramienta de compilación] [versión]
- Database: [sistema] [versión]
- Infrastructure: [plataforma] (Terraform/Bicep/CDK)
- CI/CD: [plataforma]

## Commands
- Install: `[comando]`
- Dev: `[comando]`
- Build: `[comando]`
- Test all: `[comando]`
- Test single: `[comando] [ruta]`
- Lint: `[comando]`
- Format: `[comando]`

## Architecture
- `src/` — Código fuente de la aplicación
  - `src/api/` — [descripción]
  - `src/web/` — [descripción]
  - `src/shared/` — [descripción]
- `infra/` — Infraestructura como código
- `tests/` — Pruebas de integración y E2E
- `scripts/` — Automatización y CI/CD
- `docs/` — Decisiones arquitectónicas y runbooks

## Code Style
- [2-3 reglas concretas con ejemplos]
- Example:
  ```[lenguaje]
  // Preferred pattern
  [ejemplo de código]
  ```

## Testing
- Framework: [nombre]
- Location: [patrón]
- Naming: [convención]
- Coverage: [umbral mínimo si aplica]

## Git Conventions
- Commits: [formato]
- Branches: [patrón de nombres]
- PRs: [requisitos]

## Boundaries
**Always do:**
- [lista de elementos críticos que siempre hacer]

**Ask first:**
- [lista de elementos que requieren aprobación humana]

**Never do:**
- [lista de prohibiciones absolutas]

Cómo Empezar en 15 Minutos

No necesitas un AGENTS.md perfecto desde el primer día. Comienza mínimo e itera.

Paso 1 (5 minutos): Crea AGENTS.md en la raíz de tu repositorio. Agrega tus comandos de compilación, prueba y lint. Estos tienen el mayor impacto inmediato.

Paso 2 (5 minutos): Agrega tu stack tecnológico con versiones exactas y una breve sección de arquitectura que enumere tu estructura de directorios.

Paso 3 (5 minutos): Agrega una sección de límites. Comienza con “never do” — las cosas que causarían daño real si un agente las hiciera. Agrega elementos “ask first” para cualquier cosa que requiera juicio humano.

Paso 4 (continuo): Cada vez que un agente cometa un error, agrega una regla. Este es el patrón de crecimiento orgánico que todo equipo exitoso sigue. Tu AGENTS.md se convierte en un registro vivo de lecciones aprendidas.

Pro tip: Hay un prompt mantenido por la comunidad que le pide a un agente de IA escanear tu repositorio existente — archivos de paquetes, flujos de trabajo CI/CD, guías de contribución, historial de git — y generar automáticamente un AGENTS.md inicial. Es el arranque más rápido para proyectos existentes.

La Realidad Multi-Agente

Aquí está por qué esto importa ahora mismo. Las guerras de CLI de IA significan que tus equipos probablemente ya están usando múltiples agentes, lo hayas autorizado o no. Los desarrolladores eligen la herramienta que funciona mejor para la tarea en cuestión — Cursor para edición interactiva, Claude Code para refactorizaciones complejas, Codex para colas de tareas en segundo plano.

Sin AGENTS.md, cada desarrollador configura cada agente de forma independiente. Las convenciones se desvían. La calidad varía. El mismo error se comete por diferentes agentes en diferentes partes de la base de código.

Con AGENTS.md, defines tus estándares una vez. Cada agente, cada desarrollador, cada sesión comienza desde la misma línea base. Esa es la propuesta de valor empresarial: no elegir un agente, sino hacer que todos funcionen de manera consistente.

Recursos

• Especificación oficial de AGENTS.md y ejemplos
• Blog de GitHub: Cómo escribir un gran agents.md — lecciones de 2,500+ repositorios
• Documentación de AGENTS.md de Windsurf
• Plantillas de agentsmd.net — 14 plantillas listas para producción por stack tecnológico

Consigue una Estrategia Multi-Agente Correcta

AGENTS.md es la base, pero es una pieza de una estrategia de codificación de IA más amplia. ¿Cómo encaja con tus archivos CLAUDE.md? ¿Tu infraestructura de servidor MCP? ¿Tus requisitos de gobierno? ¿El flujo de trabajo real de tu equipo?

Big Hat Group ayuda a equipos empresariales a construir estrategias coherentes de agentes de IA — no solo archivos de configuración, sino el stack completo: configuración de agentes, desarrollo de skills, límites de seguridad y los marcos de gobierno que mantienen cómodos a los equipos de cumplimiento. Hemos implementado estos patrones en organizaciones que ejecutan Copilot, Claude Code y Codex simultáneamente.

Si tu equipo está manejando múltiples agentes de codificación de IA y necesita un enfoque unificado, contáctanos.

Kevin Kaminski es Microsoft MVP y Principal en Big Hat Group, donde ayuda a equipos empresariales a implementar agentes de IA, Windows 365 y soluciones de gestión moderna.