Reglas de Cursor para producción: Next.js, React TypeScript y FastAPI [Guía 2026]

Los asistentes de código por IA suelen apoyarse en sintaxis anticuadas a menos que establezcas límites precisos. En proyectos web modernos, Cursor sugiere a menudo métodos obsoletos del antiguo router Pages de Next.js, incluye tipos any en componentes de React o redacta consultas síncronas bloqueantes en rutas asíncronas de Python FastAPI.

Las reglas de Cursor aportan pautas para reducir estas desviaciones antes de que se incorporen a tu historial de git. Los archivos de .cursor/rules/ añaden instrucciones al contexto del modelo; no garantizan su cumplimiento ni eliminan errores o alucinaciones. Debes revisar los cambios y ejecutar las comprobaciones del proyecto.

A 22 de octubre de 2026, la documentación de modelos de Cursor incluye Opus 5.5, Sonnet 5.5, Gemini 4 Argon y GPT 5.6 Sol, entre otros. El acceso depende del plan y de la configuración; las reglas no habilitan modelos adicionales.

A continuación encontrarás plantillas de reglas listas para producción en Next.js, React TypeScript y FastAPI en 2026, junto con una guía práctica para organizar reglas modulares.

Archivo raíz .cursorrules frente a reglas modulares .cursor/rules/*.mdc

Respuesta directa: Cursor admite archivos modulares .cursor/rules/*.mdc y sigue admitiendo el archivo heredado .cursorrules. Según la documentación de reglas, con alwaysApply: false, los patrones glob adjuntan instrucciones cuando un archivo coincidente entra en el contexto, como src/app/**/*.tsx para Next.js o backend/**/*.py para FastAPI. Esto ayuda a seleccionar instrucciones pertinentes, pero exige revisar los resultados.

En un principio, Cursor dependía de un único archivo .cursorrules situado en la raíz del repositorio. Aunque es una opción rápida de configurar, obliga a que cada consulta cargue instrucciones de todo el stack tecnológico, consumiendo tokens de contexto innecesarios y provocando directrices enfrentadas entre frontend y backend.

Las versiones actuales de Cursor admiten reglas modulares en formato .cursor/rules/*.mdc. Cada archivo .mdc combina un encabezado YAML con directrices técnicas redactadas en Markdown:

---
description: Breve descripción de la regla
globs: patron/destinado/a/archivos/**
alwaysApply: false
---

# Tus directrices técnicas aquí

Opciones de YAML clave

• globs: un patrón de concordancia de archivos (como src/app/**/*.tsx o backend/**/*.py). Con alwaysApply: false, adjunta la regla cuando un archivo coincidente está en el contexto.

• alwaysApply: se establece en true únicamente para normas de todo el proyecto (como formatos de commit o licencias). Debe mantenerse en false para reglas técnicas de frameworks.

• description: define el alcance de la regla y facilita su selección automática por parte de Cursor en consultas con @.

Si deseas contrastar el asistente en editor de Cursor con un agente autónomo de terminal, consulta nuestro análisis completo de Claude Code vs Cursor.

1. Mejores reglas de Cursor para Next.js (App Router)

Guarda este archivo con el nombre .cursor/rules/nextjs.mdc. Orienta al modelo sobre las convenciones del App Router, la separación de datos del servidor y la obtención de datos en Server Components; verifica los cambios antes de aceptarlos.

---
description: Estándares para Next.js App Router y Server Components
globs: src/app/**/*.{ts,tsx},app/**/*.{ts,tsx}
alwaysApply: false
---

# Reglas de arquitectura en Next.js

## Separación entre componentes de servidor y cliente
- Priorizar React Server Components (RSC) por defecto. No incluir "use client" salvo que el componente precise useState, useEffect, eventos de navegador o APIs de ventana.
- Mantener los componentes cliente en las hojas del árbol de renderizado. Pasar datos desde Server Components mediante props serializables.
- Prohibir terminantemente la importación de librerías exclusivas de servidor (clientes de base de datos, claves privadas) en componentes cliente.

## Obtención de datos y mutaciones
- Consultar datos directamente en Server Components utilizando async/await. Prescindir de la carga con useEffect.
- Emplear Server Actions de Next.js para formularios y modificaciones de estado. Agrupar acciones en el componente o en `actions.ts` con la directiva "use server" al inicio del archivo.
- Validar siempre las entradas de las Server Actions mediante esquemas Zod antes de acceder a la base de datos.
- Revalidar la caché de rutas tras una mutación correcta usando `revalidatePath()` o `revalidateTag()`.

## Enrutamiento y navegación
- Utilizar `next/link` para navegación interna; evitar etiquetas nativas `<a>` para enlaces locales.
- Leer parámetros de consulta con las props de página o `useSearchParams()`. Proteger con Suspense los componentes que analicen parámetros de búsqueda.

2. Mejores reglas de Cursor para React y TypeScript

Guarda este archivo con el nombre .cursor/rules/react-typescript.mdc. Solicita tipos precisos, exports nombrados y patrones de interfaz consistentes; comprueba su cumplimiento con revisión y herramientas de análisis.

---
description: Estándares para React y TypeScript
globs: **/*.{ts,tsx}
alwaysApply: false
---

# Directrices para React y TypeScript

## Rigor con TypeScript
- No emplear jamás el tipo `any`. Recurrir a `unknown` para entradas arbitrarias y estrechar tipos con guardas.
- Preferir `interface` para estructuras de objetos y props de componentes. Emplear `type` para uniones e intersecciones.
- Exigir tipos de retorno explícitos en las funciones exportadas.
- Evitar aserciones de no nulidad (`!`). Controlar valores nulos o indefinidos con encadenamiento opcional (`?.`) o valores por defecto.

## Arquitectura de componentes
- Emplear únicamente exports con nombre: `export function UserProfile(...)`. Descartar `export default`.
- Declarar la interfaz de props justo encima del componente usando la nomenclatura `<NombreComponente>Props`.
- Desestructurar las props en la firma: `function Button({ variant = "primary", children }: ButtonProps)`.
- Aislar lógica compleja en custom hooks con el prefijo `use`.

## Estilos y accesibilidad
- Aplicar directamente las clases de utilidad de Tailwind CSS. No utilizar estilos inline `style={{ ... }}`.
- Concatenar clases condicionales mediante utilidades como `cn()` (clsx + tailwind-merge).
- Asegurar accesibilidad completa en elementos interactivos (`aria-label`, soporte para teclado).

3. Mejores reglas de Cursor para Python y FastAPI

Guarda este archivo con el nombre .cursor/rules/fastapi.mdc. Solicita controladores asíncronos sin bloqueos, modelos de Pydantic v2 e inyección de dependencias reglamentada; valida el resultado con pruebas.

---
description: Estándares para Python FastAPI y Pydantic
globs: **/*.py,backend/**/*.py,api/**/*.py
alwaysApply: false
---

# Reglas de desarrollo en FastAPI

## Controladores de ruta asíncronos
- Definir cualquier endpoint que realice operaciones de I/O obligatoriamente con `async def`.
- No ejecutar operaciones síncronas bloqueantes (como `requests.get()`, `time.sleep()` o conectores SQL síncronos) dentro de rutas asíncronas.
- Utilizar `httpx.AsyncClient` para peticiones HTTP salientes y controladores asíncronos para la base de datos.

## Modelos Pydantic v2
- Desacoplar las cargas útiles de entrada, las respuestas de API y las tablas de base de datos en modelos específicos.
- Identificar esquemas con nombres descriptivos: `UserCreateRequest`, `UserUpdatePayload`, `UserResponse`.
- Añadir siempre `from_attributes = True` en `model_config` al transformar entidades ORM.
- Emplear `Field()` con restricciones precisas (`min_length`, `gt`, `le`) y ejemplos explicativos.

## Inyección de dependencias y seguridad
- Proveer sesiones de base de datos y contextos de usuario mediante el patrón `Depends()` de FastAPI.
- Encapsular operaciones de base de datos en gestores de contexto asíncronos para garantizar el cierre adecuado de conexiones.
- Emitir excepciones con `HTTPException` y códigos HTTP explícitos en lugar de devolver diccionarios de error sin formato.

Coordinación de reglas de Cursor con agentes de terminal

Si en tu organización también utilizáis Claude Code para refactorizaciones profundas o suites de pruebas en consola, conviene mantener alineadas las normas del repositorio. Mientras Cursor lee .cursor/rules/*.mdc, Claude Code consulta CLAUDE.md y paquetes modulares de skills.

Descubre cómo automatizar pruebas y revisiones de código en nuestro artículo sobre las mejores skills de Claude Code para desarrolladores, o examina el catálogo general de habilidades técnicas verificadas.

Cómo verificar y probar tus reglas de Cursor

Una vez guardados los archivos en .cursor/rules/, comprueba que se carguen correctamente:

1. Comprobar la asociación por globs: abre un archivo objetivo (por ejemplo src/app/page.tsx).

2. Abrir Cursor Chat (Cmd+L): revisa la etiqueta de contexto en la parte baja del panel. Debe figurar nextjs.mdc entre las reglas activas del proyecto.

3. Forzar una regla manualmente: escribe @ en el chat, haz clic en Rules y escoge el archivo que desees asociar.

4. Verificar en Composer (Cmd+I): solicita la generación de un componente y confirma que el diff cumpla las normas requeridas (exports con nombre y tipado estricto).

Errores habituales que conviene evitar

Para preservar la fluidez y precisión de Cursor, esquiva estos cuatro fallos usuales:

1. Exceso de contenido: no vuelques el manual de estilo completo de tu compañía. Mantén cada archivo .mdc por debajo de las 80 líneas con instrucciones directas.

2. Alcance mal configurado: comprueba globs y alwaysApply; una regla sin globs puede incorporarse mediante otros modos de selección o de forma manual.

3. Instrucciones opuestas: asegura coherencia entre el .cursorrules central y las reglas modulares para evitar respuestas contradictorias.

4. Pautas ambiguas: sustituye declaraciones indeterminadas como "escribe código limpio" por directrices tangibles como "limitar las funciones a un máximo de 40 líneas".

Cuadro comparativo final

Al definir archivos modulares .cursor/rules/*.mdc, conviertes a Cursor en un copiloto técnico especializado, ajustado con exactitud a la arquitectura de producción de tu empresa.