Sin reglas explícitas, cada desarrollador de tu equipo recibe sugerencias de IA distintas para el mismo problema. Un archivo de reglas bien escrito resuelve eso en minutos.
El formato original era un único archivo .cursorrules en la raíz del repo con texto libre. Desde las versiones más recientes, Cursor migró a un sistema de reglas por carpeta: .cursor/rules/*.mdc, donde cada archivo .mdc define un bloque de instrucciones con metadata (a qué globs de archivos aplica, si se activa siempre o bajo demanda). El archivo .cursorrules plano todavía funciona por retrocompatibilidad, pero si empiezas un proyecto nuevo conviene usar el formato .mdc.
Cada regla tiene un encabezado YAML con description, globs y alwaysApply, seguido del contenido en markdown que se inyecta al contexto del modelo cuando la regla aplica.
Con globs puedes tener reglas específicas por capa: una para el backend Laravel, otra para componentes React, otra para el esquema de base de datos. Cursor solo inyecta la regla cuando el archivo abierto o editado coincide con el patrón, lo que ahorra tokens de contexto.
El error más común es escribir reglas vagas tipo "escribe código limpio y mantenible". Eso no cambia el comportamiento del modelo porque no es accionable. Las reglas que funcionan son específicas y verificables:
- Mal: "Sigue buenas prácticas de seguridad." - Bien: "Todo input de usuario que llegue a una query debe pasar por el query builder o Eloquent; prohibido concatenar SQL crudo."
- Mal: "Usa nombres descriptivos." - Bien: "Los nombres de variables booleanas deben empezar con is, has o can. Ejemplo: isAuthenticated, no authFlag."
Piensa en las reglas como el onboarding que le darías a un desarrollador junior el primer día, pero escrito para que un LLM lo respete en cada sugerencia.
Además de estilo, documenta decisiones de arquitectura que la IA no puede inferir del código solo:
Esto evita que el modelo "reinvente" patrones que ya decidiste, como usar sesiones cuando el proyecto es API-only, o ignorar el filtrado por tenant.
Las reglas viven en .cursor/rules/ dentro del repo, así que se versionan con git como cualquier otro archivo. Recomendaciones:
- Revisa cambios a reglas en pull request igual que revisarías un cambio de linter. - Ten una regla general.mdc con alwaysApply: true para lo no negociable (seguridad, estructura de carpetas) y reglas específicas con glob para el resto. - Cuando detectes que la IA comete el mismo error repetidamente en el equipo (por ejemplo, no usar el logger centralizado), esa es la señal de que falta una regla, no de que hay que corregir a mano cada vez.
Cursor también permite reglas globales por usuario (Settings > Rules for AI) que aplican a todos tus proyectos, útiles para preferencias personales como el idioma de los comentarios. Pero para trabajo de equipo, las reglas deben vivir en el repositorio, no en la configuración personal de cada desarrollador — de lo contrario cada quien recibe sugerencias distintas y pierdes el punto de estandarizar.
Un archivo de reglas no es "configúralo y olvídalo". Cada vez que el equipo adopta un patrón nuevo (una librería, una convención de nombres de commits, un cambio de framework de testing), actualiza la regla correspondiente en el mismo PR que introduce el cambio. Tratarlo como deuda técnica de documentación: si las reglas quedan desactualizadas, la IA empieza a sugerir patrones viejos y el equipo pierde confianza en la herramienta.
Carlos Montiel es arquitecto de soluciones IA empresarial. Implementa LLMs, Agentes, RAG y orquestadores en empresas de Guatemala y Latinoamérica. Contáctalo para una consultoría.
Contactar a Carlos Montiel