¿Cansado de que la IA no entienda tu proyecto? Te enseño a configurar las 'Rules' en Cursor IDE para refactorizar código de verdad. ¡Entra y domina la IA!

Compañeros, déjenme empezar con una confesión un poco ácida: la palabra "productividad" me tiene hasta la coronilla. Vienen a nosotros, los que llevamos tiempo en esto, buscando el truco mágico, el atajo que les va a ahorrar cinco minutos. Quieren una lista de tareas, no un manifiesto, porque la teoría exige pensar, y pensar es un trabajo que muchos prefieren delegar en la máquina.

Y esta obsesión por la eficiencia barata los lleva a la idea más peligrosa de todas: que la IA es una simple fábrica de código nuevo. Le pides que te escriba una función, la escupe en tres segundos y aplaudes. ¡Qué maravilla! Han convertido una herramienta revolucionaria en un generador de snippets glorificado. Es como pedir un coche de carreras y usarlo solo para ir a comprar el pan.

Quiero que dejemos esa idea atrás. El verdadero poder de una herramienta como Cursor, el editor de código del que les voy a hablar, no es generar, es comprender. No es escribir, es reescribir. Es darle a la IA la llave de tu laberinto de código heredado y ordenarle: "Explícame este caos". Por eso hoy no vamos a hablar de trucos, vamos a hablar de cómo enseñarle a la IA el idioma de nuestro proyecto. Y para eso, necesitamos hablar de las "Rules" (Reglas).

¿Qué carrizo son las "Rules" y por qué deberían importarte?

Vamos a quitarnos un mito de encima de una vez: Cursor no es un editor completamente nuevo que te obliga a aprender todo desde cero. Es un fork de Visual Studio Code, lo que significa que todos tus temas, atajos y extensiones favoritas funcionan sin problemas. La migración es prácticamente inexistente.

Para que vean a qué me refiero, la siguiente imagen demuestra lo familiar que se siente la interfaz desde el primer momento.

¿Cansado de que la IA no entienda tu proyecto? Te enseño a configurar las 'Rules' en Cursor IDE para refactorizar código de verdad. ¡Entra y domina la IA!

Aclarado esto, hablemos de las Reglas. La idea me recuerda mucho a mis días en el proyecto Canaima GNU/Linux. Allí, la pasión por el código abierto me llevó de ser un agente de soporte a convertirme en el desarrollador principal en cuestión de meses. Trabajábamos en un sistema operativo completo, una tarea enorme y compleja. La única forma de avanzar era estableciendo un conjunto de normas claras, un "manual de estilo" que todos entendían. Cuando un nuevo desarrollador se unía al equipo, eso era lo primero que recibía: una guía que decía "así es como hacemos las cosas aquí".

Eso, exactamente eso, son las "Rules" de Cursor. Son un conjunto de instrucciones personalizadas y persistentes que guían el comportamiento de la IA dentro de tu proyecto. En lugar de recordarle en cada chat que use pnpm en vez de npm, creas una regla que se lo enseña para siempre. Así, la IA deja de ser un asistente genérico y se convierte en un miembro más del equipo que, como aquel nuevo desarrollador en Canaima, conoce las normas de la casa desde el primer día.

Estas reglas se configuran en archivos de texto dentro de una carpeta .cursor/rules en la raíz de tu proyecto, lo que te permite versionarlas con Git y compartirlas con todo el equipo. Visualizar esta estructura ayuda a entender lo simple que es empezar.

¿Cansado de que la IA no entienda tu proyecto? Te enseño a configurar las 'Rules' en Cursor IDE para refactorizar código de verdad. ¡Entra y domina la IA!

La anatomía de una Regla: Entendiendo el archivo .mdc

Cada regla se escribe en un archivo con extensión .mdc (Markdown with Components). Es básicamente un archivo de Markdown con una pequeña sección de metadatos al principio. La estructura es sencilla y poderosa.

Un archivo de regla tiene dos partes:

  1. El Frontmatter: Un bloque al inicio del archivo, encerrado entre ---, que contiene la configuración de la regla.

    • description: Una línea que describe de forma clara qué hace la regla. Esto es crucial para que la IA decida cuándo usarla.
    • globs: Patrones de archivo (como los de .gitignore) que le indican a Cursor cuándo debe aplicar esta regla automáticamente. Por ejemplo, src/components/**/*.tsx haría que la regla se active siempre que estés trabajando en un componente de React.
    • alwaysApply: Un booleano (true o false) para forzar que la regla se aplique siempre, en cada chat o edición.
  2. El Contenido: El cuerpo del archivo es puro Markdown. Aquí es donde escribes las instrucciones en lenguaje natural, tal como se las darías a un colega. Puedes usar listas, texto en negrilla y, lo más importante, bloques de código para dar ejemplos.

Para que esto no se quede en teoría, la siguiente ilustración desglosa visualmente cómo se ve un archivo .mdc en la práctica.

¿Cansado de que la IA no entienda tu proyecto? Te enseño a configurar las 'Rules' en Cursor IDE para refactorizar código de verdad. ¡Entra y domina la IA!

Existen cuatro tipos de reglas que determinan cómo y cuándo se aplican, controlados por los metadatos:

Tipo de ReglaDescripción
AlwaysSiempre se incluye en el contexto del modelo de IA. Ideal para guías de estilo globales.
Auto AttachedSe incluye cuando se hace referencia a archivos que coinciden con un patrón glob.
Agent RequestedLa IA decide si incluirla basándose en su description. Requiere una descripción clara.
ManualSolo se incluye cuando se menciona explícitamente en el chat usando @nombreDeLaRegla.

Fíjense en este ejemplo básico para un proyecto de React con Tailwind:

---
description: Guía de estilo para componentes de UI en React con Tailwind.
globs: src/components/**/*.tsx
alwaysApply: false
---

**Principios para Componentes de UI**

- Usa siempre clases de Tailwind para el estilo. No uses CSS en línea ni `<style>`.
- Prefiere nuestros componentes reutilizables en lugar de elementos HTML nativos.

✅ **Ejemplo correcto:**
Usa nuestro componente `Button` importado.

import { Button } from '@/components/ui/Button';

function MyComponent() {
return <Button>Hacer clic</Button>;
}

❌ **Ejemplo incorrecto:**
No uses un botón HTML nativo directamente.

function MyComponent() {
return <button className="bg-blue-500 p-2">Hacer clic</button>;
}

- Para más detalles, puedes consultar la [documentación oficial sobre reglas](https://docs.cursor.com/context/rules).

Lo más poderoso aquí es que puedes hacer referencia a otros archivos de tu propio proyecto usando la sintaxis @ruta/al/archivo.tsx. Esto le da a la IA el contexto completo del código que debe usar como referencia.

Manos a la obra: Creando tu primera regla

Vamos a crear una regla práctica. Supongamos que queremos asegurarnos de que la IA siempre use una función de logging personalizada en lugar de console.log.

  1. Crea el directorio: En la raíz de tu proyecto, crea la carpeta .cursor y, dentro de ella, otra carpeta llamada rules. Tu estructura se verá así: mi-proyecto/.cursor/rules/.

  2. Crea el archivo de la regla: Dentro de la carpeta rules, crea un archivo llamado logging-standard.mdc.

  3. Define la regla: Abre el archivo y añade el siguiente contenido. Asumamos que nuestra función de logging está en src/utils/logger.ts.

    ---
    description: Instrucciones para usar siempre nuestro logger personalizado en lugar de console.log.
    globs: src/**/*.ts, src/**/*.tsx
    alwaysApply: true
    ---
    
    Al escribir o modificar código, nunca uses `console.log`, `console.warn`, o `console.error`.
    
    En su lugar, importa y utiliza nuestro logger personalizado que se encuentra en `@src/utils/logger.ts`.
    
    Aquí tienes un ejemplo del archivo de logger para que lo uses como referencia:
    
    `@src/utils/logger.ts`
    
    ✅ **Uso correcto:**
    
    ```typescript
    import { logger } from "@/utils/logger";
    
    function fetchData() {
      logger.info("Fetching data...");
      // ...
    }
    ```
    

    Uso incorrecto:

    function fetchData() {
      console.log("Fetching data...");
      // ...
    }
    

¡Y listo! Con alwaysApply: true, a partir de ahora, cada vez que le pidas a Cursor que genere o modifique código, tendrá esta instrucción presente. Ya no tendrás que recordárselo. Acabas de enseñarle una de las reglas fundamentales de tu proyecto.

Más allá de generar código: El verdadero poder

Aquí es donde volvemos al principio. La gente se obsesiona con pedirle al chat "créame un componente de React con un formulario". Eso es útil, sí, pero es la superficie.

El verdadero poder es seleccionar 1000 líneas de código espagueti que heredaste de otro equipo y decirle a la IA: "Refactoriza esto siguiendo las directrices de @.cursor/rules/logging-standard.mdc y @.cursor/rules/react-components.mdc". En ese momento, la IA no está solo generando código, está entendiendo y aplicando el conocimiento específico de tu proyecto.

Esto también responde a una pregunta común: ¿cómo hago para que la IA siga mis reglas de linting? Cursor intenta detectar archivos como .eslintrc automáticamente. Pero con las reglas, puedes ser explícito. Puedes crear una regla que le diga: "Nuestros componentes deben seguir estrictamente las reglas definidas en @.eslintrc.js". Al usar el símbolo @, conviertes ese archivo en una fuente de verdad prioritaria.

Dejemos de buscar el atajo de cinco minutos. La productividad que nos venden es un espejismo. El verdadero poder no es hacer el trabajo más rápido, es atreverse a hacer un trabajo que antes era, sencillamente, imposible. Las Reglas de Cursor son un paso fundamental en esa dirección.

Este es solo el comienzo. En próximos posts les mostraré ejemplos concretos de reglas que uso en mis proyectos con Python y Canaima. Pero ahora quiero saber de ustedes: ¿Qué reglas se les ocurren para sus propios proyectos? ¿Qué es lo primero que le enseñarían a la IA sobre su código? ¡Dejen sus ideas en los comentarios, gente