Cómo los equipos de desarrollo configuran las reglas de Cursor para aplicar patrones de arquitectura y estándares de código en múltiples repositorios

Los equipos de ingeniería aplican patrones de arquitectura y convenciones de código en Cursor migrando del archivo monolítico heredado .cursorrules a Reglas de Proyecto modulares (.cursor/rules/*.mdc), estructurando las directrices en invariantes globales y límites delimitados por rutas de archivos (Globs), y distribuyéndolas a través de múltiples repositorios mediante Cursor Team Rules o canalizaciones automatizadas de CI/CD.

Cuando una organización adopta un asistente de codificación con IA sin controles deliberados, se produce una rápida «deriva arquitectónica»: los desarrolladores reciben sugerencias de estilos dispares, los modelos alucinan bibliotecas internas obsoletas y la generación automática rompe los límites entre capas del sistema. Diseñar un sistema de reglas estructurado y controlado por versiones en Git proporciona límites deterministas al código generado por la IA, conservando al mismo tiempo el presupuesto de tokens del contexto.

El problema del gobierno técnico con IA en equipos de ingeniería

Cuando una organización técnica implementa Cursor a gran escala, los modelos de lenguaje trabajan con conocimientos públicos generales en lugar de los estándares internos del equipo. Esto genera problemas habituales en producción:

• Ruptura de las fronteras arquitectónicas: Las sugerencias de la IA traspasan con frecuencia las capas de abstracción, inyectando consultas de base de datos directas en componentes de interfaz de usuario o saltándose la capa de dominio.
• Dependencias obsoletas y alucinadas: Los modelos sugieren utilidades internas en desuso (por ejemplo, invocando el paquete obsoleto @company/legacy-ui en lugar del estándar @company/design-system-v2) o añaden paquetes externos no homologados.
• Fragmentación estilística del código: El código combinado mezcla paradigmas funcionales y orientados a objetos, formatos contradictorios de gestión de errores y enfoques dispares de manejo del estado.
• Pruebas unitarias deficientes: Los generadores de código tienden a omitir aserciones en los límites, utilizan librerías de simulación desactualizadas o ignoran por completo la cobertura de pruebas.

Para solucionar estos desajustes, los arquitectos de software deben transformar las directrices del equipo en instrucciones persistentes e integradas en el propio repositorio.

Evolución de las reglas de Cursor: de .cursorrules a .mdc modular

Originalmente, Cursor utilizaba un único archivo .cursorrules ubicado en la raíz del repositorio. Aunque se mantiene por compatibilidad hacia atrás, un archivo monolítico obliga al modelo a cargar todas las instrucciones en cada mensaje, saturando la ventana de contexto y degradando la precisión de las respuestas.

El sistema actual de Cursor utiliza Reglas de Proyecto (Project Rules) dentro del directorio .cursor/rules/, estructuradas en archivos .mdc (Markdown Cursor) con encabezados YAML Frontmatter.

Estructura de un archivo .mdc

Cada archivo .mdc combina metadatos de configuración con directrices técnicas concretas:

---
description: Límites del dominio de servicios y patrones de repositorio
globs: src/domains/**/*.ts, src/services/**/*.ts
alwaysApply: false
---

# Reglas de la capa de dominio

- Los servicios de dominio nunca deben procesar objetos de petición HTTP en crudo.
- Todas las mutaciones de base de datos deben realizarse mediante interfaces de repositorio.

Modos de activación y parámetros de Frontmatter

El encabezado YAML determina cuándo y cómo se inyecta la regla en la ventana de contexto:

Modelos de reglas de producción para arquitectos de software

Una arquitectura de reglas sólida divide las directrices en archivos .mdc con una única responsabilidad. A continuación se presentan tres plantillas probadas para entornos empresariales.

1. Invariantes globales del repositorio (.cursor/rules/00-core-architecture.mdc)

Aplica de forma continua en todo el código base y define los estándares mínimos obligatorios.

---
description: Invariantes globales de arquitectura, pila base y dependencias prohibidas
alwaysApply: true
---

# Invariantes de arquitectura base

## Pila tecnológica y versiones
- Entorno de ejecución: Node.js v20 LTS
- TypeScript: v5.4+ con `strict: true` activado
- Framework: Next.js App Router (v14+)
- Manejo de estado: Zustand (PROHIBIDO incorporar Redux o MobX)

## Paquetes y patrones prohibidos
- PROHIBIDO: `axios` (utilizar el cliente nativo `fetch` encapsulado en `@lib/api-client`)
- PROHIBIDO: `@company/ui-core-v1` (obsoleto; utilizar `@company/design-system-v2`)
- PROHIBIDO: `moment.js` (utilizar exclusivamente `date-fns`)

## Estándares de calidad de código
- Prohibido el uso de `any` explícito. Utilizar `unknown` junto con guardas de tipos.
- Utilizar cláusulas de guarda y retornos tempranos; evitar bloques `if/else` anidados en más de dos niveles.
- Nunca codificar credenciales, claves de API o secretos en el código fuente.

2. Capa de dominio y arquitectura limpia (.cursor/rules/backend-services.mdc)

Se activa únicamente cuando los desarrolladores editan archivos dentro de los servicios o dominios de backend.

---
description: Reglas de arquitectura hexagonal y patrones de repositorio en servicios
globs: src/services/**/*.ts, src/domains/**/*.ts
alwaysApply: false
---

# Estándares de la capa de dominio

## Responsabilidades por capa
- Los controladores gestionan la serialización HTTP, validación de parámetros y códigos de estado.
- Los servicios contienen la lógica de negocio pura. Nunca pasar objetos `req` o `res` de Express/Fastify a los servicios.
- Los repositorios encapsulan la persistencia. Los servicios deben depender de interfaces abstractas de repositorio, nunca de instancias directas del ORM.

## Ejemplos de implementación

```typescript
// ✅ CORRECTO: El servicio depende de una interfaz abstracta y maneja entidades de dominio
export class OrderService {
  constructor(private readonly orderRepository: OrderRepositoryPort) {}

  async processOrder(orderId: string): Promise<Result<Order>> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) return Result.fail('Order not found');
    order.markPaid();
    await this.orderRepository.save(order);
    return Result.ok(order);
  }
}

// ❌ PROHIBIDO: Llamadas directas al ORM y consultas SQL dentro de la lógica de negocio
export class OrderService {
  async processOrder(orderId: string) {
    await prisma.orders.update({ where: { id: orderId }, data: { status: 'PAID' } });
  }
}

### 3. Estándares para pruebas automatizadas (`.cursor/rules/testing-standards.mdc`)

Garantiza que las pruebas generadas por la IA utilicen los frameworks de simulación y patrones aprobados.

```markdown
---
description: Estándares de diseño para pruebas unitarias y de integración
globs: **/*.test.ts, **/*.spec.ts, src/tests/**/*
alwaysApply: false
---

# Estándares de pruebas automatizadas

## Herramientas de prueba
- Ejecutor de pruebas: Vitest
- Librería de simulación: `vi.mock()` (No mezclar con módulos de Jest)
- Aserciones: `expect()` con comparadores explícitos

## Estructura de las pruebas
- Organizar cada prueba según el patrón Arrange-Act-Assert (Preparar-Actuar-Verificar).
- Ubicar las pruebas unitarias junto al archivo fuente: `feature.service.ts` junto a `feature.service.test.ts`.
- Simular conexiones de red y accesos a base de datos en pruebas unitarias; no ejecutar conexiones vivas.
- Incluir siempre casos de prueba negativos (validaciones incorrectas, accesos no autorizados y excepciones).

Escalabilidad entre múltiples repositorios: Monorrepositorios y Polirrepositorios

Distribuir y sincronizar reglas a través de decenas o cientos de repositorios requiere enfoques adaptados a la topología de la organización.

                          Gobierno de reglas en la empresa
                                         │
         ┌───────────────────────────────┴───────────────────────────────┐
         ▼                                                               ▼
   Estrategia Monorepo                                             Estrategia Polyrepo
  ├── .cursor/rules/00-core.mdc                                   ├── Repositorio central: org-cursor-rules
  ├── .cursor/rules/apps-web.mdc (Glob: apps/web/**)              ├── Validación y sincronización en CI/CD
  └── .cursor/rules/shared-ui.mdc (Glob: packages/**)             └── Cursor Team Rules (Panel de administración)

Estrategia A: Delimitación jerárquica en Monorrepositorios

En monorrepositorios gestionados con Turborepo, Nx o pnpm workspaces, todas las reglas se ubican en la carpeta raíz .cursor/rules/, pero se aíslan mediante patrones globs:

• globs: ["apps/web/**/*"]: Aplica directrices de Next.js, aislamiento de componentes y clases de utilidad Tailwind.
• globs: ["apps/api/**/*"]: Rige especificaciones de OpenAPI, migraciones y esquemas de backend.
• globs: ["packages/ui/**/*"]: Exige retrocompatibilidad estricta, atributos de accesibilidad (ARIA) y ausencia de dependencias externas pesadas.
• Ventaja: Al modificar un componente frontend, Cursor ignora las directrices del backend, manteniendo limpio el contexto.

Estrategia B: Sincronización en Polirrepositorios mediante CI/CD (Reglas como código)

En ecosistemas con microservicios o múltiples repositorios independientes, gestionar las reglas como bibliotecas compartidas versionadas resulta fundamental:

1. Repositorio central de estándares: Crear un repositorio Git dedicado (por ejemplo, github.com/org/cursor-rules-standards) donde se alojen los archivos .mdc oficiales con etiquetas de versión semántica (v1.2.0).
2. Validación de desviación en CI: Integrar un paso en la integración continua de cada proyecto que verifique si los archivos locales de .cursor/rules/ coinciden con la última versión aprobada.
3. Flujo automatizado de actualización: Configurar un flujo de GitHub Actions o script de GitLab CI que clone las reglas oficiales y abra un Pull Request automático cuando surja una nueva versión.

Estrategia C: Administración centralizada con Cursor Team Rules

Las organizaciones con suscripciones Cursor Team o Enterprise pueden aprovechar la gestión desde la consola en la nube:

• Distribución centralizada: Los administradores definen reglas globales en el panel de control de Cursor, y estas se transmiten automáticamente a todos los desarrolladores de la organización.
• Reglas obligatorias vs. opcionales: La empresa puede marcar las reglas de seguridad, licencias y pila base como «Obligatorias» (Enforced), impidiendo que se desactiven localmente, mientras deja otras reglas como «Opcionales».
• Adopción inmediata: Cualquier miembro que clone un nuevo repositorio hereda de inmediato las políticas corporativas sin necesidad de duplicar archivos manualmente.

Buenas prácticas y errores frecuentes

Organizar las reglas de Cursor mediante archivos .mdc modulares vinculados a rutas y sincronizados mediante automatización en Git o Cursor Team Rules permite a las empresas maximizar la productividad de la IA manteniendo la cohesión arquitectónica en todos sus repositorios.

Referencias

• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI