Cursor Rules: Cómo escribir archivos .cursor/rules que realmente funcionen

Todo usuario de Cursor choca eventualmente con la misma pared. La IA genera código que técnicamente funciona, pero ignora las convenciones de su proyecto — rutas de importación incorrectas, patrones obsoletos, componentes que no se parecen en nada al resto de su base de código. Las Cursor Rules solucionan eso dándole a la IA contexto persistente sobre cómo funciona su proyecto.

¿Qué son las Cursor Rules y por qué importan?

Las Cursor Rules son archivos Markdown que actúan como un prompt de sistema permanente inyectado antes de cada interacción con la IA — chat, autocompletado, generación de código, todo. Piense en ellas como la documentación de incorporación para la IA. En lugar de corregir los mismos errores en cada sesión, escribe la instrucción una vez y se mantiene.

El enfoque antiguo era un único archivo .cursorrules en la raíz de su proyecto. Eso todavía funciona, pero está obsoleto. El sistema actual utiliza un directorio .cursor/rules/ con archivos .mdc individuales (Markdown Cursor), cada uno orientado a situaciones específicas. Esta es una configuración mucho mejor porque no tiene que meter todas las instrucciones en un archivo gigante — divide las reglas por responsabilidad, y Cursor solo carga las relevantes para lo que está haciendo ahora mismo.

Si ha trabajado con context engineering para herramientas de IA, el concepto es familiar: un mejor contexto de entrada produce resultados dramáticamente mejores. Las reglas son context engineering para todo su flujo de trabajo de desarrollo.

Configurar su primer archivo de reglas

Cree el directorio .cursor/rules/ en la raíz de su proyecto:

mkdir -p .cursor/rules

Cada regla es un archivo .mdc con frontmatter YAML seguido de contenido Markdown. Aquí está el esqueleto:

---
description: "Cuándo debe aplicarse esta regla"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Sus instrucciones van aquí en Markdown simple.

Tres campos de frontmatter controlan todo:

También puede crear reglas a través del propio Cursor — escriba /create-rule en el chat y describa lo que quiere. Pero escribirlas a mano le da más control.

Los cuatro tipos de reglas explicados

Cómo se activa una regla depende de su configuración de frontmatter. Hay cuatro modos, y elegir el correcto importa para su presupuesto de ventana de contexto.

Siempre aplicar

---
alwaysApply: true
---

Se carga en cada solicitud de IA sin excepción. Úselo con moderación — para los fundamentos de todo el proyecto, como la declaración de su stack tecnológico o las convenciones críticas que se aplican en todas partes. Cada regla siempre activa consume tokens en cada interacción, sea relevante o no.

Adjuntada automáticamente (basada en glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Se activa solo cuando edita archivos que coinciden con los patrones glob. Este es el tipo de regla más útil en el día a día. Sus convenciones de componentes React se cargan cuando trabaja en archivos de componentes, sus patrones de API cuando trabaja en manejadores de rutas, sus reglas de prueba cuando escribe pruebas.

Solicitada por el agente (inteligente)

---
description: "Patrones de migración de base de datos usando Drizzle ORM"
alwaysApply: false
---

Sin globs, sin always-apply — solo una descripción. El agente de Cursor lee la descripción y decide si la regla es relevante para la tarea actual. Si le pide que escriba una migración, carga esta regla. Si está dando estilo a un botón, la salta. Esto funciona sorprendentemente bien para reglas que no se mapean claramente a rutas de archivos.

Manual

---
---

Sin campos de frontmatter definidos (o frontmatter vacío). Estas reglas solo se activan cuando las menciona explícitamente con @nombre-de-regla en el chat. Útil para instrucciones raramente utilizadas pero importantes — como listas de verificación de despliegue o guías de refactorización que solo necesita ocasionalmente.

Patrones glob que realmente funcionan

Los globs determinan qué archivos activan las reglas adjuntadas automáticamente. Si están mal configurados, sus reglas nunca se activan o se activan en todas partes. Esto es lo que funciona:

# Todos los archivos TypeScript en src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Solo archivos de componentes
globs: ["**/components/**/*.tsx"]

# Archivos Python, excluyendo tests
globs: ["**/*.py", "!**/test_*.py"]

# Múltiples directorios específicos
globs: ["src/api/**", "src/services/**"]

Algunos problemas del uso real:

• src/* solo coincide con un nivel de directorio. Casi siempre querrá src/**/* para la coincidencia recursiva.
• *.js no coincide con archivos .jsx o .ts. Sea explícito sobre las extensiones.
• Los globs deben ser una lista YAML. La sintaxis de llaves como {src,lib}/**/*.ts puede fallar silenciosamente — use entradas de lista separadas.
• El prefijo ! excluye patrones, lo que es útil para ignorar archivos generados o código heredado.

Ejemplos prácticos de reglas

Aquí es donde la teoría se encuentra con la realidad. Estas son reglas que puede agregar a un proyecto y ver inmediatamente mejores resultados de IA.

Regla base para todo el proyecto (Siempre aplicar)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Mantenga esto bajo 30 líneas. Se carga con cada solicitud, así que cada palabra cuesta tokens.

Regla de componentes React (Adjuntada automáticamente)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Regla API Python (Adjuntada automáticamente)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Regla de servicio Go (Adjuntada automáticamente)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Gestionar el impuesto en tokens

Esto es algo que la mayoría de las guías de Cursor omiten: cada regla que escribe cuesta tokens. Un proyecto con 20 reglas siempre activas puede consumir **más de 2.000 tokens por solicitud** solo en instrucciones — antes de que la IA siquiera mire su código.

Eso importa porque el contexto de chat de Cursor es de aproximadamente 20.000 tokens en modo estándar. Si sus reglas consumen el 25% de eso, ha perdido un cuarto del "espacio de pensamiento" de la IA para su pregunta real. Notará una peor calidad de salida a medida que se acumulan las reglas, especialmente en conversaciones más largas.

Tres principios mantienen su presupuesto de tokens saludable:

**1. Use reglas adjuntadas automáticamente y solicitadas por el agente de forma agresiva.** Solo la declaración de su stack de proyecto debería estar siempre activa. Todo lo demás debe cargarse condicionalmente. ¿Esa regla de componentes React? No necesita estar en contexto cuando escribe migraciones SQL.

**2. Escriba denso, no verboso.** Reemplace "Se recomienda encarecidamente que los desarrolladores utilicen interfaces TypeScript en lugar de alias de tipo al definir contratos de API públicos" con "Prefer `interface` over `type` for public APIs." La IA no necesita ser convencida — necesita instrucciones.

**3. Aplique la Regla de las Tres.** Solo codifique un patrón como regla después de que la IA lo haya hecho mal tres veces. Si Cursor ya maneja sus convenciones de nomenclatura correctamente sin una regla, omita la regla. Cada regla innecesaria es contexto desperdiciado.

Puede monitorear el uso de tokens en la barra de estado en la parte inferior del panel de chat de Cursor. Preste atención cuando se acerque al 100% — esa es su señal para podar.

## Organizar reglas para un proyecto real

Un proyecto en producción normalmente necesita 5-8 archivos de reglas. Aquí hay una estructura que funciona bien:

```text
.cursor/rules/
  base.mdc            # Stack tecnológico, always-apply (< 30 líneas)
  components.mdc      # Patrones React/Vue, glob a directorios de componentes
  api.mdc             # Convenciones backend, glob a directorios API
  database.mdc        # Patrones ORM, glob a models/migrations
  testing.mdc         # Convenciones de prueba, glob a archivos de prueba
  deployment.mdc      # Patrones CI/CD, activador manual
  personal.mdc        # Sus preferencias (gitignored)

Confirme todo en el control de versiones excepto personal.mdc. Así todo su equipo obtiene el mismo comportamiento de IA — que es el objetivo. Como dice un usuario del foro de Cursor, buenas reglas significan que "acepta más sugerencias tal como están, con resultados que coinciden con sus convenciones en el primer intento."

Si trabaja con otras herramientas de codificación con IA junto a Cursor, los conceptos se transfieren directamente. Claude Code usa CLAUDE.md, GitHub Copilot tiene archivos de instrucciones, y Windsurf tiene su propio formato — pero el principio subyacente es idéntico.

Cómo funciona la precedencia de reglas

Cuando múltiples reglas se aplican al mismo archivo, Cursor sigue una jerarquía clara:

Las Team Rules están disponibles en los planes Team y Enterprise. Las establecen los administradores en el panel de Cursor y se aplican en toda la organización — los desarrolladores individuales no pueden desactivarlas.

Dentro de las reglas de proyecto, si dos reglas se aplican al mismo archivo y entran en conflicto, el comportamiento no está estrictamente definido. En la práctica, las reglas cargadas más tarde tienden a tener precedencia. Numerar sus archivos (001-base.mdc, 002-components.mdc) le da un orden predecible.

Errores comunes y cómo solucionarlos

Después de leer decenas de hilos comunitarios y probar reglas en varios proyectos, estos son los errores que más tropiezan a la gente:

Escribir reglas demasiado vagas. "Escriba código limpio" no le dice nada a la IA. "Use exports nombrados, no exports por defecto. Estructure los componentes como: imports, tipos, función, subcomponentes" le da algo concreto.

Poner todo en always-apply. El primer instinto es poner alwaysApply: true en cada regla. Resista eso. Audite sus reglas trimestralmente — si tiene más de 2-3 reglas siempre activas, probablemente está desperdiciando tokens.

Olvidar probar las reglas. Después de escribir una regla, abra un archivo relevante y pida a Cursor que genere algo que debería seguir la regla. Si no lo hace, su patrón glob puede ser incorrecto, o la instrucción no es lo suficientemente clara.

No documentar los anti-patrones. Decirle a la IA qué hacer es la mitad del trabajo. Decirle qué no hacer es la otra mitad. Incluya en cada regla una sección "NUNCA hacer esto" con ejemplos explícitos del enfoque incorrecto.

Ignorar el guardado de reglas en la UI. Un error conocido hace que los cambios en las reglas desaparezcan. Si los cambios desaparecen, cierre Cursor completamente, seleccione "Anular" en el popup de cambios no guardados y vuelva a abrirlo.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor no es la única herramienta que usa archivos de instrucciones. Así se comparan los formatos para quienes trabajan con múltiples asistentes de codificación con IA:

La ventaja de Cursor es la granularidad. CLAUDE.md y AGENTS.md son más simples — cargan todo siempre. Cursor le permite cargar las reglas correctas en el momento correcto, lo que importa una vez que su conjunto de instrucciones supera unas pocas cientos de líneas.

Para un análisis más profundo de cómo el contexto determina la salida de IA en estas herramientas, nuestra guía de context engineering explica los principios que se aplican independientemente del editor que use.

Si tienes funciones de IA en tu hoja de ruta, esa es nuestra especialidad: el equipo de integración de IA de Techsy lleva los sistemas LLM del prototipo a producción. ¿Quieres una segunda opinión sobre tu stack? Solicita una consultoría gratuita.

Preguntas frecuentes

¿Está .cursorrules obsoleto?

Sí. El archivo .cursorrules único en la raíz de su proyecto todavía funciona, pero Cursor recomienda migrar a archivos .cursor/rules/*.mdc. El nuevo formato admite patrones glob, carga condicional y mejor organización. Migre dividiendo su archivo monolítico en reglas enfocadas.

¿Qué extensión de archivo debo usar — .mdc o .md?

Use .mdc para archivos que incluyen frontmatter YAML (description, globs, alwaysApply). Los archivos .md simples también funcionan en el directorio de reglas, pero no admiten los metadatos de frontmatter que permiten la carga condicional.

¿Cuántas reglas debería tener un proyecto?

Cinco a ocho es el punto óptimo para la mayoría de los proyectos. Una regla base siempre activa, tres a cuatro reglas adjuntadas automáticamente por tipo de archivo y una o dos reglas manuales para tareas especiales. Más de 10 reglas generalmente significa que algunas se pueden consolidar o eliminar.

¿Las Cursor Rules afectan el autocompletado y el completado por tabulación?

Las reglas se aplican a las interacciones de chat y agente. Las User Rules no se aplican a las ediciones inline (Cmd/Ctrl+K), y las reglas generalmente no afectan las sugerencias de autocompletado de Cursor Tab. Son más efectivas en sesiones de chat y Composer.

¿Puedo compartir reglas entre múltiples proyectos?

Sí, a través de la función Remote Rules de Cursor. Vaya a Cursor Settings > Rules, Commands, seleccione "Remote Rule (GitHub)" y pegue una URL de repositorio. Las reglas se sincronizan automáticamente cuando se actualiza el repositorio fuente. Alternativamente, mantenga un repositorio de reglas compartido y enlace simbólicamente en cada proyecto.

¿Cuál es la longitud máxima recomendada para una regla?

La documentación de Cursor sugiere mantener las reglas individuales bajo 500 líneas. En la práctica, apunte a menos de 100 líneas por regla. Las reglas más cortas son más fáciles de mantener y cuestan menos tokens. Si una regla supera las 150 líneas, divídala en dos reglas enfocadas.

¿Las reglas funcionan con todos los modelos de IA en Cursor?

Las reglas funcionan con cada modelo que Cursor admite — Claude, GPT-4o, Gemini y otros. Las reglas se inyectan como contexto a nivel de sistema independientemente del modelo seleccionado. El comportamiento del modelo puede variar, pero las reglas en sí son agnósticas al modelo.

¿Cómo depuro una regla que no funciona?

Primero, verifique que el patrón glob coincida con su archivo — abra el archivo y compruebe si la regla aparece en el panel de contexto. Luego, pruebe con una pregunta directa que debería activar la regla. A continuación, intente configurar alwaysApply: true temporalmente para confirmar que el contenido de la regla funciona en sí mismo. Si lo hace, el problema es su patrón glob.

¿Debo confirmar .cursor/rules en git?

Absolutamente. El objetivo de las reglas de proyecto es la coherencia en todo el equipo. Confirme todo en .cursor/rules/ excepto los archivos de preferencias personales. Agregue personal.mdc a .gitignore para configuraciones individuales que no deberían aplicarse a todos.

¿Puedo usar Cursor Rules junto con servidores MCP?

Sí, y se complementan muy bien. Las reglas definen cómo la IA debe escribir código, mientras que los servidores MCP le dan a la IA acceso a herramientas y datos externos. Una regla podría decir "usa siempre nuestro cliente API interno", mientras que un servidor MCP permite a la IA consultar realmente esa API durante el desarrollo.

Fuentes

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub