Cascade de Windsurf: guía y buenas prácticas.

Recientemente, he estado interactuando con Cascade Windsurf integrado en un Intellij para desarrollar un piloto con IA probando diferentes técnicas. Cascade es un asistente de IA avanzado e integrado que ofrece capacidades como la autonomía para ejecutar acciones e implementar soluciones completas, que entiende el contexto del proyecto profundamente, donde tendremos herramientas especializadas, se puede desarrollar de modo multitask y donde se almacenan memorias con pasos importantes que se han dado durante el desarrollo de una tarea.

En este post voy a describir cómo ha sido mi experiencia con esta herramienta durante los últimos 3 meses, y en el siguiente post hablaré sobre el uso de la interfaz, definiendo sus reglas y los modos de trabajo (chat y code).

Hablaremos sobre modelos, capacidades, modos de empleo de los modelos (que denominaremos “modelo de trabajo”), estrategia de planes... Una guía completa donde veremos cómo hemos utilizado esta herramienta tan útil, siempre con el objetivo de mejorar y adoptar nuevas formas y paradigmas.

¿Qué es Cascade de Windsurf?

Cascade es un asistente de IA agentic desarrollado por Windsurf, diseñado específicamente para pair programming y desarrollo de software. A diferencia de un simple autocompletado de código, Cascade es un agente autónomo capaz de:

• Entender contexto completo: analiza tu proyecto, archivos abiertos, estructura del código y decisiones arquitectónicas.
• Ejecutar acciones: no solo sugiere código, sino que puede editar archivos, ejecutar comandos, navegar el proyecto y validar cambios.
• Razonar y planificar: descompone tareas complejas en pasos, investiga soluciones y propone estrategias antes de implementar.
• Aprender del proyecto: usa un sistema de memorias persistentes para recordar reglas, patrones y decisiones específicas de tu codebase.

Es, en esencia, un compañero de desarrollo que entiende tanto el código como el contexto del proyecto.

Características principales

1 Integración profunda con el IDE

Cascade se integra nativamente con IDEs como IntelliJ IDEA y VS Code, proporcionando:

• Acceso a archivos abiertos y posición del cursor.
• Capacidad de editar múltiples archivos simultáneamente.
• Ejecución de comandos del sistema (Maven, npm, git, etc.).
• Navegación inteligente del proyecto.

2 Múltiples modelos de IA

Permite cambiar entre diferentes modelos según la tarea:

• Gemini Pro 2.5 para equilibrio velocidad/calidad.
• Claude Sonnet 4 para máxima precisión.
• Claude Sonnet 3.7 (Thinking) para un razonamiento visible.
• GPT-5 para capacidades avanzadas.
• (Nuevo) Claude Sonnet 4.5 (Thinking) para un razonamiento interno más profundo antes de responder, mejor planificación de tareas complejas, mayor precisión en la resolución de problemas… Potentísimo.
• Etc.

3 Sistema de memorias persistentes con un memory bank

• Guarda decisiones arquitectónicas.
• Recuerda reglas específicas del proyecto.
• Mantiene contexto entre conversaciones.
• Evita repetir explicaciones.

4 Herramientas de productividad

• Búsqueda semántica en el código.
• Planes y TO-DO lists para tareas complejas.
• Ejecución segura de comandos con confirmación del usuario.
• Validación automática con tests.
• Búsqueda avanzada (grep_search) para encontrar patrones de código.
• Integración con MCP servers (Cloud Run,Context7) para documentación actualizada.

5 Capacidades Agentic

• Investigación autónoma. Busca mejores prácticas antes de implementarlas.
• Análisis de dependencias. Entiende el impacto de los cambios (no siempre).
• Refactorización inteligente. Actualiza tests y documentación automáticamente (no siempre lo hace bien).
• Debugging sistemático. Reproduce errores, analiza causas y propone soluciones (esto es una maravilla, resuelve problemas pasándole los logs o introduciendo algunos nuevos de forma automática con gran rapidez).

Modos de trabajo con Cascade

Después de 3 meses trabajando con esta herramienta, he identificado varios modos de interacción con Cascade según la naturaleza de la tarea:

Modo investigación

Este es el modo que utilizo cuando no conozco la mejor solución:

"Investiga cuál es el patrón estándar para manejar refresh tokens en Spring Boot. Explícame las opciones y recomienda una antes de implementar."

Modo implementación

En este caso, lo utilizo para tareas claras y bien definidas:

"Crea un endpoint POST /api/orders que reciba un OrderDTO,valide los datos y guarde el pedido en la BD usando OrderService."

Modo debugging

Este sería el modo de interacción para resolver errores:

"Tengo un error 401 en /api/orders. Stack trace adjunto. Revisa JwtAuthenticationFilter y SecurityConfig."

Modo arquitectura

Para decisiones de diseño:

"Quiero unificar las entidades User y AdminUser. Analiza el impacto, propón una estrategia de migración paso a paso."

Modo aprendizaje

Este modo se puede utilizar para entender código existente:

"Explícame cómo funciona el sistema de refresh tokens que implementamos. ¿Cómo evita la condición de carrera?"

Modo validación

Para después de implementar, le diríamos:

"Ejecuta los tests E2E para verificar que el flujo de checkout funciona correctamente."

¿Qué modelos de IA hemos utilizado?

Una de las características más potentes de Cascade es la posibilidad de elegir entre diferentes modelos de IA según la naturaleza de la tarea. Durante el desarrollo del piloto, he trabajado principalmente con los siguientes modelos:

Gemini Pro 2.5

• Uso principal: uno de mis modelos más utilizados para tareas generales y complejas.
• Fortalezas:
  • Excelente equilibrio entre velocidad y calidad.
  • Muy bueno en comprensión de contexto multilenguaje (español/inglés).
  • Capacidad de razonamiento profundo.
  • Generación de código limpio y bien estructurado.
• Casos de uso: refactorizaciones arquitectónicas, implementación de features complejas, análisis de requisitos.

Claude Sonnet 4

• Uso principal: tareas que requieren máxima precisión y análisis detallado.
• Fortalezas:
  • Excelente para análisis de código existente y arquitectura.
  • Muy preciso en la comprensión de requisitos técnicos.
  • Manejo extremadamente cuidadoso de cambios críticos.
  • Superior en documentación técnica y explicaciones detalladas.
• Casos de uso: revisión de código de seguridad (JWT, autenticación), análisis arquitectónico profundo, refactorización de sistemas complejos (User/AdminUser).

Claude Sonnet 3.7 (Thinking)

• Uso principal: problemas complejos que requieren razonamiento paso a paso.
• Fortalezas:
  • Proceso de "pensamiento" visible y estructurado.
  • Excelente para debugging de problemas difíciles.
  • Análisis metódico de causas raíz.
  • Muy bueno para explorar diferentes enfoques.
• Casos de uso: debugging de condiciones de carrera (refresh tokens), resolución de errores de Kafka, problemas de deserialización.

GPT-5

• Uso principal: tareas de última generación que requieren capacidades avanzadas.
• Fortalezas:
  • Capacidades de razonamiento más avanzadas.
  • Excelente comprensión de contexto complejo.
  • Muy bueno para problemas que requieren creatividad técnica.
  • Generación de código de alta calidad.
• Casos de uso: optimizaciones avanzadas, resolución de problemas inusuales. Es, hasta el momento, el que menos he usado y el que menos me ha convencido.

Claude Sonnet 4.5 (Thinking) y 4.5 ((Nuevo, Octubre ‘25)

En el momento de escribir este artículo lo he probado para una migración de Mappers a Map Struct donde me ha estructurado un plan completísimo, con estimaciones, posibles problemas y soluciones a dichos problemas, ejemplos de código, inyecciones de dependencia, porcentajes de pruebas y número de líneas a refactorizar. Su capacidad para refactorizar, resolver errores y analizar el environment me ha impresionado, es tremendamente potente y la diferencia respecto a modelos anteriores es notable. Este modelo nos va a aportar:

• Razonamiento mejorado: mejor capacidad para problemas complejos multi-paso y planificación estratégica.
• Programación avanzada: mayor precisión en debugging, refactorización y arquitectura de sistemas complejos.
• Seguimiento de instrucciones: mejor adherencia a restricciones y requisitos específicos.
• Contexto largo: manejo más efectivo de grandes codebases y conversaciones extensas.
• Menor tasa de errores: reducción significativa de alucinaciones y errores lógicos.

Observaciones sobre los modelos

Gemini Pro 2.5 como modelo principal:

• Se ha convertido en mi "go-to" para la mayoría de tareas diarias.
• Excelente relación velocidad/calidad.
• Muy versátil para diferentes tipos de problemas.

Familia Claude Sonnet (3.7 y 4):

• Sonnet 4 es mi elección para código crítico y decisiones arquitectónicas importantes.
• Sonnet 3.7 (Thinking) es invaluable cuando necesito "ver" el proceso de razonamiento.
• El modo "Thinking" ha sido especialmente útil para entender por qué ciertas soluciones funcionan.

GPT-5 para casos especiales:

Reservado para problemas que requieren capacidades de última generación (por ser el último modelo que salió en el momento del piloto). No me ha sido de gran utilidad. He hecho 3 o 4 prompts y no me ha dado las respuestas esperadas.

Consistencia entre modelos:

• Todos tienen acceso al mismo sistema de memorias persistentes y del memory-bank.
• El cambio de modelo no afecta al conocimiento acumulado del proyecto.
• A veces pruebo el mismo problema con varios modelos para comparar enfoques.

Uso de planes para la organización del proyecto

Uno de los patrones más efectivos que he desarrollado trabajando con Cascade es el uso sistemático de planes escritos para organizar y documentar el trabajo complejo. Estos planes funcionan como:

• Hojas de ruta para implementaciones grandes.
• Documentación viva del proyecto.
• Punto de referencia para retomar trabajo después de interrupciones.
• Histórico de decisiones arquitectónicas y técnicas.
• No son planes estáticos según los escribamos, son dinámicos, ya que en cada interacción podemos darnos cuenta de que ciertas decisiones no generan lo que nosotros queremos, por tanto lo que le pedimos es que reescriba el plan X con la mejor decisión, incluso marcándole muy bien ciertas restricciones para que no haya alucinaciones.

Estructura de la carpeta plans/

He organizado diferentes planes en mi proyecto categorizados por tipo de plan:

1. Plan general

plans/plan-general.md

En este plan recogemos:

• Visión completa del proyecto.
• Módulos principales (Productos, Checkout, Pagos).
• Tecnologías utilizadas (Java 17, React, PostgreSQL, MongoDB).
• Fases de implementación.
• Estado actual y próximos pasos.

Extracto del plan general:

### Fase 1: Configuración del Proyecto
1. Crear estructura de carpetas del proyecto
2. Configurar entorno de desarrollo
3. Configurar dependencias y herramientas de construcción
4. Configurar conexiones a bases de datos

2. Planes de implementación de módulos

Planes detallados para cada componente del sistema:

• plan-modulo-productos.md - CRUD y gestión del catálogo.
• plan-modulo-checkout.md - Carrito y proceso de compra.
• plan-modulo-pagos.md - Integración con Bizum, Redsys, transferencias.
• plan-modulo-mail-pedido.md - Sistema de notificaciones por email.
• plan-integracion-cart-checkout.md - Integración frontend-backend.
• Patrón típico de estos planes:

## Objetivo
[Descripción clara del módulo]

Arquitectura (3 Capas)
   Capa de Presentación (Controller)
   Capa de Servicio (Service)
   Capa de Persistencia (Repository)

Implementación Detallada
   [Paso a paso técnico]
   Pruebas
   [Estrategia de testing]

3. Planes de refactorización

Documentan cambios arquitectónicos importantes:

• plan_user_unification.md - Unificación de tablas users/admin_users.

Ejemplo de plan de refactorización:

# Plan de Refactorización: Unificación de Usuarios

Fase 1: Análisis y Preparación
  [x] Identificación del Problema
  [x] Decisión Arquitectónica

Fase 2: Refactorización del Backend
  [ ] Modificar entidad User.java
  [ ] Eliminar AdminUser.java
  [ ] Unificar UserDetailsService
  [ ] Actualizar SecurityConfig

Fase 3: Verificación y Pruebas
  [ ] Actualizar pruebas unitarias
  [ ] Ejecutar suite E2E

Fase 4: Limpieza Final
  [ ] Eliminar ficheros obsoletos
  [ ] Actualizar memoria del proyecto

4. Planes de testing

Estrategias completas para diferentes tipos de pruebas:

• e2e_testing_setup.md - Configuración Playwright con Maven.
• plan_gatling_tests.md - Pruebas de carga y performance.

Plan E2E (extracto):

### Fase 1: Aislamiento de Dependencias
1. Perfil Maven (e2e-test) en Backend
   - Excluir spring-kafka y Testcontainers
   - Saltar tests unitarios

### Fase 2: Lanzador de Backend Controlado
   -  Crear InfiniaSportsE2ETestApplication.java
   - Usar SpringApplicationBuilder
   - Forzar perfil e2e-test

### Fase 3: Orquestación del Ciclo de Vida con Maven
   - exec-maven-plugin en playwright-tests
   - pre-integration-test: Iniciar backend y frontend
   - integration-test: Ejecutar tests Playwright
   - post-integration-test: Detener servidores

5. Planes de infraestructura

Configuración de servicios externos y despliegue:

• plan-kafka-carga-productos.md - Integración con Kafka para carga asíncrona.
• plan-despliegue-gcp-cliente.md - Despliegue en Google Cloud Platform.
• plan-despliegue-gcp-gratuito.md - Alternativa con tier gratuito.

6. Planes de frontend

• plan-frontend-react.md - Estructura de componentes React.
• plan-proxy-admin-frontend.md - Configuración de proxy para admin.

7. Planes de documentación

• plan-openapi.md - Especificación OpenAPI 3.0 de la API.

Metodología de trabajo con planes

Vamos a ver paso a paso cómo sería esta metodología de trabajo con los planes.

1. Creación del plan con Cascade cuando enfrento una tarea compleja:

"Vamos a implementar las pruebas E2E con Playwright. 
Antes de empezar, crea un plan detallado en plans/e2e_testing_setup.md 
que incluya fases, dependencias, configuración y estrategia de orquestación."

2. Cascade investiga, propone estructura y crea el documento.
3. Iteración guiada por el plan. El plan se convierte en la guía de trabajo:

"Según el plan en plans/e2e_testing_setup.md, 
implementemos la Fase 1: Aislamiento de Dependencias."

4. Cascade consulta el plan y ejecuta esa fase específica.
5. Actualización del plan durante el desarrollo. A medida que avanzo, actualizo el estado:

"Actualiza plan_user_unification.md: 
marca como completada la Fase 2 y añade notas sobre 
el problema de condición de carrera que encontramos."

6. Planes como memoria del proyecto. Los planes documentan decisiones técnicas importantes.

Ejemplo real (plan-kafka-carga-productos.md):

## 4.1. Persistencia robusta e idempotencia

El DataInitializer asigna un UUID único a cada producto antes de enviarlo a Kafka.

El consumidor (ProductConsumer) convierte el id de String a UUID y antes de guardar comprueba si ya existe (existsById).

Control idempotente: productos no se duplican aunque el flujo se repita.

¿Cuáles son las ventajas de este enfoque?

Podemos extraer 6 ventajas principales:

• Claridad. Siempre sé qué sigue a continuación.
• Trazabilidad. Historial de decisiones técnicas.
• Colaboración. Documentación que otros pueden seguir.
• Recuperación. Fácil retomar después de interrupciones.
• Validación. Checkpoints claros de progreso.
• Aprendizaje. Registro de soluciones a problemas complejos.

Integración con el sistema de memorias de Cascade

Los planes y las memorias se complementan, ya que los planes contienen documentación estructurada y fases de implementación, y las memorias, reglas y decisiones que Cascade debe recordar siempre.

Ejemplo:

• El plan-kafka-carga-productos.md documenta la implementación.
• Una memoria guarda: "El campo id de Product es String generado con uuid2, no UUID nativo".
• Cascade usa la memoria en implementaciones futuras sin consultar el plan cada vez. Adicionalmente, le pedimos que lo almacene en el memory-bank. De esa manera, siempre vamos a tener una memoria en la herramienta y otra persistida.

Conclusión

Cascade de Windsurf no nos sustituye como desarrolladores/as, nos da un entorno de trabajo completo, sincronizado, con capacidad para ayudarte en momentos claves del diseño y del desarrollo.

También nos aumenta nuestra productividad, que he estimado entre un 80%-100%. Por tanto, creo que aunque es una herramienta que no es perfecta y nos obliga a pilotar la nave, hoy en día es imprescindible para aumentar nuestra productividad. ¿La has probado? Te leo en comentarios.