rules.md: El Estándar Definitivo para Controlar Agentes de IA en 2025

En la vertiginosa evolución del desarrollo de software asistido por Inteligencia Artificial, hemos presenciado la adopción masiva de estándares como agents.md o rules.md. Estos archivos se han convertido en la columna vertebral para guiar a los agentes de IA (como GitHub Copilot, Cursor, Gemini o Claude) en aspectos de arquitectura, patrones de código, estrategias de testing y convenciones de nombrado.

A medida que nos adentramos en 2025, la forma en que interactuamos con el código ha cambiado radicalmente. Ya no empezamos con un lienzo en blanco; empezamos con un contexto altamente estructurado. Sin embargo, este contexto puede ser un arma de doble filo. Si un agente de IA no conoce las convenciones específicas de tu proyecto, tu pila tecnológica, o tus preferencias arquitectónicas en ecosistemas complejos como Android, el resultado es a menudo un código genérico, desactualizado o, peor aún, que introduce antipatrones sutiles pero destructivos.

Cada nueva sesión de chat con un LLM solía ser como incorporar a un nuevo desarrollador junior desde cero todos los días: “Usamos Kotlin, preferimos inyección de dependencias con Hilt, no uses findViewById, emplea Jetpack Compose para la UI, asegúrate de manejar los flujos asíncronos con StateFlow y aislar la lógica de dominio en UseCases”. Repetir este mantra una y otra vez resultaba en una pérdida de tiempo masiva y una frustración palpable para el desarrollador senior. La solución definitiva a este problema de “amnesia crónica” de los agentes fue el nacimiento y estandarización de los archivos de reglas persistentes.

El estándar rules.md (y sus encarnaciones específicas de plataforma como .cursorrules, CLAUDE.md, o las modernas reglas estructuradas en el directorio .cursor/rules/ con el potente formato .mdc) actúa como un contrato semántico vinculante entre el desarrollador humano y el agente sintético. Es el equivalente a un onboarding automatizado, determinista y permanente. Al inyectar estas reglas de manera contextual y quirúrgica en cada interacción, la IA deja de ser un generador de texto estocástico propenso a alucinaciones y se convierte en un miembro del equipo altamente especializado, alineado perfectamente con la visión técnica del proyecto y las restricciones del dominio.

En este artículo, exploraremos en profundidad el concepto del estándar de reglas, su fascinante historia, cómo ha evolucionado desde archivos de texto plano monolíticos hacia sistemas de reglas granulares y dinámicas, y cómo implementar estas directrices de manera magistral en proyectos Android complejos utilizando Kotlin. A lo largo de esta extensa guía técnica, no solo aprenderás los fundamentos teóricos, sino que obtendrás plantillas prácticas, arquitecturas de configuración y estrategias avanzadas para dominar el desarrollo asistido por IA, garantizando que tu código escale sin comprometer la calidad ni la seguridad.

🏛️ Origen e Historia: Del Caos al Orden Sistémico

El concepto de un archivo dedicado a dictar reglas de comportamiento para la IA no surgió de un día para otro en un laboratorio de investigación aséptico, ni fue impuesto por un único comité estandarizador corporativo. Más bien, su desarrollo fue una respuesta orgánica, iterativa y comunitaria, impulsada por la intensa fricción que experimentaban los equipos de ingeniería al interactuar con modelos generativos en entornos de producción.

La Era de la Prehistoria Agentica (2023 - Principios de 2024)

En los primeros días de herramientas como GitHub Copilot original o ChatGPT incrustado en el flujo de trabajo, la interacción era puramente transaccional. Los desarrolladores copiaban bloques de código, los pegaban en una ventana de chat web y añadían instrucciones ad-hoc: “Refactoriza esto usando Kotlin Coroutines”. La IA no tenía idea de qué versión de Kotlin estabas usando, qué dependencias tenías en tu build.gradle.kts, o cuál era la arquitectura general de tu aplicación Android.

Esta falta de conciencia del entorno requería un esfuerzo mental extenuante por parte del desarrollador para proporcionar el contexto necesario en cada prompt. A esto lo llamábamos la era del “Prompting Fatigoso”.

El Surgimiento de los Prompts Globales y .cursorrules (Finales de 2024 - 2025)

Con la llegada de IDEs nativos de IA como Cursor, Windsurf y extensiones avanzadas de VS Code, el paradigma cambió. Estas herramientas introdujeron la capacidad de leer el contexto del repositorio local. Sin embargo, para evitar que la IA adivinara las intenciones del equipo analizando heurísticamente el código base, se introdujo el concepto de un archivo de manifiesto global.

Cursor popularizó el archivo .cursorrules. Ubicado en la raíz del proyecto, este archivo de texto plano (usualmente en formato Markdown) servía como un “System Prompt” inyectado invisiblemente al principio de cada interacción con el modelo de IA. Los equipos comenzaron a volcar toda su sabiduría tribal en este archivo: convenciones de nomenclatura, advertencias sobre bibliotecas deprecadas, reglas estrictas sobre el manejo de errores, y más.

El problema surgió rápidamente: los monolitos colapsan por su propio peso. Un archivo .cursorrules para una aplicación Android empresarial podía fácilmente superar las 1000 líneas. Contenía reglas para la capa de red (Retrofit/Ktor), reglas para la UI (Jetpack Compose), reglas de base de datos (Room), y reglas para CI/CD (GitHub Actions).

El Problema de la “Tasa de Tokens” (Token Tax) y la Dilución del Contexto

Cuando un LLM (como Claude 3.5 Sonnet o GPT-4o) recibe un contexto enorme, sufre de dos fenómenos:

1. Pérdida en el medio (Lost in the Middle): El modelo presta atención al principio y al final del prompt, pero a menudo ignora las instrucciones ubicadas en el centro del documento.
2. Impuesto de Tokens (Token Tax): Inyectar 10,000 tokens de reglas globales en cada pequeña petición de autocompletado es extremadamente costoso financieramente y añade latencia (tiempo hasta el primer token, TTFT). ¿Por qué la IA necesita leer las reglas de configuración de Firebase Crashlytics cuando solo le estás pidiendo que centre un texto en un botón de Jetpack Compose?

La Revolución Modular: El Formato .mdc y .cursor/rules/ (2025)

Para resolver la dilución del contexto y el impuesto de tokens, la industria evolucionó hacia un sistema de reglas basado en enrutamiento contextual. En lugar de un único archivo .cursorrules, los proyectos modernos adoptaron el directorio .cursor/rules/ (o implementaciones análogas en otras herramientas), poblado por múltiples archivos con extensión .mdc (Markdown Context) o simplemente .md con frontmatter estructurado.

Este avance permitió lo que llamamos Inyección Dinámica de Reglas (Dynamic Rule Injection). Cada regla ahora posee metadatos (generalmente en YAML frontmatter) que definen “cuándo” y “dónde” debe aplicarse. Si el desarrollador abre un archivo que termina en ViewModel.kt, la herramienta inyecta automáticamente las reglas de manejo de estado, pero omite por completo las reglas de diseño visual.

Esta modularidad no solo salvó millones de dólares en costos de inferencia a nivel global, sino que también incrementó drásticamente la precisión y adherencia a las reglas por parte de los agentes, permitiendo la creación de bases de código ultra-cohesivas y seguras.

⚖️ El Ecosistema de Reglas: Comparativa y Nomenclatura

En 2025, los agentes de codificación IA han convergido en un patrón arquitectónico común (archivos Markdown ubicados en la raíz del repositorio), pero utilizan diferentes nombres y convenciones según el proveedor. Comprender este ecosistema es vital para equipos que operan en entornos agnósticos o que migran entre herramientas.

1. agents.md (El Estándar Abierto)

Adoptado por la Linux Foundation y soportado por más de 100,000 repositorios de código abierto, agents.md es el equivalente a un archivo robots.txt pero para agentes de software. Es agnóstico a la herramienta. Fue diseñado para que agentes autónomos de orquestación, herramientas CLI (como Aider), y subagentes de CI/CD comprendan el contexto del proyecto. Suelen ser archivos sin metadatos complejos, enfocados en reglas de alto nivel y arquitectura.

2. .cursorrules (El Legado Histórico)

El formato original de archivo único. Aunque sigue siendo soportado por retrocompatibilidad por Cursor, se considera un patrón deprecado para proyectos medianos a grandes. Sigue siendo útil para proyectos de juguete o repositorios de un solo propósito (como un script de Python aislado), donde la sobrecarga de crear un directorio de reglas no se justifica.

3. .cursor/rules/*.mdc (El Estándar Industrial para Cursor)

El formato moderno y recomendado. Utiliza archivos .mdc que combinan Markdown con metadatos YAML. Permite enrutamiento basado en “globs” (expresiones regulares de rutas de archivos). Su principal ventaja es la resolución dinámica de contexto, lo que lo convierte en la opción más poderosa para arquitecturas multicapa como las que encontramos en el ecosistema de Android (Clean Architecture con capas de Presentación, Dominio y Datos).

4. CLAUDE.md (La Aproximación de Anthropic)

Anthropic introdujo CLAUDE.md para su herramienta Claude Code CLI y la interfaz web de Claude Projects. A diferencia de las reglas granulares de Cursor, CLAUDE.md se inclina por un enfoque más holístico. Claude, gracias a sus inmensas ventanas de contexto (más de 200k tokens) y su legendaria resistencia al problema “Lost in the Middle”, puede procesar un CLAUDE.md muy extenso sin degradación significativa del rendimiento. Es ideal para documentar la filosofía general del proyecto y comandos de compilación frecuentes (pnpm test, ./gradlew assembleDebug).

5. copilot-instructions.md (La Visión de GitHub)

GitHub Copilot utiliza este archivo para anclar las instrucciones del asistente en el contexto del repositorio. Su funcionalidad se alinea más estrechamente con el antiguo .cursorrules, aplicando instrucciones de manera bastante global. Sin embargo, Microsoft ha ido integrando capacidades de resolución de contexto semántico (Semantic Code Search), lo que permite a Copilot inferir reglas implícitas buscando en otros archivos del proyecto.

La Intersección con design.md

Es crucial distinguir entre las reglas de ingeniería y las directrices de diseño. En la taxonomía moderna de documentación asistida por IA:

• agents.md o .cursor/rules/: Dictan el CÓMO se construye el software. Tratan sobre concurrencia, tipos estáticos, arquitecturas (MVVM, MVI), patrones de inyección, y seguridad (evitar inyección SQL, manejo de datos sensibles).
• design.md: Dicta el QUÉ y el POR QUÉ desde una perspectiva visual y de usuario. Trata sobre tokens de color (Material 3), tipografía, jerarquía visual, pautas de accesibilidad (TalkBack en Android), animaciones y el tono de voz de la aplicación.

Un agente frontend avanzado (como Spec-Kitty o OpenSpec) leerá simultáneamente una regla de compose.mdc (que le dirá que use Modifier.fillMaxWidth()) y el archivo design.md (que le dirá que los botones primarios deben tener un radio de esquina de 16.dp).

🧠 La Anatomía Estructural de un Archivo .mdc Perfecto

Para exprimir al máximo las capacidades de enrutamiento contextual en 2025, debemos entender la anatomía profunda de un archivo .mdc moderno. Diseñar reglas no es simplemente escribir una lista de deseos; es ingeniería de prompts (Prompt Engineering) aplicada a nivel de infraestructura.

Un archivo .mdc bien diseñado consta de dos partes fundamentales: el Frontmatter YAML y el Cuerpo de Markdown.

1. El Frontmatter YAML: El Cerebro del Enrutamiento

El frontmatter le dice al motor del IDE o al orquestador del agente exactamente cuándo esta regla es relevante. Sin esto, volvemos a la era oscura de la dilución de contexto.

---
description: "Convenciones estrictas para el desarrollo de UI con Jetpack Compose y Material 3"
globs: ["**/ui/**/*.kt", "**/components/**/*.kt", "**/screens/**/*.kt"]
alwaysApply: false
---

Analicemos los componentes:

• description: No es solo un comentario para los humanos. El motor semántico del agente utiliza esta descripción para decidir si invocar la regla cuando el usuario hace una pregunta general, incluso si no ha abierto ningún archivo específico. Si el usuario escribe “¿Cómo hago un botón en esta app?”, el agente escanea las descripciones de todas las reglas, encuentra “desarrollo de UI”, y activa esta regla dinámicamente.
• globs: Define los patrones de coincidencia de archivos. Esta es la magia. Al especificar **/ui/**/*.kt, garantizamos que estas reglas de Jetpack Compose nunca contaminarán el contexto cuando el agente esté trabajando en un DAO de la base de datos Room (**/data/local/**/*.kt), ahorrando tokens y previniendo alucinaciones.
• alwaysApply: Un booleano crítico. Si se establece en true, la regla se inyecta incondicionalmente en cada prompt de este repositorio, independientemente de los archivos abiertos. Úselo con extrema precaución. Reserve alwaysApply: true exclusivamente para reglas base inviolables (ej. “Respeta a rajatabla los principios SOLID”, “Escribe siempre en inglés”).

2. El Cuerpo de Markdown: Directivas Claras, Concisas y Deterministas

El cuerpo de la regla debe evitar el lenguaje ambiguo. Los LLMs responden mejor a imperativos fuertes, restricciones negativas claras (“NUNCA HAGAS X”) y ejemplos de código positivos (“pocos disparos” o few-shot prompting).

Principios para escribir el cuerpo:

1. Prioridad por Negación: Los modelos de lenguaje a menudo “olvidan” las instrucciones positivas complejas, pero son notablemente obedientes a las restricciones negativas absolutas. Comience siempre con lo que NO se debe hacer.
2. Jerarquía Visual: Utilice encabezados (##, ###), listas viñeteadas y negritas para resaltar palabras clave críticas (**OBLIGATORIO**, **NUNCA**).
3. Snippets de Código Contextuales: La forma más rápida de entrenar a un LLM en el comportamiento deseado es mostrarle un ejemplo de “Código Bueno” vs “Código Malo”.

Veamos un ejemplo práctico de la estructura interna de una regla para un ViewModel en Android:

# Reglas de Implementación de ViewModel

Eres un experto desarrollador Android Senior especializado en MVVM y Kotlin Coroutines.
Tu objetivo es escribir ViewModels seguros, reactivos y eficientes.

## 🚫 RESTRICCIONES CRÍTICAS (NUNCA HACER ESTO)
- NUNCA expongas `MutableStateFlow` o `MutableLiveData` al exterior. Usa siempre propiedades de solo lectura (`StateFlow` o `LiveData`).
- NUNCA pases el `Context` de Android a un ViewModel. Esto provoca memory leaks masivos. Usa inyección de dependencias para proveer recursos si es absolutamente necesario, o maneja los strings en la UI.
- NUNCA uses `GlobalScope` ni `CoroutineScope(Dispatchers.IO)`. Usa SIEMPRE `viewModelScope.launch`.

## ✅ PATRONES REQUERIDOS (SIEMPRE HACER ESTO)
- Maneja el estado de la UI utilizando una única data class `UiState`.
- Emplea un canal de eventos `Channel` para *One-Time Events* (ej. mostrar un Toast, navegación).
- Inyecta todas las dependencias (UseCases, Repositorios) mediante constructor usando la anotación `@HiltViewModel` y `@Inject`.

## 📝 EJEMPLO CANÓNICO DE REFERENCIA

```kotlin
// BUENO: Encapsulamiento de estado y eventos con Hilt
@HiltViewModel
class UserProfileViewModel @Inject constructor(
    private val getUserProfileUseCase: GetUserProfileUseCase
) : ViewModel() {

    private val _uiState = MutableStateFlow(UserProfileUiState())
    val uiState: StateFlow<UserProfileUiState> = _uiState.asStateFlow()

    private val _uiEvent = Channel<UserProfileEvent>()
    val uiEvent = _uiEvent.receiveAsFlow()

    fun fetchUser(userId: String) {
        viewModelScope.launch {
            _uiState.update { it.copy(isLoading = true) }
            try {
                val user = getUserProfileUseCase(userId)
                _uiState.update { it.copy(isLoading = false, user = user) }
            } catch (e: Exception) {
                _uiState.update { it.copy(isLoading = false, error = e.message) }
                _uiEvent.send(UserProfileEvent.ShowError(e.message ?: "Unknown error"))
            }
        }
    }
}
```

Este enfoque transforma a tu IA de un codificador genérico a un purista de MVVM alineado a tus estándares arquitectónicos exactos.

🛠️ Guía Paso a Paso: Implementando un Sistema .mdc en un Proyecto Android Complejo

Imaginemos un proyecto Android de gran escala, quizás una aplicación de banca o un e-commerce robusto, modularizado por funcionalidades (features/) y capas (core/, domain/, data/, ui/). Así es como arquitectaríamos el directorio .cursor/rules/ para un control IA sin precedentes.

Paso 1: Inicializar el Directorio y la Regla Base

Primero, crea el directorio .cursor/rules/ en la raíz de tu proyecto. El primer archivo que debemos añadir es la regla base que siempre debe aplicarse.

Crea .cursor/rules/00-base-android.mdc:

---
description: "Reglas fundamentales de Android aplicables a todo el proyecto. Estilo, Kotlin y arquitectura base."
globs: ["*.kt", "*.kts"]
alwaysApply: true
---

En el cuerpo de este archivo, definiremos cosas universales:

• Usar Kotlin 2.1+.
• Prevenir el uso de !! (operador no nulo forzado). La IA debe preferir el safe call ?. y el Elvis operator ?:.
• Exigir convenciones de nombrado estandarizadas (interfaces empiezan con “I” o clases implementadas terminan en “Impl”).
• Dictar que todas las fechas deben manejarse con java.time y nunca con el antiguo java.util.Date.

Paso 2: Reglas Específicas para la Capa de Datos (Room & Retrofit)

La capa de datos requiere reglas estrictas sobre el manejo de transacciones, migraciones de base de datos y serialización JSON.

Crea .cursor/rules/10-data-layer.mdc:

---
description: "Reglas para Repositorios, DAOs (Room), DTOs y llamadas a red (Retrofit/Ktor)."
globs: ["**/data/**/*.kt", "**/*Dao.kt", "**/*Dto.kt", "**/*RepositoryImpl.kt"]
alwaysApply: false
---

El cuerpo debe incluir instrucciones como:

• “Todos los métodos en DAOs de Room deben ser funciones suspend a menos que devuelvan un Flow”.
• “NUNCA expongas clases de la base de datos (Entidades Room) o modelos de red (DTOs) a la capa de dominio. Mapea SIEMPRE las entidades a Modelos de Dominio limpios usando funciones de extensión .toDomain()”.
• “Utiliza Moshi o Kotlinx Serialization. No uses Gson bajo ninguna circunstancia, se considera legado en este proyecto”.

Paso 3: Reglas de la Capa de UI y Jetpack Compose

Aquí es donde la IA tiende a descarrilarse más debido a la rápida evolución del ecosistema de Compose.

Crea .cursor/rules/20-compose-ui.mdc:

---
description: "Pautas de desarrollo para componentes de UI en Jetpack Compose, Material Design 3 y manejo de estados."
globs: ["**/ui/**/*.kt", "**/presentation/**/*.kt", "**/screens/**/*.kt", "**/components/**/*.kt"]
alwaysApply: false
---

Las reglas de Compose deben ser muy detalladas:

• “Todos los componentes UI custom deben ser funciones @Composable y deben aceptar un parámetro modifier: Modifier = Modifier como su primer parámetro opcional”.
• “No pases ViewModels hacia abajo a los componentes hijos (State Hoisting). Pasa funciones lambda para los eventos (ej. onItemClick: (Item) -> Unit) y los estados requeridos explícitamente”.
• “Usa rememberSaveable para estados de UI que deban sobrevivir a cambios de configuración, no solo remember”.
• “Integra descripciones de accesibilidad usando semantics { contentDescription = "..." } en elementos interactivos que no posean texto inherente”.

Paso 4: Reglas de Configuración de Build y CI/CD

El entorno de construcción también necesita directrices, especialmente cuando migramos a Gradle Version Catalogs o Kotlin DSL.

Crea .cursor/rules/30-build-gradle.mdc:

---
description: "Gestión de dependencias de Gradle, Kotlin DSL y Version Catalogs."
globs: ["*.gradle.kts", "gradle/libs.versions.toml", "build.gradle.kts"]
alwaysApply: false
---

Instrucciones:

• “Cualquier nueva dependencia debe añadirse centralmente en libs.versions.toml. NUNCA hardcodees la versión directamente en un build.gradle.kts”.
• “Mantén los bloques de plugins ordenados de forma alfabética”.

Al modularizar estas instrucciones, garantizamos que cuando un desarrollador le pide a la IA: “Agrega un botón en la pantalla de Perfil”, el agente solo leerá 00-base-android.mdc y 20-compose-ui.mdc. No perderá tokens vitales (ni tiempo de atención algorítmica) leyendo sobre mapeos de bases de datos o configuraciones de Gradle.

🌐 Comparativa Evolutiva: Interacción de Modelos LLM con rules.md

El ecosistema de IA no es homogéneo. Diferentes familias de modelos procesan los archivos de reglas con distintas fortalezas y debilidades. Como ingenieros de software, debemos optimizar nuestros archivos .mdc teniendo en mente el hardware subyacente y la arquitectura neuronal de los agentes.

1. La Familia Claude 3.5 (Anthropic) y la Ventana de Contexto Perceptiva

Claude 3.5 (incluyendo Sonnet y Opus) domina actualmente la comprensión de contexto extenso gracias a su tecnología de memoria jerárquica y atención esparcida. Cuando un archivo .mdc se inyecta en Claude, el modelo exhibe una retención excepcional de las reglas, incluso aquellas ubicadas al final del documento. Táctica Recomendada: Con Claude, puedes permitirte ser exhaustivo. Puedes incluir múltiples “ejemplos negativos” detallados. Claude sobresale en tareas holísticas de refactorización donde tiene que escanear un archivo viejo y alinearlo con un extenso manual de estilo definido en rules.md. Es el motor preferido detrás de los agentes de orquestación (MAO) que operan autónomamente sobre PRs completos.

2. La Familia GPT-4o / O1 (OpenAI) y el Razonamiento Deductivo

Los modelos O1 introdujeron los paradigmas de razonamiento implícito (Hidden Chain of Thought). Al enfrentarse a un archivo de reglas, estos modelos no solo leen las directrices, sino que “piensan” a través de ellas. Si una regla en .cursorrules establece que “La inyección de dependencias está prohibida en componentes Composable”, el modelo O1 inferirá proactivamente las ramificaciones de esto y estructurará el ViewModel para gestionar las dependencias internamente y exponer solo lambdas simples a la UI. Táctica Recomendada: Sé explícito sobre los “Por qués” (The Whys). O1 responde brillantemente si explicas el razonamiento detrás de la regla. En lugar de decir “No uses LiveData”, di “No uses LiveData porque no escala bien con Coroutines asíncronas de alto rendimiento y viola nuestros patrones reactivos asíncronos”. El modelo internalizará el principio y lo aplicará a casos frontera no explícitamente listados.

3. Modelos de Autocompletado Ligeros (DeepSeek Coder V2, StarCoder 2, Gemini Nano)

Estos modelos SLM (Small Language Models) operan localmente en el dispositivo o mediante APIs de muy baja latencia. Su tarea es adivinar las próximas 10-50 líneas de código a medida que escribes (autocompletado en línea tab-to-complete). Son altamente sensibles a la saturación de tokens. Táctica Recomendada: Para herramientas que alimentan reglas a modelos SLM, la granularidad es vida o muerte. Utiliza el directorio .cursor/rules/ de forma estricta. Si inyectas más de 1000 tokens en un SLM, su rendimiento de autocompletado colapsará y comenzará a generar código aleatorio o entrará en bucles de repetición (“hallucination loops”). Mantén los archivos .mdc para autocompletado por debajo de las 500 palabras.

🚀 Orquestación Avanzada: Sinergia entre rules.md, SDD y MAO

El verdadero poder de rules.md emerge cuando se integra en marcos de desarrollo de orden superior como el Spec-Driven Development (SDD) o se maneja a través de un Multi-Agent Orchestrator (MAO).

En 2025, los equipos altamente apalancados en IA no dependen de agentes individuales actuando en el vacío. Utilizan orquestadores. Cuando un Orquestador MAO recibe una nueva tarea (ej. “Implementar login offline con Room”), sigue un protocolo estricto:

1. Fase de Ingestión de Reglas: El orquestador escanea el repositorio y lee todas las políticas en .cursor/rules/. Compila un “Perfil de Restricciones del Proyecto”.
2. Generación de Especificaciones (SDD): Utilizando un framework como OpenSpec, un subagente Analista redacta una especificación formal de la solución. Esta especificación es verificada automáticamente (usando técnicas de refutación socrática) contra las reglas extraídas en la fase 1. Si la especificación sugiere usar SQLiteOpenHelper, la regla 10-data-layer.mdc que exige el uso exclusivo de Room activará una alarma, y el documento de especificación será rechazado y re-generado antes de escribir una sola línea de código.
3. Fase de Ejecución: Múltiples agentes (frontend, backend, QA) proceden a escribir el código. Cada agente recibe dinámicamente solo el subconjunto de archivos .mdc relevantes para su dominio. El Agente de QA recibe las reglas de testing (40-testing.mdc) que le exigen usar MockK y Turbine para testear los flujos, ignorando la existencia de Mockito.

Esta arquitectura garantiza que la deuda técnica se prevenga por diseño (by design), no mediante tediosas revisiones de código posteriores al hecho. Las reglas actúan como guardianes inquebrantables del repositorio, inmunizando al proyecto contra las alucinaciones y divergencias estilísticas de la inteligencia artificial.

🛠️ Antipratrones y Depuración: Cuando las Reglas Fallan

Incluso con el mejor sistema .mdc, las cosas pueden salir mal. Aquí listamos los antipatrones más comunes que observamos en los equipos modernos y cómo solucionarlos.

1. El Antipatrón “Regla Contradictoria”

Síntoma: El agente genera un bloque de código y luego, en la misma respuesta, genera un bloque de comentarios disculpándose y reescribiendo el código, o produce un híbrido extraño (ej. mezcla LiveData y StateFlow). Causa: Existe un conflicto de precedencia. Puede que tengas un archivo .cursorrules heredado que dice “Usa LiveData” y un .cursor/rules/20-compose.mdc nuevo que dice “Usa StateFlow”. El LLM se confunde ante el doble vínculo. Solución: Auditoría de reglas. Elimina .cursorrules globales y migra el 100% de la lógica a .mdc enrutados por globs de forma mutuamente excluyente.

2. El Antipatrón “Sobrecarga de Abstracción”

Síntoma: El modelo ignora las reglas completamente, volviendo a generar código genérico. Causa: Has superado la ventana de contexto efectivo o has diluido la atención del modelo con información irrelevante en un bloque alwaysApply: true. Solución: Refactoriza tus reglas. Mueve la lógica especializada a archivos .mdc con globs más restrictivos. Reemplaza largos párrafos narrativos por viñetas concisas.

3. El Antipatrón “Regla de Perfección Utópica”

Síntoma: Las reglas exigen arquitecturas tan elaboradas (Clean Architecture con 5 capas de interfaces vacías) que la IA falla en generar código funcional simple. Causa: Reglas desconectadas de la pragmática. Exigir abstracciones excesivas ahoga las capacidades generativas del agente. Solución: Implementa reglas pragmáticas. Permite excepciones explícitas. En tu .mdc, puedes añadir: “Para operaciones CRUD simples sin lógica de negocio, se permite a la UI interactuar directamente con el Repositorio, saltándose la capa de UseCases para evitar boilerplate innecesario”.

🏆 Conclusión: El Futuro de las Reglas para la IA

El estándar rules.md y la evolución hacia el formato contextual .mdc representan uno de los avances más profundos en la disciplina de la interacción Humano-Máquina en la ingeniería de software. Hemos transitado de la codificación asistida basada en el conocimiento general pre-entrenado del modelo, hacia un desarrollo quirúrgico anclado en hiper-contexto dinámico.

En el desarrollo de aplicaciones móviles con Kotlin y Android, donde la fragmentación arquitectónica y la rápida evolución de librerías como Jetpack Compose pueden abrumar incluso a los equipos más experimentados, contar con un directorio .cursor/rules/ bien mantenido no es un lujo: es un requisito operativo indispensable en 2025.

Las reglas son la cristalización de la experiencia del arquitecto humano. Nos permiten delegar la implementación de bajo nivel a los agentes sintéticos con total confianza, sabiendo que respetarán nuestros estándares de calidad, seguridad y diseño arquitectónico. El futuro del desarrollo no pertenecerá a quienes escriban código más rápido, sino a quienes sepan especificar las restricciones de su sistema con mayor precisión algorítmica. Un gran sistema de reglas transforma a la IA de una simple herramienta predictiva en una extensión verdaderamente alineada del intelecto del equipo de ingeniería.