Instrucciones personales y AGENTS.md

Tiempo: 50 minutos
Superficie: aplicación, CLI o IDE
Plataformas: macOS, Windows y Linux

Qué vas a aprender

Decidir qué instrucciones pertenecen al mensaje, a tu perfil o al proyecto.
Crear un AGENTS.md breve y comprobable.
Entender cómo se combinan instrucciones generales y específicas.

Coloca cada regla en su ámbito

Prompt: una condición que solo importa en la tarea actual.
Instrucciones personales: preferencias que quieres en muchas conversaciones, como idioma o estilo.
AGENTS.md de proyecto: reglas duraderas de una carpeta o repositorio: estructura, límites y verificación.
AGENTS.md anidado: reglas más específicas de una subcarpeta.

No conviertas una preferencia temporal en una norma permanente.

Cómo descubre Codex las instrucciones

Codex puede leer una guía global desde su directorio de configuración y después archivos AGENTS.md desde la raíz del proyecto hasta la carpeta de trabajo. Las instrucciones más cercanas tienen prioridad cuando concretan o sustituyen una regla anterior.

En la aplicación, las instrucciones personalizadas de Settings > Personalization pueden actualizar la guía personal. En un proyecto compartido, conserva las reglas del equipo dentro del proyecto para que puedan revisarse y versionarse.

Práctica: crea la guía de tu web

Dentro de mi-primera-web, crea AGENTS.md:

# Guía del proyecto

## Objetivo
- Mantener una web local de una página para aprendizaje.

## Límites
- No publicar ni añadir servicios externos.
- No usar datos personales reales.
- No añadir dependencias sin pedir permiso.

## Contenido
- Mantener el español claro para público general.
- Marcar el correo de ejemplo como ficticio.

## Verificación
- Abrir index.html después de cada cambio.
- Comprobar móvil, escritorio y navegación con teclado.
- Informar de cualquier comprobación no realizada.

Inicia una tarea nueva dentro del proyecto y escribe:

No edites archivos. Enumera las instrucciones del proyecto que se aplican a
esta tarea, indica de qué archivo proceden y señala cualquier ambigüedad.

Después pide un cambio incompatible, por ejemplo «añade analítica externa sin preguntar». Codex debería señalar el conflicto y solicitar una decisión.

Qué no debe contener AGENTS.md

Contraseñas o claves.
Historias de conversación.
Información personal innecesaria.
Una lista enorme de posibilidades hipotéticas.
Instrucciones que no pueden comprobarse, como «hazlo perfecto».

Global y proyecto

Una guía personal puede decir «responde en español y explica la jerga». El proyecto puede decir «el contenido público utiliza español neutro». Una regla más específica no debería borrar silenciosamente límites de seguridad definidos arriba; si existe conflicto, revísalo explícitamente.

Comprobación manual

Una persona nueva comprende objetivo y límites en menos de dos minutos.
Cada regla puede observarse o verificarse.
Los comandos o pasos citados funcionan realmente.
No hay secretos.
Las reglas específicas están cerca de los archivos a los que afectan.

Recuperación

Si Codex utiliza instrucciones antiguas, inicia una tarea o sesión nueva para que vuelva a construir la cadena. Busca AGENTS.override.md o guías anidadas que puedan tener prioridad.

Error frecuente

Usar AGENTS.md como enciclopedia. Las reglas importantes se pierden entre explicaciones largas. Mantén una guía corta y enlaza documentos especializados cuando sean necesarios.

Mini ejercicio

Añade una regla que hayas repetido dos veces durante el curso. Justifica por qué es duradera. Elimina otra que solo corresponda a una práctica.

Evidencia que debes guardar

AGENTS.md aprobado.
Resumen de instrucciones activas.
Conflicto detectado y decisión tomada.

Ejemplo resuelto: una regla estable sin convertirla en una novela

Marta repite en cada tarea: «escribe en español claro, no cambies originales y guarda resultados en salida». Esas reglas son estables y pueden convertirse en instrucciones del proyecto:

# Instrucciones del proyecto

- Responde en español claro y explica cualquier término técnico.
- No modifiques archivos dentro de `entrada/`.
- Escribe todos los entregables en `salida/`.
- Antes de cambios masivos, presenta inventario y vista previa.
- Al terminar, informa de archivos creados, controles y pendientes.

Para la tarea concreta añade: «procesa el informe de junio». Esa fecha no pertenece a las instrucciones permanentes porque cambiará en la próxima ejecución.

Dani tiene además un AGENTS.md en una subcarpeta con reglas para las pruebas de esa parte del proyecto. Antes de actuar pide a Codex que enumere las instrucciones aplicables y señale cualquier conflicto. Si una regla general dice «guarda salidas en salida» y una regla específica de pruebas exige tests/fixtures, la más cercana al trabajo puede precisar el destino; el conflicto debe hacerse visible, no resolverse por intuición silenciosa.

Prueba de calidad: abre una tarea nueva y formula un encargo mínimo. Comprueba si se respetan idioma, carpeta protegida, vista previa y parte final. Si debes recordar la misma regla otra vez, revisa su ubicación o redacción.

Señal de alarma: las instrucciones contienen contraseñas, decisiones temporales, reglas contradictorias o tantos detalles que ya no se sabe cuáles son obligatorios.

Criterio de terminado: las normas estables se aplican en una tarea nueva y el objetivo temporal permanece en el prompt de esa tarea.

Cambia una variable

Elimina deliberadamente una regla no esencial y comprueba si el resultado sigue siendo seguro. Las instrucciones deben ser suficientes, no enciclopédicas.

Comprueba que lo has entendido

¿«Haz el informe de hoy» pertenece a instrucciones permanentes?
¿Qué debes hacer si dos reglas parecen incompatibles?

Respuesta razonada

No: es un objetivo temporal. Ante reglas incompatibles, identifica su origen y alcance, detén la decisión afectada y pide aclaración o aplica la jerarquía documentada de forma explícita.

Fuentes oficiales

Revisado contra la documentación: 14 de julio de 2026.