Reglas de Agente (.cursorrules / CLAUDE.md / AGENTS.md)

1. Visión general del concepto y problema sistémico

Los LLM modernos se entrenan en gigabytes de código abierto de GitHub, por lo que, por defecto, generan código "promedio": versiones principales obsoletas de bibliotecas, patrones de importación caóticos, any en TypeScript o enfoques ineficientes para el manejo de errores. Cuando un ingeniero trabaja en la paradigma de vibecoding sin reglas fijas, cada nuevo prompt se convierte en una lotería:

• El agente establece moment.js o axios obsoletos en lugar de date-fns nativo o fetch.
• El agente mezcla capas arquitectónicas (por ejemplo, accediendo directamente a la base de datos desde un componente React del cliente).
• El agente inventa sus propios comandos de compilación o prueba en lugar de usar los scripts existentes en el proyecto.

Agent Rules (archivos .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) abordan el problema del drift de la base de código. Transforman la convención interna del equipo en un contrato sistémico que es leído por el entorno de desarrollo o el agente de terminal antes de que comience la generación de cualquier código.

2. Taxonomía arquitectónica y modelo mental

Las reglas del repositorio se dividen en tres niveles de aislamiento y activación:

┌─────────────────────────────────────────────────────────────┐
│                   NIVELES DE REGLAS DEL AGENTE             │
├─────────────────────────────────────────────────────────────┤
│ 1. Global / Machine Layer (~/.cursorrules, ~/.claude.json)   │
│    Preferencias de un desarrollador específico (lenguaje, estilo de respuestas)│
├─────────────────────────────────────────────────────────────┤
│ 2. Repository Core Layer (CLAUDE.md, AGENTS.md, reglas raíz)  │
│    Stack global, bibliotecas prohibidas, comandos lint / test │
├─────────────────────────────────────────────────────────────┤
│ 3. Scoped / Event-Driven Rules (.cursor/rules/*.mdc)         │
│    Activación por patrón glob (por ejemplo, rutas API, UI, DB) │
└─────────────────────────────────────────────────────────────┘

1. Reglas globales del repositorio (Core Repository Contract):
   • Se ubican en la raíz del proyecto (CLAUDE.md para Claude Code, AGENTS.md o .cursorrules para editores).
   • Describen el mínimo crítico: versiones del entorno (Node.js 22, Bun, Python 3.12), gestor de paquetes (pnpm), linter obligatorio e instrucciones sobre la estructura de commits.
2. Reglas modulares contextuales (Scoped Domain Rules):
   • Archivos con metadatos y patrones glob (por ejemplo, .cursor/rules/database.mdc con filtro src/db/**/*.ts).
   • Se cargan en la memoria de trabajo del modelo únicamente cuando el agente planea editar archivos de migraciones o modelos ORM.
3. Restricciones operativas (Operational Guardrails):
   • Restricciones negativas claras (Negative Constraints): "NUNCA ejecutar git push --force", "NUNCA modificar .env.production", "NO agregar nuevas dependencias sin el consentimiento explícito del ingeniero".

3. Pipeline técnico y mecánica interna

El ciclo de vida de las reglas durante una sesión de vibecoding:

1. Inicialización de la sesión y escaneo del repositorio: IDE o agente CLI escanea la carpeta raíz y el directorio de servicio .cursor/rules/ o .agents/rules/ al inicio.
2. Análisis de intención y coincidencia de patrones (Glob Matching): El usuario envía una solicitud ("Crea un nuevo endpoint para el pago de suscripciones"). El agente predice el cambio de archivos en src/app/api/stripe/route.ts. El motor de reglas activa las reglas para src/app/api/**/*.ts y stripe.mdc.
3. Construcción del prompt sistémico extendido: El motor concatena:
   • El System Prompt base del modelo;
   • El contenido del archivo del contrato global;
   • Las reglas modulares encontradas;
   • El árbol actual de archivos abiertos y la solicitud del usuario.
4. Generación de código con cumplimiento forzado de invariantes: El modelo forma una llamada a la herramienta o código, refiriéndose a las reglas como contexto sistémico obligatorio.
5. Validación post-generación: Si el agente tiene acceso a la terminal, ejecuta el comando de validación especificado en las reglas (por ejemplo, pnpm typecheck), antes de devolver el informe final al ingeniero.

4. Escenarios prácticos de ingeniería en producción

01. Límites arquitectónicos en Next.js 15+ App Router

El archivo .cursor/rules/nextjs.mdc con el patrón src/app/**/*.tsx previene errores clásicos en el uso de componentes del servidor y del cliente:

---
description: Estándares arquitectónicos de Next.js App Router
globs: src/app/**/*.tsx, src/components/**/*.tsx
---
- Por defecto, todos los componentes son Server Components.
- La directiva 'use client' debe añadirse SOLO si hay useState, useEffect o manejadores de eventos onClick/onChange.
- PROHIBIDO importar utilidades del servidor (db, auth secret) en archivos con 'use client'.
- Todas las mutaciones de datos deben realizarse exclusivamente a través de Server Actions en el directorio `src/actions/`.

02. Ejecución determinista de pruebas para Claude Code

La configuración CLAUDE.md garantiza que el agente de terminal utilice exclusivamente los scripts de prueba correctos sin intentar ejecutar un jest global incompatible:

# Directrices del Repositorio para Claude Code

## Comandos
- Construir: `pnpm build`
- Verificación de tipos: `pnpm tsc --noEmit`
- Pruebas Unitarias: `pnpm test:unit`
- Pruebas E2E: `pnpm test:e2e`

## Disciplina del Flujo de Trabajo
Antes de notificar sobre la finalización exitosa de la tarea:
1. Ejecuta `pnpm tsc --noEmit`. Si hay errores de tipado, corrígelos.
2. Ejecuta `pnpm test:unit` para los módulos modificados.
3. No crees nuevos archivos sin verificar previamente la existencia de utilidades en `src/lib/`.

03. Forzando la seguridad de tipos y validación Zod en API

La regla para el backend impide el uso de payloads JSON no tipados en los controladores:

---
description: Estandarización de endpoints del backend
globs: src/server/api/**/*.ts
---
- Todos los argumentos de entrada de las solicitudes deben ser analizados a través de esquemas Zod (`schema.parseAsync(req.body)`).
- El tipo `any` está estrictamente prohibido; al trabajar con datos desconocidos, usar `unknown` seguido de un narrowing de tipo.
- En caso de errores de negocio, lanzar un `TRPCError` tipificado o `HttpError` con el código de estado correspondiente.

5. Errores comunes, trampas y seguridad

• Regla de acumulación (Rule Bloat & Attention Saturation): Intentar documentar toda la documentación del proyecto en un archivo de reglas lleva a archivos de más de 500 líneas. Esto agota la atención del modelo ("Lost in the Middle") y provoca que el modelo comience a ignorar instrucciones clave. Divida las reglas en scopes modulares.
• Reglas contradictorias o en conflicto: Si el CLAUDE.md global requiere el uso de pnpm, y un README.md obsoleto o una regla local contiene npm install, el modelo puede entrar en un ciclo de alucinaciones del gestor de paquetes.
• Riesgo de filtración de datos sensibles: Nunca incluya tokens de acceso, contraseñas de bases de datos de prueba o claves API personales en las reglas del repositorio. Todas las variables de entorno deben describirse solo como nombres abstractos (por ejemplo, DATABASE_URL is required in .env.local).
• Falta de versionado: Las reglas de los agentes deben evolucionar junto con la base de código en el sistema de control de versiones Git. El cambio de stack tecnológico debe ir acompañado de una actualización atómica de los archivos de reglas correspondientes en el mismo commit.