Reglas de Cursor IDE para IA: cómo especializar tu asistente de IA

Cursor IDE permite definir reglas en tres niveles:

1. Reglas para IA en la configuración de Cursor IDE: reglas base que se aplican globalmente a todos los proyectos
2. Archivo .cursor/index.mdc con Rule Type "Always": reglas específicas del repositorio que sustituyen al antiguo enfoque con .cursorrules
3. Archivos .cursor/rules/*.mdc: reglas dinámicas que solo se activan cuando la IA trabaja en tareas relacionadas con su descripción

Aquí comparto mis reglas base de Cursor: la configuración global que uso en Cursor IDE. Son el punto de partida de todo mi trabajo de desarrollo. Cuando las combino con reglas a nivel de repositorio y reglas contextuales, consigo un sistema potente que mantiene la calidad del código y hace mucho más consistente mi forma de trabajar.

¿Prefieres un tutorial en video? He grabado un recorrido completo por este sistema de reglas de Cursor. Puedes ver la guía completa en video sobre estas reglas; en YouTube aparece con su título original en inglés.

Cómo configurar las reglas de Cursor para mejorar la programación con IA

Cursor -> Settings -> Cursor Settings -> Rules for AI:

Yo pego este bloque tal cual en Cursor. Lo dejo en inglés porque está pensado para copiarlo y pegarlo directamente en la configuración:

# Global Rules

## Code Style

- Comments in English only
- Prefer functional programming over OOP
- Use OOP classes only for connectors and interfaces to external systems
- Write pure functions - only modify return values, never input parameters or global state
- Follow DRY, KISS, and YAGNI principles
- Use strict typing everywhere - function returns, variables, collections
- Check if logic already exists before writing new code
- Avoid untyped variables and generic types
- Never use default parameter values - make all parameters explicit
- Create proper type definitions for complex data structures
- All imports at the top of the file
- Write simple single-purpose functions — no multi-mode behavior, no flag parameters that switch logic. If the user needs multiple modes, they will ask explicitly

## Error Handling

- Always raise errors explicitly, never silently ignore them
- Use specific error types that clearly indicate what went wrong
- Avoid catch-all exception handlers that hide the root cause
- Error messages should be clear and actionable
- NO FALLBACKS: Code should either succeed or fail with a clear error. Fallbacks are only allowed if the user explicitly asks for them. Never add automatic fallbacks — they hide real problems
- Transparent debugging: When something fails, show exactly what went wrong and why
- Fix root causes, not symptoms - fallbacks hide real problems that need solving
- External API/service calls: use retries with warnings, raise the last error if all attempts fail
- Error messages must include enough context to debug (request params, response body, status codes) — no generic "something went wrong"
- Logging: no dynamic values interpolated into log message strings — pass them as structured data or extra fields. Exceptions can use f-strings for readability

## Language Specifics

- Prefer structured data models over loose dictionaries (Pydantic, interfaces)
- Avoid generic types like `Any`, `unknown`, or `List[Dict[str, Any]]`
- Use modern package management (pyproject.toml, package.json)
- Leverage language-specific type features (discriminated unions, enums)

## Libraries and Dependencies

- Install in virtual environments, not globally
- Add to project configs, not one-off installs
- When a dependency is installed locally (node_modules, .venv, etc.), read its source code directly even if it's gitignored — this is the best way to understand how a library works
- Update project configuration files when adding dependencies

## Testing

- Respect the current repository testing strategy and existing test suite
- Do not add new unit tests by default
- When tests are needed, prefer integration, end-to-end, or smoke tests that validate real behavior
- Use unit tests only rarely, mainly for stable datasets or pure data transformations
- Never add unit tests just to increase coverage numbers
- Avoid mocks when real calls are practical
- It is usually better to spend a little money on real API or service calls than to maintain fragile mock-based coverage
- Add only the minimum test coverage needed for the requested change

## Terminal Usage

- Always use non-interactive git diff: `git --no-pager diff` or `git diff | cat`
- Prefer non-interactive commands with flags over interactive ones

## Code Changes

- Matching the existing code style is more important than "correct" or "ideal" style — new code must look like it was written by the same author
- Suggest only minimal changes related to current dialog
- Change as few lines as possible while solving the problem
- Focus only on what user is asking for - no extra improvements

## Documentation

- Code is the primary documentation — use clear naming, types, and docstrings
- Keep documentation in docstrings of the functions/classes they describe, not in separate files
- Separate docs files (in `docs/`) only when a concept cannot be expressed in code — and only one file per topic
- Never duplicate documentation across files — reference other sources instead
- Store knowledge as current state, not as a changelog of modifications

Cómo sacar más partido a las reglas de Cursor con una estrategia multinivel

Cuando trabajo con las funciones de IA de Cursor IDE, he comprobado que conviene optimizar las reglas en los tres niveles. La idea clave es reducir al mínimo la cantidad de tokens que se envían al modelo en cada conversación. Cuantos menos tokens se gasten en contexto, más margen queda para generar respuestas útiles y de calidad.

Si quieres profundizar en cómo funcionan estas reglas en Cursor, consulta la documentación oficial de Cursor sobre las Rules for AI.

Flujo de implementación en 3 pasos para las reglas de proyecto en Cursor

1. Empiezo solo con la configuración del IDE
   Arranco con la configuración global de Cursor IDE para fijar mis preferencias de base. Así puedo experimentar con distintas formulaciones sin llenar de ruido mis repositorios. Este nivel lo reservo para reglas realmente universales que aplican a todo mi trabajo de programación.

2. Llevo las reglas específicas al nivel de repositorio
   Cuando detecto patrones propios de una base de código concreta o quiero compartir mis pautas para la IA con el equipo, muevo esas reglas a un archivo .cursor/index.mdc con Rule Type "Always". Así creo un marco común sin recargar la configuración global. (Nota: el archivo heredado .cursorrules sigue funcionando, pero ya no es la opción recomendada).

3. Las separo en reglas contextuales cuando hace falta
   Si el archivo de reglas del repositorio empieza a crecer demasiado, lo divido en archivos .cursor/rules/*.mdc. Así reduzco el consumo de tokens, porque solo se activan las reglas relevantes cuando hacen falta. Eso le deja más margen al modelo para centrarse en la tarea concreta, en vez de obligarlo a cargar con un montón de directrices que no vienen al caso.

Mi objetivo es simple: en cada conversación con el asistente de IA, darle justo el contexto necesario para que sea útil, sin gastar capacidad en información que no necesita en ese momento.

Ejemplos reales de reglas de Cursor en repositorios de producción

Para mostrar cómo aplico estas reglas en proyectos distintos, aquí van algunos ejemplos reales.

Archivos .cursor/index.mdc a nivel de repositorio: estructura e implementación

Mis archivos .cursor/index.mdc con Rule Type "Always" funcionan como una especie de README.md pensado específicamente para asistentes de programación con IA. Aportan contexto sobre el propósito del proyecto, su arquitectura y los patrones de código que conviene seguir. (Los archivos .cursorrules, ya heredados, siguen siendo compatibles, pero no se recomiendan para proyectos nuevos).

Ejemplos de repositorios de producción con reglas de Cursor

1. repo-to-text: esta utilidad para convertir repositorios en texto incluye reglas que explican el propósito del proyecto, las decisiones de arquitectura y los patrones de código que conviene seguir.

2. chatgpt-telegram-bot-telegraf: en este bot de Telegram, las reglas se centran en la arquitectura del bot, los patrones de uso de la API y las convenciones para manejar mensajes y comandos.

Archivos .cursor/rules/*.mdc: cuándo usarlos y cómo aprovecharlos

Cuando las reglas de repositorio se vuelven demasiado extensas, las divido en archivos .cursor/rules/*.mdc centrados en contextos concretos que solo se activan cuando son relevantes.

Ejemplo de implementación de reglas específicas para tareas

Un buen ejemplo es el repositorio de mi web personal:
website-next-js/.cursor/rules/

En ese repositorio he creado archivos de reglas separados para:

• Flujos de trabajo de gestión de contenido
• Requisitos de optimización de imágenes
• Buenas prácticas de SEO
• Patrones de arquitectura de componentes
• Procedimientos de despliegue

Este enfoque mantiene a la IA centrada y evita saturarla con información irrelevante cuando estoy trabajando en tareas concretas.

Uso de reglas a mitad de una conversación: limitaciones y buenas prácticas

Hay una limitación importante que conviene tener en cuenta: las reglas .mdc contextuales funcionan mejor cuando se aplican al principio de una conversación nueva. Si ya estás a mitad de un intercambio con Cursor IDE y de pronto necesitas una regla especializada, por ejemplo unas pautas para consultar una base de datos, puede que la IA no cargue automáticamente ese archivo. Esto ocurre porque Cursor ya ha fijado el contexto de la conversación y no siempre vuelve a evaluar qué reglas debe aplicar a mitad del diálogo.

En esos casos, menciono explícitamente la regla que necesito con una instrucción directa, por ejemplo: "Sigue nuestras directrices para consultar la base de datos en esta tarea". Así Cursor busca y aplica la regla correspondiente. Para tareas críticas que dependen de pautas concretas, me resulta más eficaz empezar una conversación nueva, donde Cursor detectará y aplicará automáticamente todas las reglas contextuales relevantes desde el principio.

Cómo evolucionaron mis reglas de Cursor: de la configuración global a los sistemas contextuales

Mi forma de trabajar con las reglas de Cursor ha pasado por varias etapas.

Fase 1: configuración global del IDE para reglas universales

Al principio metía todo en la configuración de Cursor IDE. Era simple y funcionaba bien. A medida que fui detectando más patrones en mi flujo de trabajo, esas reglas globales crecieron. Cada proyecto nuevo se beneficiaba, pero con el tiempo la configuración se volvió difícil de manejar: había demasiadas reglas que no aplicaban en todos los casos.

Fase 2: reglas específicas de repositorio para fijar estándares de proyecto

Cuando la configuración global empezó a llenarse de información irrelevante para cada proyecto, pasé a usar reglas a nivel de repositorio. Al principio eso significaba archivos .cursorrules en la raíz del repositorio, hoy ya considerados heredados. Ese fue mi enfoque principal durante bastante tiempo, porque me permitía adaptar las reglas a cada proyecto sin perder coherencia. Hoy la opción recomendada es usar archivos .cursor/index.mdc con Rule Type "Always".

Fase 3: reglas dinámicas y contextuales para tareas especializadas

Cuando Cursor IDE introdujo las reglas dinámicas .cursor/rules/*.mdc, reorganicé todo. Estas reglas contextuales solo se activan cuando la IA está realizando una tarea relacionada. Eso me permitió:

• Mantener la configuración global mínima y útil para casi cualquier proyecto
• Usar .cursor/index.mdc con Rule Type "Always" para los estándares generales del proyecto, en sustitución de .cursorrules
• Crear archivos .cursor/rules/*.mdc bien enfocados para tareas especializadas

Este enfoque por capas da instrucciones a la IA justo cuando las necesita, reduce el ruido y hace que su ayuda sea más relevante.

La evolución refleja algo que fui entendiendo con el tiempo: colaborar bien con asistentes de programación con IA implica empezar con una capa amplia e ir afinando hasta llegar a reglas contextuales y específicas de cada tarea.

Comparación completa de los niveles de reglas de Cursor: globales, de repositorio y contextuales

Aquí tienes una comparación rápida de los tres niveles de reglas en Cursor IDE:

Característica	Configuración global del IDE	Reglas de repositorio (.cursor/index.mdc con Always)	Reglas contextuales (.cursor/rules/*.mdc)
Alcance	Todos los proyectos	Un repositorio concreto	Tareas o contextos concretos
Visibilidad	Solo tú (configuración local)	Todo el equipo a través del repositorio	Todo el equipo a través del repositorio
Persistencia	Se mantiene entre proyectos	Va ligada al repositorio	Va ligada al repositorio
Activación	Siempre activa	Siempre activa en ese repositorio	Solo cuando es relevante para la tarea actual
Mejor para	Reglas universales	Patrones de arquitectura del proyecto	Conocimiento especializado de dominio
Eficiencia de tokens	Baja (siempre presente)	Media (siempre presente dentro del proyecto)	Alta (solo se carga cuando hace falta)
Ubicación de la configuración	Interfaz de ajustes de Cursor	Archivo .cursor/index.mdc	Directorio .cursor/rules/
Portabilidad	Requiere configurarlo manualmente en cada dispositivo	Se transfiere al clonar el repositorio	Se transfiere al clonar el repositorio
Compatibilidad heredada	No aplica	.cursorrules sigue funcionando (heredado)	No aplica

Este enfoque multinivel te permite optimizar el uso de tokens sin renunciar a una guía coherente en escenarios distintos.

Guía paso a paso: cómo aplicar reglas de Cursor en tu flujo de desarrollo

Ahora que ya he explicado la idea general, veamos cómo puedes montar un sistema parecido para tu propio trabajo.

Configurar reglas globales de Cursor para programar con IA

Para configurar tus reglas globales en Cursor IDE:

1. Abre Cursor IDE y ve a Settings (el botón de la esquina superior derecha)
2. Entra en Cursor Settings > Rules for AI
3. Añade tus directrices principales con una estructura como la que viste arriba
4. Mantén las reglas globales centradas en estándares universales de programación que apliquen a todos tus proyectos
5. Prueba con indicaciones sencillas para ver cómo responde la IA a tus instrucciones

Cómo gestionar con eficiencia la configuración local de Cursor IDE

La clave está en encontrar el equilibrio: si pones muy pocas reglas, la IA no entenderá bien tus preferencias; si añades demasiadas, gastarás tokens en contexto irrelevante.

También conviene recordar que esta configuración se guarda localmente en tu instalación de Cursor IDE. Tus compañeros no la verán salvo que la reproduzcan en sus propias máquinas. Y si usas Cursor IDE en varios equipos, por ejemplo uno personal y otro de trabajo, tendrás que configurarlo manualmente en cada instalación.

Crear archivos .cursor/index.mdc a nivel de repositorio para equipos de proyecto

Para la configuración a nivel de proyecto:

1. Crea un archivo .cursor/index.mdc en tu repositorio
2. Define el Rule Type como "Always" en la interfaz de Cursor o indícalo manualmente en el archivo
3. Empieza con una breve descripción del proyecto: qué hace, qué tecnologías usa y cuál es el contexto general
4. Documenta los patrones de arquitectura que la IA debe comprender
5. Incluye las convenciones de código específicas de ese proyecto
6. Mantén el archivo por debajo de las 100 líneas para optimizar el uso de tokens

Nota: los archivos .cursorrules heredados siguen funcionando, pero ya no son la opción recomendada.

Plantilla mínima de reglas de repositorio para proyectos en Cursor IDE

Aquí tienes una plantilla sencilla para empezar:

# Proyecto: [Nombre del proyecto]

## Visión general
- Propósito: [Breve descripción]
- Stack: [Tecnologías principales]
- Arquitectura: [Patrón principal: MVC, microservicios, etc.]

## Patrones de código
- [Lista de patrones específicos del proyecto]

## Requisitos de estilo
- [Directrices de estilo específicas del proyecto]

Crear archivos .mdc contextuales para tareas especializadas

Para una configuración más avanzada:

1. Crea un directorio .cursor/rules/ en tu repositorio
2. Añade archivos .mdc para distintos contextos
3. Ponles nombres descriptivos según su propósito
4. Haz que cada archivo se centre en una sola preocupación
5. Incluye una breve descripción al inicio para ayudar a la IA a entender cuándo debe aplicar esas reglas

Crear reglas: método manual frente a interfaz de Cursor IDE

Puedes crear estos archivos a mano o usar la interfaz de Cursor IDE:

1. Ve a Settings > Rules
2. Haz clic en Add Rule
3. Introduce un nombre y una descripción para la regla
4. Añade el contenido personalizado
5. Guarda la regla y Cursor creará el archivo .mdc correspondiente dentro del repositorio

Ambos enfoques funcionan bien. Crear el archivo a mano te da más control sobre su estructura, mientras que la interfaz de Cursor ofrece una experiencia más guiada.

Ejemplo de archivo de reglas de Cursor para desarrollo con React

Este ejemplo sí lo traduzco al español porque es una plantilla orientativa, no un bloque pensado para copiarse literalmente:

# Directrices para componentes de React

Estas reglas se aplican al trabajar con componentes de React en este proyecto.

## Estructura de componentes
- Componentes funcionales con interfaces de TypeScript para las props
- Hooks personalizados para la gestión de estado compleja
- `styled-components` para los estilos

## Convenciones de nombres
- Archivos de componentes: PascalCase.tsx
- Archivos de hooks: use[Nombre].ts
- Archivos de estilos: [nombre].styles.ts

Beneficios medibles de usar reglas de Cursor para programar con ayuda de IA

Después de implantar este sistema multinivel, he visto mejoras claras en varias dimensiones.

Mejora de la calidad del código gracias a reglas consistentes

El beneficio más inmediato ha sido la consistencia en la calidad del código. Al plasmar mis preferencias en reglas de Cursor, la IA genera código que:

• Sigue de forma consistente los principios de la programación funcional
• Aplica un manejo de errores adecuado sin que tenga que pedirlo cada vez
• Añade tipado correcto sin recordatorios constantes
• Mantiene convenciones de nombres uniformes en toda la base de código

Esto se traduce en menos comentarios de revisión y menos tiempo dedicado a corregir problemas de estilo. En un proyecto vimos una reducción del 50% en los comentarios de PR relacionados con cuestiones de estilo después de implantar estas reglas.

Mejor colaboración de equipo con reglas de Cursor compartidas

Cuando trabajo con equipos, estas reglas ayudan a crear un marco común:

• Las personas que se incorporan entienden antes las expectativas gracias al archivo de reglas del repositorio
• La colaboración entre perfiles técnicos y no técnicos mejora porque todos pueden remitirse a las mismas reglas
• El conocimiento se transmite de forma automática a medida que la IA aplica las buenas prácticas con consistencia

Lo he notado especialmente al incorporar desarrolladores junior: reciben feedback inmediato sobre buenas prácticas sin tener que esperar a una revisión de código.

Ganancias de productividad gracias a una interacción mejor afinada con la IA de Cursor IDE

Los números hablan por sí solos:

• Alrededor de un 60% menos de tiempo explicando estándares de código a nuevas incorporaciones
• Aproximadamente un 35% menos de tiempo hasta enviar la primera PR, con menos rondas de revisión
• Cerca de un 40% menos de commits de "corrección de estilo" que ensucian el historial de Git

Pero la métrica más valiosa ha sido la carga mental. Cuando delegas en la IA las decisiones de estilo, los desarrolladores pueden centrarse en resolver el problema real en lugar de estar pendientes de reglas de formato.

Técnicas avanzadas de reglas de Cursor para desarrolladores profesionales

Cuando ya te sientas cómodo con las estructuras básicas, estas técnicas avanzadas te ayudarán a afinar todavía más la experiencia.

Reglas de Cursor para tareas especializadas en escenarios habituales de desarrollo

He comprobado que los archivos de reglas especializados funcionan especialmente bien en estos casos:

Reglas de pruebas (test-guidelines.mdc)

• Respeta la estrategia de pruebas ya existente en el repositorio
• Prioriza pruebas de integración, end-to-end y smoke tests antes que añadir nuevos unit tests
• Usa unit tests solo en casos puntuales, sobre todo para conjuntos de datos estables o transformaciones puras
• No añadas unit tests solo para inflar la cobertura
• Evita los mocks cuando las llamadas reales sean viables
• Suele ser mejor gastar un poco de dinero en llamadas reales que mantener pruebas frágiles basadas en mocks
• Define únicamente la cobertura mínima necesaria para la tarea actual

Reglas de integración de API (api-standards.mdc)

• Expectativas sobre manejo de errores
• Patrones de lógica de reintentos
• Estándares para los flujos de autenticación

Reglas de gestión de estado (state-patterns.mdc)

• Convenciones de nombres para acciones de Redux
• Directrices para normalizar el estado
• Patrones para manejar efectos secundarios

Al separar estas preocupaciones, cada archivo se mantiene enfocado y solo se activa cuando de verdad importa para la tarea en curso.

Cómo optimizar el uso de tokens en las reglas de Cursor

Para aprovechar al máximo la ventana de contexto efectiva de la IA:

1. Prioriza la posición: coloca las reglas más importantes al principio o al final del archivo
2. Usa una estructura jerárquica: empieza por los principios generales y después baja al detalle
3. Elimina redundancias: no repitas la misma regla en varios sitios
4. Escribe con concisión: mejor listas de puntos que párrafos largos
5. Aprovecha el formato Markdown: usa encabezados para separar claramente las categorías de reglas

Como regla general, si un archivo supera las 100 líneas, probablemente está intentando abarcar demasiado y conviene dividirlo en piezas más enfocadas.

Problemas habituales con las reglas de Cursor y cómo resolverlos

Si tus reglas no están dando el resultado esperado:

1. Conflictos entre reglas: comprueba si hay pautas contradictorias en distintos niveles
2. Reglas demasiado genéricas: hazlas más específicas y añade ejemplos concretos
3. Reglas demasiado estrechas: si son excesivamente rígidas, no se adaptarán a escenarios parecidos
4. Límites de tokens: si las reglas se están truncando, simplifica y prioriza
5. Falta de contexto: la IA puede necesitar contexto adicional de archivos para aplicar bien las reglas
6. Sobrecarga de reglas: cuando aparecen demasiadas reglas en la misma conversación, al modelo le cuesta recordarlas y seguirlas todas a la vez; prioriza las más importantes

He comprobado que revisar el código generado frente a mis reglas e ir refinándolas de forma iterativa mejora continuamente la calidad de la ayuda que da la IA.

Cursor IDE frente a otros asistentes de programación con IA: comparación de enfoques de configuración

Aunque Cursor tiene un sistema de reglas especialmente bien diseñado, otros asistentes de programación con IA siguen enfoques parecidos para personalizarse:

• GitHub Copilot ofrece .github/copilot/settings.yml para configuración a nivel de proyecto
• JetBrains AI Assistant incorpora fragmentos y plantillas a nivel de proyecto
• VS Code, con distintas extensiones de IA, permite usar ajustes de espacio de trabajo y archivos de personalización

Nota: la evolución de Cursor, desde .cursorrules hasta .cursor/index.mdc con Rule Type "Always", muestra cómo este tipo de sistemas sigue mejorando en flexibilidad y organización.

Uso eficiente de tokens: cómo sacar más partido a la IA en cualquier herramienta

Lo que une a todos estos enfoques es un principio básico: minimizar el uso de tokens es esencial para obtener buenos resultados. Da igual qué asistente de programación con IA uses: la clave está en aportar el contexto justo, sin saturar al modelo.

La gestión de tokens funciona igual en todas las herramientas basadas en LLM:

1. Cada palabra que añades a las instrucciones consume tokens
2. Los tokens dedicados a las instrucciones reducen el contexto disponible para entender el código
3. Una guía excesivamente verbosa acaba aportando cada vez menos valor

Así que, tanto si usas el sistema de tres niveles de Cursor como las opciones de configuración de otra herramienta, conviene aspirar siempre a ser preciso y conciso. Centra tus instrucciones en los patrones y preferencias que realmente importan, y deja que la IA resuelva el resto.

La ventaja real no está en qué herramienta ofrece más opciones de personalización, sino en cómo usas las que tienes para transmitir expectativas con claridad, sin desperdiciar tokens en verbosidad innecesaria.

Tutorial en video: mira la implementación completa de las reglas de Cursor IDE

Si aprendes mejor de forma visual, he preparado un tutorial en video que muestra la implementación completa de este sistema de reglas de Cursor en tres niveles. El video está publicado en YouTube con un título en inglés, pero el contenido sigue exactamente este enfoque:

En el video verás:

• Cómo configurar reglas globales en los ajustes de Cursor IDE
• Cómo crear archivos de reglas específicos del repositorio con el nuevo enfoque .cursor/index.mdc con Rule Type "Always" y con el enfoque heredado .cursorrules
• Cómo implementar archivos .cursor/rules/*.mdc contextuales para tareas especializadas
• Cómo se combinan los distintos niveles para optimizar la asistencia de la IA
• Problemas habituales y formas de optimizar el uso de tokens

Verás el flujo completo en acción, desde la configuración inicial hasta las configuraciones multinivel más avanzadas, que cambian por completo la forma de colaborar con asistentes de programación con IA.

Si quieres leer los artículos equivalentes sobre otros agentes de programación, aquí los tienes:

• Reglas de Claude Code para IA: https://kirill-markin.com/es/articulos/reglas-claude-code-para-ia/
• Reglas de Codex para IA: https://kirill-markin.com/es/articulos/reglas-codex-para-ia/