Istari

Appearance

El README para Agentes de Codificación ​

¿Qué es AGENTS.md? ​

AGENTS.md es un formato abierto diseñado para guiar a los agentes de codificación, actuando como un manual de instrucciones específico para la IA. Es compatible con la mayoría de los agentes y herramientas de desarrollo con IA.

Piensa en él como un README, pero para agentes: un lugar dedicado y predecible donde proporcionar el contexto y las instrucciones necesarias para que los agentes de IA trabajen eficazmente en tu proyecto.

El estándar AGENTS.md es mantenido por la Agentic AI Foundation bajo la Linux Foundation, con contribuciones de OpenAI Codex, Amp, Jules de Google, Cursor y Factory.

¿Por qué AGENTS.md y no el README? ​

Los archivos README.md están diseñados para humanos: descripciones del proyecto, guías de inicio rápido y pautas de contribución.

AGENTS.md complementa esto al contener el contexto extra —a veces muy detallado— que los agentes de codificación necesitan:

README.mdAGENTS.md
Para desarrolladores humanosPara agentes de IA
Visión general del proyectoInstrucciones técnicas precisas
Guía de inicio rápidoComandos de build y test
Descripción de la arquitecturaConvenciones de código y estilo

Cómo Optimiza la Memoria de la IA ​

Separación de Preocupaciones ​

Mientras que el README.md es para humanos, el AGENTS.md contiene detalles técnicos que saturarían la documentación principal, como pasos de construcción complejos, guías de estilo de código y consideraciones de seguridad. Mantenerlos separados permite que cada audiencia consuma solo lo que necesita.

Precisión Semántica ​

Proporciona un lugar predecible y estructurado donde los agentes pueden encontrar el contexto necesario sin "perderse" en la documentación general. Al saber exactamente dónde buscar, el agente consume menos tokens y actúa con mayor precisión.

Jerarquía de Contexto (Archivos Anidados) ​

En repositorios grandes o monorepos, se pueden usar archivos AGENTS.md anidados en subcarpetas. El agente leerá automáticamente el archivo más cercano al código que está editando, lo que ahorra tokens al no cargar instrucciones irrelevantes de otros subproyectos.

Por ejemplo: el repositorio principal de OpenAI tiene 88 archivos AGENTS.md distribuidos en su monorepo.

Cómo Implementarlo en tu Proyecto ​

1. Crear el Archivo ​

Crea un archivo AGENTS.md en la raíz de tu repositorio. Un ejemplo mínimo y funcional:

markdown
# AGENTS.md

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

2. Cubrir lo que Importa ​

Agrega las secciones que ayuden al agente a trabajar eficazmente con tu proyecto. Las más populares son:

  • Visión general del proyecto — arquitectura y decisiones clave
  • Comandos de build y test — cómo compilar y ejecutar el proyecto
  • Guías de estilo de código — convenciones, linters, formateadores
  • Instrucciones de testing — cómo correr y escribir pruebas
  • Consideraciones de seguridad — qué evitar y qué proteger

3. Agregar Instrucciones Extra ​

Mensajes de commit, directrices para pull requests, advertencias de seguridad, pasos de despliegue: cualquier cosa que le dirías a un nuevo compañero de equipo pertenece aquí también.

4. Declarar las Skills Disponibles ​

Una de las mejores prácticas es incluir en tu AGENTS.md un directorio de Skills disponibles, indicando cuándo debe usar cada una. Esto elimina la ambigüedad y evita que el agente omita o active incorrectamente una habilidad.

Incluye el nombre de cada skill, una descripción breve y los casos de uso que la deben activar:

markdown
## Skills Disponibles

Las siguientes skills están disponibles en este proyecto. Úsalas según corresponda:

| Skill                 | Cuándo usarla                                                             |
| --------------------- | ------------------------------------------------------------------------- |
| `webapp-testing`      | Al crear, modificar o depurar tests de la aplicación web                  |
| `brand-guidelines`    | Al generar cualquier artifact visual o documento con identidad de marca   |
| `aws-cdk-deploy`      | Al desplegar infraestructura o modificar stacks de AWS CDK                |
| `pr-review-checklist` | Antes de proponer un pull request, para validar que cumple los estándares |
| `database-migration`  | Al crear o modificar migraciones de base de datos                         |

También puedes ser más explícito con instrucciones en prosa para casos donde el criterio de activación requiere más contexto:

markdown
## Skills Disponibles

### `security-audit`

Úsala **siempre** que modifiques cualquier endpoint de autenticación, manejo de tokens,
validación de inputs o lógica de permisos. No esperes a que se te pida explícitamente.

### `docx-creator`

Úsala cuando el usuario pida generar un informe, contrato, o cualquier documento
que deba entregarse en formato `.docx`. Si el usuario solo pide "un documento" sin
especificar formato, pregunta antes de asumir.

### `data-analysis`

Úsala al trabajar con archivos `.csv`, `.xlsx` o `.json` que contengan datos
tabulares. Si el dataset tiene más de 1.000 filas, activa también el script
de validación en `scripts/validate.py` antes de proceder.

Por qué esto importa: El agente evalúa las descripciones de las skills contra tu petición para decidir si activarlas. Al declarar explícitamente en el AGENTS.md cuándo usar cada una, reduces las activaciones incorrectas y garantizas que skills críticas (como auditorías de seguridad) nunca se omitan por falta de contexto.

5. Escalar con Archivos Anidados ​

En monorepos, coloca un AGENTS.md dentro de cada paquete. Los agentes leen automáticamente el archivo más cercano en el árbol de directorios, por lo que cada subproyecto puede tener instrucciones propias sin interferir con otros.

Compatibilidad ​

Un solo AGENTS.md funciona en un ecosistema amplio de herramientas:

  • GitHub Copilot
  • Cursor
  • Claude / Claude Code
  • Devin (Cognition)
  • Jules (Google)
  • Aider
  • Amp
  • opencode
  • Kilo Code
  • Semgrep

Preguntas Frecuentes ​

¿Hay campos obligatorios? No. AGENTS.md es Markdown estándar. Usa los encabezados que prefieras; el agente simplemente analiza el texto que proporcionas.

¿Qué pasa si las instrucciones se contradicen? El AGENTS.md más cercano al archivo editado tiene prioridad. Los prompts explícitos del usuario en el chat lo anulan todo.

¿El agente ejecutará los comandos de testing automáticamente? Sí, si los listas. El agente intentará ejecutar las verificaciones programáticas relevantes y corregir los fallos antes de terminar la tarea.

¿Puedo actualizarlo más adelante? Por supuesto. Trata el AGENTS.md como documentación viva que evoluciona con tu proyecto.