Guía completa de Cursor Rules: haz que la IA genere código conforme a tus normas (con configuración práctica)

Mirando el código que Cursor acaba de generar, con el dedo sobre Enter — por tercera vez.

La primera usó var para declarar variables; la segunda pasó a componentes de clase; esta vez borró todos los tipos TypeScript y añadió un montón de any. Borras el código, pensando en escribirlo a mano.

En ese momento caes en la cuenta: la IA no es tonta — simplemente no le dijiste «cuáles son mis reglas».

Cuando empecé con Cursor, pensaba que la IA «debería saber» qué es buen código. Hasta que el equipo se quejó: «¿por qué los componentes que genera Cursor no siguen nuestro estilo?». Entonces entendí: la IA necesita normas claras.

Este artículo resuelve eso. Configura Cursor Rules en 5 minutos y la IA generará código alineado con tu proyecto — sin stack equivocado ni estilo incoherente.

¿Qué es Cursor Rules? ¿Por qué lo necesitas?

La esencia de Cursor Rules: ponerle reglas a la IA

En pocas palabras, Cursor Rules es un archivo de configuración que le dice a la IA tus normas de codificación.

Como el manual de onboarding que la empresa entrega a un nuevo desarrollador: qué stack usamos, cómo nombrar el código, cómo organizar archivos. Cursor Rules hace lo mismo — le da a la IA su «manual de incorporación».

El funcionamiento es directo: cuando hablas con Cursor, el contenido de las reglas se adjunta al prompt. La IA lee «este proyecto usa React Hooks, no componentes de clase» y genera código acorde.

¿Qué pasa si no configuras Rules? Mi lección aprendida

La primera vez que usé Cursor en un proyecto pensé que había encontrado un tesoro — la IA escribía a toda velocidad. Tres días después vi el problema:

Estilo de código caótico. Unos archivos con camelCase, otros con PascalCase, algunos con snake_case. Ni yo recordaba cuál era cuál.

Stack equivocado. Quería componentes funcionales y Cursor generaba class Component extends React.Component. Le decía «usa Hooks» y en el siguiente archivo volvía atrás.

Incumplimiento de normas del equipo. Todas las funciones debían llevar comentarios; el código de Cursor iba limpio — sin una línea. Y el manejo de errores: la norma exigía try-catch, pero la IA llamaba APIs a pelo.

Después pasé dos días refactorizando hasta que me dolieron las manos.

¿Y después de configurar Rules? Vale la pena

Luego invertí 5 minutos en un archivo .cursorrules con:

• Stack: React 18 + TypeScript
• Solo componentes funcionales y Hooks
• Nombres en camelCase
• Tipos obligatorios, prohibido any

¿El resultado?

Desde entonces, cada componente cumple las normas. La coherencia subió al menos un 80%; el code review se redujo a la mitad. El equipo preguntaba «¿cómo hiciste que Cursor obedezca tanto?».

Vale la pena.

Los datos no mienten: según buenas prácticas de la comunidad, unas Rules bien configuradas mejoran mucho la coherencia y reducen refactorizaciones. awesome-cursorrules en GitHub ya supera las 2000 estrellas — es una necesidad real de los desarrolladores.

Métodos de configuración de Cursor Rules (2026)

Lo importante: cambio entre métodos antiguo y nuevo

Si buscas tutoriales, verás .cursorrules y .cursor/rules. No te preocupes: ambos son válidos, solo de épocas distintas.

Método antiguo (antes de 2025):
Un archivo .cursorrules en la raíz con todas las reglas. Simple y directo.

Método nuevo (recomendado en 2026):
Directorio .cursor/rules con varios archivos .mdc, cada uno para una categoría.

El equipo oficial recomienda migrar: más flexibilidad, reglas por función y distintos alcances. El antiguo aún funciona, pero quedará obsoleto.

Mi consejo: proyecto nuevo → método nuevo; proyecto existente → migra cuando puedas.

Dos niveles: global vs proyecto

Cursor soporta dos niveles; conviene entender la diferencia.

User Rules (reglas globales)

Tus preferencias personales, en todos los proyectos.

Ruta: File → Preferences → Cursor Settings → Rules → User Rules

Casos de uso: normas transversales, por ejemplo:

• «Todos mis proyectos usan TypeScript»
• «Odio var; uso const o let»
• «Toda operación asíncrona con async/await, no .then()»

Piénsalo como tu «obsesión por el código limpio» personal.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Project Rules (reglas del proyecto)

Normas de un solo proyecto.

Configuración:

1. Crea la carpeta .cursor en la raíz
2. Dentro, la carpeta rules
3. Archivos .mdc, p. ej. frontend.mdc o typescript-rules.mdc

Casos de uso: stack y normas del proyecto, por ejemplo:

• «Proyecto Next.js 14 + TypeScript + Tailwind CSS»
• «APIs RESTful»
• «Componentes en components/, nombres PascalCase»

Prioridad clara: reglas del proyecto > reglas globales.

Alcance de las reglas: que no abarquen de más

Novedad importante de 2026: controlar cuándo aplican.

En cada .mdc puedes definir:

Always (siempre activo): sin importar qué hagas. Para normas centrales como «prohibido var». Con cuidado: demasiadas reglas Always saturan el contexto.

Auto Attached (adjunto automático): según el tipo de archivo. Por ejemplo .tsx → reglas React, .py → Python. Mi opción favorita.

Agent Requested (la IA decide): según la conversación. Para reglas auxiliares opcionales.

Manual (invocación manual): solo cuando lo pidas. Para «reglas de rendimiento» o «reglas de pruebas».

En la práctica: 80% Auto Attached, 10% Always, 10% el resto según caso.

Novedad enero 2026: comando /rules

El 8 de enero de 2026, Cursor publicó una actualización del CLI con el comando /rules.

En la terminal de Cursor escribes /rules y creas o editas reglas sin buscar carpetas. Ahorra tiempo si las ajustas a menudo.

Detalles en el anuncio del foro oficial de Cursor.

¿Cómo escribir Cursor Rules efectivas?

Esta es la parte clave. La calidad de las reglas determina si Cursor te obedece.

Tres categorías de contenido

Al configurar, te recomiendo tres capas:

A. Tecnología y arquitectura

Primero, qué proyecto es.

Stack del proyecto:
- Frontend: React 18 + TypeScript 5.3
- Estado: Zustand
- Estilos: Tailwind CSS 3.4
- Build: Vite 5.0
- Node.js: 18+

Y las normas de arquitectura:

Normas de arquitectura:
- Separación frontend/backend
- API estilo RESTful
- Estructura de carpetas:
  - components/ componentes reutilizables
  - pages/ componentes de página
  - utils/ utilidades
  - hooks/ Hooks personalizados

¿Por qué tanto detalle?

Lo aprendí a las malas. Solo puse «usa React» y Cursor alternaba entre React 16 y 18. Al poner versiones, desapareció el problema.

B. Normas de código

Aquí unifica el estilo.

Normas de código:

Nombres:
- Componentes: PascalCase (ej. UserProfile)
- Archivos: kebab-case (ej. user-profile.tsx)
- Variables y funciones: camelCase (ej. getUserData)
- Constantes: UPPER_SNAKE_CASE (ej. MAX_RETRY_COUNT)

Estilo:
- Solo componentes funcionales, no de clase
- Priorizar const, luego let, prohibido var
- Funciones flecha, no function (salvo que necesites this)
- Todos los componentes con tipos TypeScript

Longitud:
- Archivo ≤300 líneas
- Función ≤50 líneas

Comentarios:
- Funciones clave con JSDoc
- Lógica compleja con comentarios inline
- Comentar el «por qué», no el «qué»

C. Calidad y pruebas

Manejo de errores:
- Operaciones asíncronas con try-catch
- Errores de API con mensajes claros al usuario
- No tragar errores; al menos console.error

Rendimiento:
- Listas con key
- Listas grandes con scroll virtual
- Imágenes con ancho y alto para evitar layout shift

Pruebas:
- Utilidades con tests unitarios
- Lógica de negocio crítica con cobertura

Principios de oro al escribir reglas

Principio 1: concreto, ejecutable, verificable

El más importante.

❌ Mal: «Escribe buen código», «Sigue mejores prácticas», «Cuida el rendimiento»

La IA no sabe qué «mejor práctica» quieres.

✅ Bien:

• «Usa componentes funcionales, no de clase»
• «Props con interface, no type»
• «Async con async/await, no .then()»

Buenas reglas = instrucciones directas, no consejos vagos.

Principio 2: menos de 500 líneas

Práctica comunitaria. Demasiado largo dificulta la comprensión y ocupa contexto.

Si superas 500 líneas, divide:

• frontend.mdc
• backend.mdc
• typescript.mdc
• testing.mdc

Principio 3: ejemplos de código, no solo texto

A la IA le encantan los ejemplos.

❌ Solo texto:

Escribe componentes funcionales con tipos

✅ Con ejemplo:

Ejemplo de componente:

interface UserCardProps {
  name: string;
  email: string;
}

export const UserCard = ({ name, email }: UserCardProps) => {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

Con ejemplo, Cursor sabe exactamente qué quieres.

Principio 4: reglas importantes al principio

La IA prioriza lo que está arriba:

1. Stack y versiones
2. Estilo de código
3. Organización de archivos
4. Optimizaciones opcionales

Errores frecuentes

Error 1: reglas demasiado amplias

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

«Sigue las mejores prácticas de React» — ¿de 2016 o 2024?

Mejor: «Usa React Hooks; useState y useEffect primero; estado complejo con useReducer»

Error 2: reglas contradictorias

«TypeScript obligatorio» y «permitido any» — ¿cuál gana?

La IA se confunde y puede ignorar ambas.

Error 3: olvidar versiones

React 16 (clases) vs React 18 (Hooks) son mundos distintos. Especifica React 18.2+, TypeScript 5.3+, Node.js 18+.

Error 4: reglas como tesis

No hace falta convencer a la IA con teoría.

❌ «Elegimos TypeScript por el tipado estático que detecta errores en compilación…» (300 palabras más)

✅ «Usa TypeScript; prohibido any»

Directo y claro.

Práctica: configurar reglas para React + TypeScript

Menos teoría, un ejemplo real.

Proyecto React + TypeScript:

• React 18
• TypeScript 5.x
• Tailwind CSS 3.x
• Vite 5.x

Normas del equipo:

• Solo componentes funcionales
• Tipos estrictos, prohibido any
• Nombres y archivos uniformes
• Manejo de errores obligatorio

Paso a paso.

Paso 1: crear el archivo de reglas

En la raíz del proyecto:

mkdir -p .cursor/rules
cd .cursor/rules
touch react-typescript.mdc

Paso 2: definir el stack

Abre react-typescript.mdc:

# Reglas del proyecto React + TypeScript

## Stack tecnológico

- React 18.2+
- TypeScript 5.3+
- Tailwind CSS 3.4+
- Vite 5.0+
- Node.js 18+

## Gestión de dependencias

- Gestor: pnpm
- No uses npm ni yarn

Paso 3: normas de estilo

## Normas de código

### Componentes

- Solo componentes funcionales, prohibidos los de clase
- Nombre del componente en PascalCase
- Nombre del archivo en kebab-case
- Exportación nombrada, no default

Ejemplo:

// ❌ Incorrecto
export default function userProfile() { }

// ✅ Correcto
export const UserProfile = () => { }

### TypeScript

- Todos los componentes con tipos
- Props con interface, no type
- Prohibido any; usa unknown o tipos concretos
- Retorno de funciones explícito

Ejemplo:

// ✅ Definición correcta
interface UserCardProps {
  name: string;
  email: string;
  age?: number;
}

export const UserCard = ({ name, email, age }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded">
      <h3 className="text-lg font-bold">{name}</h3>
      <p className="text-gray-600">{email}</p>
      {age && <p>Age: {age}</p>}
    </div>
  );
};

### Nombres

- Variables y funciones: camelCase
- Componentes: PascalCase
- Constantes: UPPER_SNAKE_CASE
- Archivos: kebab-case
- CSS: clases Tailwind, sin CSS personalizado

### Operaciones asíncronas

- async/await obligatorio
- Prohibido encadenar .then()
- try-catch obligatorio

Ejemplo:

// ✅ Correcto
const fetchUserData = async (userId: string): Promise<User> => {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
};

Paso 4: organización de archivos

## Organización de archivos

### Estructura

src/
├── components/     # Componentes reutilizables
├── pages/          # Páginas
├── hooks/          # Hooks personalizados
├── utils/          # Utilidades
├── types/          # Tipos TypeScript
├── services/       # Llamadas API
└── constants/      # Constantes

### Nombres de archivo

- Componente: user-card.tsx
- Utilidad: format-date.ts
- Tipos: user.types.ts
- Hook: use-user-data.ts

### Orden de imports

1. React
2. Librerías de terceros
3. Componentes internos
4. Utilidades
5. Tipos
6. Estilos

Paso 5: requisitos de calidad

## Requisitos de calidad

### Manejo de errores

- Llamadas API con try-catch
- Mensajes de error claros para el usuario
- Registrar errores en log

### Rendimiento

- Listas con atributo key
- Evitar crear objetos/funciones en el render
- React.memo para evitar re-renders innecesarios
- Imágenes con width y height

### Calidad de código

- Archivo ≤300 líneas
- Función ≤50 líneas
- Lógica compleja con comentarios
- Funciones clave con JSDoc

Paso 6: archivo completo

Integra todo y tendrás .cursor/rules/react-typescript.mdc listo.

Ajusta según el proyecto:

• Redux → normas Redux
• React Query → normas de datos
• Reglas de negocio específicas

Probar el efecto

Pide a Cursor un componente de tarjeta de usuario:

Tu prompt: «Crea un componente de tarjeta de usuario con nombre, email y avatar»

Antes de las reglas, Cursor podría generar:

export default function UserCard(props) {
  return <div>...</div>
}

Después de las reglas:

interface UserCardProps {
  name: string;
  email: string;
  avatarUrl: string;
}

export const UserCard = ({ name, email, avatarUrl }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded shadow">
      <img src={avatarUrl} alt={name} className="w-16 h-16 rounded-full" width="64" height="64" />
      <h3 className="text-lg font-bold mt-2">{name}</h3>
      <p className="text-gray-600">{email}</p>
    </div>
  );
};

Cumple todo:

• ✅ Componente funcional
• ✅ Tipos TypeScript
• ✅ Exportación nombrada
• ✅ Estilos Tailwind
• ✅ Imagen con dimensiones

De una vez, sin rehacer.

Técnicas avanzadas y problemas frecuentes

Prioridad: ¿quién manda?

Con varias capas de reglas pueden chocar. Prioridad en Cursor:

Reglas del proyecto > reglas globales

Global dice «comillas simples», proyecto «comillas dobles» → gana el proyecto.

Reglas de subdirectorio > reglas del padre

project/
├── .cursor/rules/general.mdc
└── frontend/
    └── .cursor/rules/react.mdc

En frontend/, react.mdc tiene más peso.

Invocación manual > activación automática

Si mencionas una regla en la conversación, se prioriza aunque sea Manual.

Varios archivos: el arte de dividir

Proyectos complejos necesitan varios archivos:

.cursor/rules/
├── core.mdc              # Stack central (Always)
├── frontend.mdc          # Frontend (Auto Attached: *.tsx, *.ts)
├── backend.mdc           # Backend (Auto Attached: *.py, *.go)
├── testing.mdc           # Pruebas (Auto Attached: *.test.*)
└── performance.mdc       # Rendimiento (Manual)

Cada archivo, un dominio.

Depuración: ¿las reglas no aplican?

Problema 1: no sé si están activas

En Composer o Chat pregunta: «¿Qué reglas ves?»

Cursor lista las reglas cargadas. Si no aparecen las tuyas:

• Ruta incorrecta
• Alcance mal configurado
• Formato del archivo

Problema 2: conflicto entre reglas

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Reglas contradictorias → la IA puede ignorar ambas.

Solución:

1. Localiza el conflicto
2. Define prioridad, elimina la de menor peso
3. O en la regla de mayor prioridad: «sobreescribe otras reglas»

Problema 3: la IA no obedece

Posibles causas:

1. Reglas vagas → instrucciones concretas
2. Reglas largas → lo importante al principio
3. Conflicto con tu prompt → si pides «componente de clase» pero la regla dice funcional, gana el prompt

Soluciones:

• Reescribe con ejemplos
• Di «sigue las reglas del proyecto»
• Cambia de Auto Attached a Always

Reglas listas: sobre hombros de gigantes

¿No quieres empezar de cero? Hay mucho en la comunidad.

awesome-cursorrules

El repo más popular, 2000+ estrellas:

• React, Vue, Angular
• Python, Go, Java
• Next.js, Astro, Nuxt
• TypeScript, pruebas, Docker

Copia, ajusta y listo.

awesome-cursorrules-zh

Optimizado para desarrolladores chinos; incluye reglas combinadas (React + FastAPI full stack).

cursor.directory

Biblioteca online con vista previa y copia; 30+ frameworks.

dotcursorrules.com

Más casos prácticos y buenas prácticas.

Mi consejo: empieza con reglas comunitarias y ajusta con el tiempo. No escribas todo desde cero.

Colaboración: reglas como activo del equipo

En equipo, sube las reglas al control de versiones.

1. Git

git add .cursor/rules
git commit -m "Add Cursor rules for project standards"

Al hacer pull, Cursor carga las mismas reglas para todos.

2. Onboarding

En el README del proyecto:

## Desarrollo con Cursor

Este proyecto tiene Cursor Rules en `.cursor/rules`.

Al usar Cursor, la IA respeta:
- React 18 + TypeScript
- Componentes funcionales + Hooks
- Estilos Tailwind CSS
- Tipado estricto

Para cambiar reglas, consensua con el equipo primero.

3. Review periódico

Cada trimestre:

• ¿Reglas obsoletas?
• ¿Nuevas mejores prácticas?
• ¿Feedback del equipo?

Documentación viva, no configuración única.

Conclusión

En resumen: ponle reglas claras a la IA y trabajará bien.

¿Te suena?

• Pides un componente y el estilo es un caos
• Quieres TypeScript y te mete any
• El código «huele a IA», no a tu equipo

No es culpa de Cursor — no le dijimos «nuestras reglas».

Ahora ya sabes:

1. Crear reglas — .cursor/rules en proyectos nuevos; .cursorrules en legacy
2. Stack claro — versiones, frameworks, herramientas
3. Normas de código — nombres, estilo, errores, con ejemplos
4. Longitud controlada — ≤500 líneas; divide si hace falta
5. Optimización continua — evoluciona con el proyecto

Actúa ya:

• Sin reglas → 5 minutos para el primer archivo
• Con reglas vagas → añade ejemplos
• En equipo → sube a Git

En un mes notarás:

• Menos tiempo en code review
• Estilo unificado
• Onboarding más rápido
• La IA como aliada de verdad

Recursos finales:

• awesome-cursorrules — 2000+ estrellas
• awesome-cursorrules-zh — versión optimizada para desarrolladores chinos
• cursorrules.org — biblioteca online