Monorepos y Jerarquias

El problema de un solo archivo

En un monorepo con 5 paquetes, un unico AGENTS.md en la raiz se vuelve problematico:

• Demasiadas instrucciones para que el agente las siga todas
• Instrucciones del frontend mezcladas con las del backend
• El agente recibe contexto irrelevante para el paquete en el que trabaja

AGENTS.md jerarquico

AGENTS.md soporta archivos anidados. El agente lee el mas cercano al directorio donde trabaja:

mi-monorepo/
├── AGENTS.md                    # Instrucciones globales
├── packages/
│   ├── api/
│   │   ├── AGENTS.md            # Instrucciones del API
│   │   └── src/
│   ├── web/
│   │   ├── AGENTS.md            # Instrucciones del frontend
│   │   └── src/
│   └── shared/
│       ├── AGENTS.md            # Instrucciones de shared libs
│       └── src/

Raiz: contexto global

# AGENTS.md (root)

E-commerce monorepo with pnpm workspaces.

## Workspace commands
- Install all: `pnpm install`
- Build all: `pnpm -r build`
- Test all: `pnpm -r test`

## Shared conventions
- TypeScript strict in all packages
- Biome for formatting and linting
- Commits: `feat(package): description`

## Navigation
- API: `packages/api/`
- Frontend: `packages/web/`
- Shared types: `packages/shared/`

Paquete: contexto especifico

# AGENTS.md (packages/api/)

REST API for the e-commerce platform. Express 5 + Prisma + PostgreSQL.

## Commands
- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test`
- Test file: `pnpm vitest run path/to/file.test.ts`
- Migrate: `pnpm prisma migrate dev`

## Architecture
Hexagonal architecture:
- `src/domain/` - entities, value objects
- `src/application/` - use cases, ports
- `src/infrastructure/` - adapters, repositories

## Boundaries
- Never modify Prisma schema without asking first
- Never expose internal domain types in API responses

Resolucion de conflictos

Cuando un agente trabaja en packages/api/src/, lee instrucciones en este orden:

Prioridad	Fuente
1 (maxima)	Prompt del usuario
2	packages/api/AGENTS.md
3	AGENTS.md (raiz)

Las instrucciones mas cercanas ganan sobre las mas lejanas. Si la raiz dice “use npm” pero el paquete dice “use pnpm”, el agente usa pnpm.

AGENTS.override.md

Algunos agentes (como Codex) soportan archivos override que toman prioridad maxima:

packages/api/
├── AGENTS.md              # Instrucciones base
├── AGENTS.override.md     # Override temporal (ej: sprint especifico)
└── src/

El override es util para instrucciones temporales que no quieres mezclar con las permanentes. Ejemplo: durante una migracion de base de datos.

Progressive disclosure

En vez de poner todo en un archivo gigante, usa una jerarquia de documentos:

Raiz: minimo viable

# AGENTS.md

E-commerce API. TypeScript + Express + PostgreSQL.

- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`

For TypeScript conventions, see `docs/TYPESCRIPT.md`.
For testing patterns, see `docs/TESTING.md`.
For API design, see `docs/API-DESIGN.md`.

Documentos de detalle

docs/
├── TYPESCRIPT.md     # Convenciones TS detalladas
├── TESTING.md        # Patrones de test completos
├── API-DESIGN.md     # Diseno de endpoints
└── SECURITY.md       # Politicas de seguridad

Los agentes navegan jerarquias de forma eficiente. Leen el AGENTS.md raiz y luego consultan los documentos de detalle solo cuando lo necesitan.

Beneficios

• Menos tokens: el agente solo carga lo relevante
• Mantenibilidad: cada documento tiene un scope claro
• Escalabilidad: agregar areas nuevas no infla el archivo principal

Limite de tamano

Codex impone un limite de 32 KiB por defecto para el contenido combinado de AGENTS.md. Otros agentes tienen limites similares.

Regla practica: si tu AGENTS.md supera 200 lineas, es hora de dividirlo.

Patron para equipos

Si multiples equipos trabajan en el monorepo, cada equipo mantiene su AGENTS.md:

AGENTS.md                          # Platform team
packages/
├── payments/AGENTS.md             # Payments team
├── users/AGENTS.md                # Users team
└── notifications/AGENTS.md        # Notifications team

Cada equipo es responsable de mantener actualizado su archivo. El AGENTS.md raiz contiene solo las convenciones compartidas.

Resumen

• Monorepos usan AGENTS.md anidados: el mas cercano al directorio de trabajo gana
• La raiz tiene convenciones globales; cada paquete tiene las suyas
• Progressive disclosure: archivo raiz minimo con links a documentos de detalle
• Si supera 200 lineas, dividelo
• AGENTS.override.md para instrucciones temporales sin contaminar el archivo base

---

← Capitulo 3: Secciones Esenciales | Capitulo 5: Sistema de Boundaries →