Cursor Agent en proyectos grandes: 7 métodos para resolver archivos no encontrados y código incorrecto

Apareció el tercer mensaje de error en pantalla.

Hace un momento pedí a Cursor Agent que refactorizara el módulo de login: cinco archivos — formulario frontend, ruta API, middleware de autenticación, modelo de usuario y capa de caché Redis. Tras dos minutos, el Agent dijo con confianza: «Listo». Ejecuté el código y… se cayó.

Al revisar descubrí que encontró cuatro archivos pero solo modificó tres. Peor aún: «optimizó» la lógica del middleware que ya era correcta y todas las peticiones de login devolvían 401. Media hora revirtiendo a mano, reordenando dependencias y terminando yo el resto.

En ese momento dudaba: ¿puede un asistente de programación con IA manejar proyectos grandes?

Pasé dos semanas estudiando cómo funciona Cursor Agent, leyendo decenas de artículos y probando en proyectos reales. Acabé con un método para que el Agent sea más fiable en proyectos grandes. Ahora la tasa de éxito al refactorizar con Agent subió de menos del 50% a más del 90%.

Este artículo comparte 7 trucos prácticos desde gestión de contexto, división de tareas y revisión de código. No son teoría: son lecciones de proyectos reales.

Por qué el Agent falla en proyectos grandes

Antes de los trucos, conviene entender por qué falla. No es que «sea tonto»: hay tres limitaciones objetivas.

El contexto es el mayor cuello de botella

Aunque un modelo prometa 200k tokens, en un proyecto real no alcanza. Un proyecto frontend/backend mediano tiene cientos de archivos principales, cada uno con cientos o miles de líneas. Suma package.json, configs, tests… y superas el límite con facilidad.

El Agent no puede «ver» todo el proyecto. Solo ve los archivos mencionados en la conversación más lo que el índice automático de Cursor asocia. Es como buscar en un campo de fútbol viendo solo cinco metros: lo que se pierde es inevitable.

Probé en un proyecto React+Node.js: la misma petición en proyecto pequeño (20 archivos) tenía 85% de éxito a la primera; en mediano (50) bajaba al 60%; en grande (100+) caía al 35%. La diferencia es clara.

El «miopía» del Agent

El Agent suele «no ver» archivos de dependencia indirecta.

Si pides cambiar una ruta API, modifica la ruta y el Controller correspondiente. Pero ese Controller llama a una utilidad, que depende de un módulo de config… En cadenas ocultas, a menudo deja de rastrear en el segundo nivel.

Lo peor es la preferencia por lo reciente: prioriza archivos abiertos recientemente o mencionados en el chat. Si antes hablaste de un archivo sin relación con la tarea, puede incluirlo y cambiarlo mal. Y el archivo clave que no nombraste puede quedar fuera.

Falta de visión global

Es lo más grave.

Un desarrollador repasa mentalmente la arquitectura: ¿qué módulos intervienen? ¿Cómo se comunican? ¿Cambiar A afecta a B? El Agent no. Cada tarea es «optimización local»: mira el código a mano, elige la solución más razonable y actúa.

Vi un caso extremo: pedí optimizar consultas a base de datos. Añadió índices y ajustó SQL; fue más rápido. Tres días después la memoria explotó: para «optimizar» había puesto precarga de datos completos en caché y Redis colapsó.

El Agent no conoce el diseño global. Ve rendimiento y optimiza rendimiento; ve duplicación y extrae funciones, sin pensar si rompe la intención del diseño.

3 trucos clave de gestión de contexto

Sabiendo el problema, toca actuar. La gestión de contexto es lo primero: controla lo que el Agent «ve» y muchos problemas desaparecen.

Truco 1: optimizar Project Rules

Muchos meten todas las rules del proyecto en modo always. Es el error más grande.

always significa «cargar estas rules en cada conversación». Suena bien, pero consume tokens sin parar. Frontend, backend, tests, docs… cada uno con sus normas. Si todo va en always, un tercio de los tokens se va antes de empezar.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Lo correcto: Auto Attached + coincidencia glob

Ejemplo de un proyecto frontend/backend que mantengo:

# .cursorrules (raíz del proyecto)

# Reglas generales (solo lo esencial)
- type: always
  rules:
    - Usar TypeScript
    - Seguir configuración ESLint
    - Toda operación async debe tener manejo de errores

# Reglas frontend (solo al modificar frontend)
- type: auto
  glob: "src/frontend/**/*.{ts,tsx}"
  rules:
    - Usar React Hooks
    - Componentes con PropTypes o tipos TypeScript
    - Usar Tailwind CSS, sin estilos inline

# Reglas backend (solo al modificar backend)
- type: auto
  glob: "src/backend/**/*.ts"
  rules:
    - Rutas API con validación de entrada
    - Operaciones de BD en transacciones
    - No registrar información sensible en logs

# Reglas de tests
- type: auto
  glob: "**/*.test.ts"
  rules:
    - Cada test con descripción clara
    - Estructura Jest describe/it

Así el Agent carga reglas solo cuando hace falta. Medí: uso de tokens bajó un 70% y ya no se distrae con reglas irrelevantes.

Truco: al final de cada regla añade «si no estás seguro, pregúntame primero». Con eso, en casos límite pregunta en lugar de adivinar.

Truco 2: Long Context y Summarized Composers

Cursor tiene dos funciones útiles que muchos ignoran.

Long Context

Es un interruptor; actívalo en tareas complejas. El Agent usa una ventana de contexto mayor y ve más código.

No lo dejes siempre activo: consume tokens rápido y alarga el tiempo de respuesta. Mi hábito:

• Tareas normales (función, bug): desactivado
• Tareas complejas (refactor, nueva función): activado
• Muy complejas (refactor entre módulos): activado + referencias manuales con @

Summarized Composers

Permite acceder a resúmenes de conversaciones anteriores, no al historial completo. Ideal para proyectos largos.

Ayer el Agent escribió una utilidad; hoy quieres extenderla. Si dices «usa la función de ayer», puede no encontrarla. Con Summarized Composers busca en resúmenes del historial.

Mi flujo: al terminar un módulo grande, abro un Chat nuevo y empiezo con «En este proyecto ya implementamos XX, código en XX». Contexto histórico sin arrastrar demasiado detalle.

Truco 3: gestionar el contexto de forma activa

Lo más importante y lo que más se olvida.

No esperes que el Agent encuentre todos los archivos: dile qué ver y qué no.

Referencia archivos clave: sintaxis @

Al describir la tarea, marca con @archivo:

Ayúdame a refactorizar el flujo de autenticación. Archivos implicados:
@src/routes/auth.ts (ruta de autenticación)
@src/middleware/jwt.ts (middleware JWT)
@src/models/User.ts (modelo de usuario)
@src/utils/password.ts (utilidad de contraseña)

No modifiques otros archivos.

Esa última frase importa. Medí: con ella, cambios en archivos irrelevantes bajan del 30% a menos del 5%.

Limitar el alcance de cambios

Si solo afecta a un subdirectorio, dilo:

Añade un componente de recuperación de contraseña en src/frontend/components/auth/,
sin modificar código de otros directorios.

Uso avanzado: lista blanca + negra

Puedes modificar: todos los archivos bajo src/api/**
No modifiques: src/api/legacy/** (código legacy pendiente de retirar)

Libertad suficiente sin tocar lo prohibido.

Mi hábito: antes de asignar una tura, pienso «¿cuántos archivos como máximo debería tocar? ¿qué directorios?» y se lo digo al Agent. Parece molesto, pero ahorra mucho tiempo corrigiendo bugs después.

2 reglas de oro para dividir tareas

La gestión de contexto mitiga «no ver todo», pero tareas demasiado complejas también fallan. Ahí entra la división de tareas.

Truco 4: dividir por responsabilidad, no por archivos

Fue el error más grande que cometí.

Al principio dividía por archivos. Registro de usuario:

1. Componente de formulario frontend
2. Ruta API backend
3. Modelo de base de datos

Suena razonable, pero en la práctica:

• Frontend sin saber la forma de la API
• Backend con parámetros distintos a lo que esperaba el frontend
• Modelo con tipos incorrectos; frontend y backend otra vez

Mucho ida y vuelta, más lento.

División correcta: por responsabilidad funcional

Mismo ejemplo de registro:

Paso 1: flujo básico de registro (MVP)

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Tarea 1: registro mínimo viable
- Frontend: formulario solo con usuario y contraseña
- Backend: API de registro + validación básica
- BD: modelo User (campos mínimos)
Objetivo: flujo completo que registre un usuario

Paso 2: validación y seguridad

Tarea 2: validación y seguridad
- Formato de email
- Fortaleza de contraseña
- Anti-duplicados
- Almacenamiento cifrado

Paso 3: experiencia de usuario

Tarea 3: mejorar UX de registro
- Validación en tiempo real
- Auto-login tras registro
- Email de bienvenida

¿La diferencia? Cada tarea es vertical: frontend, backend y BD en un punto funcional independiente.

Ventajas:

1. Cada tarea se prueba sola: tras la tarea 1 ya corre
2. Menos retrabajo: frontend y backend juntos detectan problemas de API al instante
3. El Agent entiende mejor: objetivo claro, menos confusión

Medí: con división por responsabilidad, éxito a la primera del 60% al 85%.

Truco 5: checkpoints claros

Este truco me salvó muchas veces.

En proyectos grandes: cambias mucho, la dirección era mala y ya no puedes volver. Con Agent no pregunta «¿guardamos antes?» y modifica. Cuando te das cuenta, pueden ser docenas de archivos.

Usar Checkpoint

Cursor tiene Checkpoint, muy útil y subestimado.

Antes de empezar, crea un checkpoint:

# En Cursor: Cmd/Ctrl + Shift + P
# Escribe Create Checkpoint
# Nota: antes de refactorizar módulo de login

Deja trabajar al Agent. Si algo va mal, rollback al checkpoint y se deshace todo.

Mi hábito:

• Nueva tarea grande: checkpoint
• Tras el Agent: pruebas OK → borrar checkpoint; fallan → rollback
• Varias tareas pequeñas: checkpoint cada 2-3 tareas

Si el Agent falla, pierdes como mucho una tarea pequeña.

Desarrollo guiado por pruebas (TDD)

Más avanzado: tests primero, implementación después.

Parece trabajo extra, pero en proyectos grandes ayuda:

1. Escribe tests manualmente (comportamiento esperado)
2. Ejecuta y confirma que fallan (aún no hay implementación)
3. Pide al Agent implementar hasta que pasen
4. Si no pasan, el Agent entendió mal: para de inmediato

Los tests son una condición de parada clara. El Agent no divaga; busca «hacer pasar los tests».

En un proyecto Node.js refactoricé todo el módulo de autenticación así: siete iteraciones, sin desviarse. Sin tests, más de diez intentos con bugs.

2 prácticas clave de revisión y monitorización

Lo anterior reduce errores, pero cero no es realista. La última línea: revisión y monitorización — detectar pronto y cortar pérdidas.

Truco 6: revisión en varios niveles

Error común: creer que con IA ya no hace falta Code Review.

Al contrario: con IA la revisión importa más. Los errores del Agent suelen ser sutiles — sintaxis correcta, lógica aparentemente coherente, pero «no encaja». Lo que un humano ve al instante, el Agent puede no ver.

Reglas automáticas en Cursor Rules

Puedes definir reglas de Code Review en .cursorrules. Mi configuración:

# .cursorrules (sección de revisión)
code_review_rules:
  # Crítico (obligatorio corregir)
  critical:
    - "No hardcodear contraseñas, API keys u otros secretos"
    - "Consultas BD parametrizadas para evitar SQL injection"
    - "Validar y sanitizar toda entrada externa"

  # Advertencia (muy recomendable)
  warning:
    - "Funciones no más de 50 líneas; considerar dividir"
    - "Evitar any; tipos explícitos"
    - "Async con try-catch o .catch()"

  # Info (optimización opcional)
  info:
    - "Considerar tests unitarios"
    - "Comentarios en lógica compleja"
    - "Extraer código duplicado a funciones comunes"

Tras cada tarea, pido auto-revisión:

Tarea terminada. Revisa el código según code_review_rules en .cursorrules
y lista problemas critical y warning.

El Agent lista problemas; a menudo detecta en revisión lo que escribió antes. Es mirar el código desde otro ángulo.

Estrategia humano + máquina

Solo Agent no basta; solo manual es agotador. Nivel por nivel:

1. Primera pasada Agent (auto): errores sintácticos y de estilo obvios
2. Revisión humana focalizada:
   • ¿Lógica de negocio correcta? (donde más falla el Agent)
   • ¿Condiciones límite completas?
   • ¿Impacto en rendimiento? (N+1, etc.)
   • ¿Seguridad? (SQL injection, XSS, etc.)
3. Validación con tests: no romper funcionalidad existente

No revises línea a línea — pierdes tiempo. Centra la lógica core y riesgos; el resto, herramientas y tests.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

En proyectos grandes, ~15-20% del código del Agent tiene problemas:

• 5% bugs graves (lógica, seguridad)
• 10% calidad (rendimiento, mantenibilidad)
• 5% funciona pero no cumple normas del proyecto

Sin revisión, salen semanas después con coste de diagnóstico mucho mayor.

Truco 7: Git como último seguro

Suena básico, pero muchos no le dan importancia.

Usa git diff

Tras cambios del Agent, lo primero no es ejecutar tests:

git diff

Qué archivos cambiaron y cómo. Siempre reviso:

• ¿Volumen de cambios esperado? (decenas de archivos = alerta)
• ¿Archivos irrelevantes tocados?
• ¿Lógica clave alterada?

Truco: git diff --stat primero:

git diff --stat

# Ejemplo de salida:
# src/api/auth.ts          | 25 +++++---
# src/models/User.ts       | 12 ++--
# src/utils/password.ts    |  3 +-
# src/config/database.ts   | 150 ++++++++++++++++++++++++++++++++++++++++++++++

Si un archivo suma 150 líneas y la tarea no lo pedía… mira qué pasó.

Checkpoint + Git juntos

Doble seguro:

1. Antes de empezar:
   - git checkout -b feature/xxx  (nueva rama)
   - Crear Cursor Checkpoint

2. Tras el Agent:
   - git diff (revisar)
   - Ejecutar tests
   - Si OK: git commit
   - Si no:
     - Problema pequeño: arreglo manual o corrección puntual
     - Grande: rollback Checkpoint o git reset --hard

3. Tras confirmar:
   - git push
   - Abrir Pull Request

Ventajas:

• Checkpoint: rollback rápido sin historial Git
• Rama Git: aislamiento de la rama principal
• Historial de commits: trazabilidad

Hábito: en commits de tareas del Agent anoto:

git commit -m "feat: añadir registro de usuario (by AI Agent)"

Si hay problemas después, el commit indica código generado por Agent y reviso con más cuidado.

Conclusión

Volvamos a la escena de la una de la madrugada del inicio.

Si hoy refactorizara el módulo de login con Cursor Agent:

1. Contexto: .cursorrules del módulo de auth; @ en los 5 archivos clave; «solo modifica estos 5»
2. División: no todo de golpe; flujo básico, luego validación, luego caché
3. Revisión: tras cada subtarea, git diff, tests, y seguir solo si está bien

Así, probabilidad de no encontrar archivos del 50% a menos del 10%; de código incorrecto del 30% a menos del 5%. Tiempo extra por tarea: 5-10 minutos.

Las herramientas de programación con IA no son omnipotentes. No diseñan arquitectura, no entienden negocio por ti ni asumen calidad de código. Pero bien usadas duplican eficiencia — si aprendes a «gestionarlas».

Contexto, división de tareas, revisión de código — las tres dimensiones son imprescindibles. Contexto para que el Agent «vea bien»; división para que «haga bien»; revisión para que «duermas tranquilo».

Sugerencia: si usas Cursor Agent en un proyecto grande, dedica 10 minutos hoy a revisar Project Rules. Cambia always por auto + glob: ahorras tokens y el Agent mejora al instante.

La tecnología avanza, pero algunos principios no cambian: requisitos claros, tareas divididas, verificación continua. Válido para IA y para cualquier proyecto complejo.

¿Qué problemas has tenido con Cursor Agent? Comparte en los comentarios.