Ir al contenido principal
Español— Elegir un idioma
Menú

AGENTS.md: Configura las instrucciones de tu repositorio

Lección 15 de 20 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Dominio del archivo de configuración de Codex
  2. La jerarquía de AGENTS.md
  3. Las secciones que conforman el archivo
  4. Dos patrones que previenen sorpresas
  5. Mantener el archivo vivo
  6. Puntos clave

Lección actualizada el 3 de noviembre de 2026 basándose en la página Custom instructions with AGENTS.md: Codex solo lee los archivos AGENTS.md situados entre la raíz del proyecto y el directorio de trabajo actual (más el archivo global en ~/.codex). Un archivo en un subdirectorio fuera de esta ruta no se carga, contrariamente a lo que implicaba la versión anterior. Fuente: AGENTS.md.

Dominio del archivo de configuración de Codex

Descubriste AGENTS.md en la Lección 3. Aquí profundizamos en patrones avanzados: la diferencia entre un archivo decorativo (tres líneas escritas al inicio y olvidadas) y uno que realmente dirige el comportamiento del agente en un proyecto activo.

La jerarquía de AGENTS.md

Codex lee estos archivos de forma jerárquica, de lo general a lo específico: primero el archivo global en tu carpeta de Codex (~/.codex/AGENTS.md, o AGENTS.override.md si existe) y, a continuación, empezando desde la raíz del proyecto, los archivos de los directorios recorridos hasta el directorio de trabajo actual. En un proyecto estructurado, el árbol tiene este aspecto:

mon-projet/
  AGENTS.md                    → Reglas globales (baja prioridad)
  src/
    AGENTS.md                  → Reglas para todo el código fuente
    api/
      AGENTS.md                → Reglas específicas para APIs
      routes/
        AGENTS.md              → Reglas para rutas
    components/
      AGENTS.md                → Reglas para componentes React
  tests/
    AGENTS.md                  → Reglas para pruebas

Las reglas se acumulan: Codex concatena los archivos desde la raíz hasta el directorio actual, y aquellos más cercanos a dicho directorio, leídos en último lugar, anulan las instrucciones generales. Hay un punto que se malinterpreta con facilidad: solo se leen los directorios que están en la ruta entre la raíz y el directorio actual. Si tu archivo raíz prohíbe any mientras que tests/AGENTS.md permite aserciones más laxas en los mocks, esa tolerancia solo se aplica cuando Codex trabaja desde tests/ o uno de sus subdirectorios; si se lanza desde la raíz, no lee tests/AGENTS.md. La revisión de código de GitHub funciona de manera distinta: Codex busca en todo el repositorio archivos AGENTS.md y aplica las reglas de revisión (## Code Review Rules) del archivo más cercano al código en cuestión. La concatenación se detiene en 32 KiB por defecto (project_doc_max_bytes): un archivo demasiado largo se trunca.

Las secciones que conforman el archivo

El contexto va primero, porque determina cada decisión posterior. Una aplicación SaaS sujeta al RGPD (Reglamento General de Protección de Datos) no se programa igual que una herramienta interna para cinco personas:

## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.

Al saber que maneja datos sujetos al RGPD, Codex añadirá las protecciones esperadas sin que tengas que especificarlas en cada petición. A continuación vienen las convenciones, que responden a una pregunta: ¿qué aspecto tiene el código correcto aquí?

## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components, 
  camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)

La sección de comandos es la que se omite con más frecuencia, y su ausencia tiene un coste: sin estos comandos, Codex no puede verificar su propio trabajo y devuelve código que nunca ha ejecutado ni probado.

## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed

Las reglas estrictas forman la barrera de seguridad. Formuladas como «NUNCA» y «SIEMPRE», evitan errores que cuestan toda una tarde solucionar: una migración de Prisma eliminada que tendrás que reconstruir desde producción, un secreto confirmado que necesita revocación, o un innerHTML colado en un componente que abre una vulnerabilidad XSS.

## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations

Por último, la arquitectura describe el flujo permitido entre capas. Sin ella, Codex produce código que funciona pero que hace un cortocircuito en tu estructura: una ruta que consulta Prisma directamente, por ejemplo, porque era el camino más corto.

## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access

Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.

A esto se añaden, proyecto a proyecto, instrucciones específicas para cada tecnología utilizada:

## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand

## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE

Dos patrones que previenen sorpresas

Declarar las variables de entorno esperadas evita que Codex invente nombres de claves al escribir un script o que registre accidentalmente un valor sensible en un rastro de depuración:

## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)

Nombrar tus bibliotecas preferidas, y especialmente aquellas que rechazas, resuelve una molestia recurrente: el agente instala una dependencia que es perfectamente válida en sí misma, pero que tu equipo rechazó hace dos años tras una mala experiencia.

## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)

Mantener el archivo vivo

AGENTS.md evoluciona con tu código, igual que una prueba o un README. Actualízalo en cuanto adoptes una nueva convención, cambies de bibliotecas o frameworks, y especialmente en cuanto identifiques un error recurrente de Codex: ese último caso siempre señala una instrucción faltante más que un fallo del modelo. Hay un cuarto desencadenante, más sutil, que merece la pena vigilar: cuando un nuevo desarrollador hace una pregunta que AGENTS.md debería haber respondido, esa respuesta pertenece al archivo.

Puntos clave

  • La jerarquía de AGENTS.md permite instrucciones cada vez más específicas
  • Los comandos son críticos para que Codex verifique su trabajo
  • Las reglas NUNCA son las más importantes para evitar errores
  • Documenta las dependencias preferidas para evitar malas elecciones
  • Mantén AGENTS.md como código vivo