Guía de Cascade AI: desarrolla en Java con reglas, modo chat y modo code.

Cascade AI es un asistente de desarrollo impulsado por inteligencia artificial, diseñado específicamente para garantizar la creación de código Java impecable y consistente. Su característica principal es un sofisticado sistema de reglas jerárquico que guía cada línea de código generada.

Este sistema combina de forma inteligente las mejores prácticas globales de la industria para tecnologías como Spring Boot (definidas en archivos .md) con directrices personalizadas y de máxima prioridad específicas para cada proyecto (en archivos .mdc).

Esta dualidad permite que el asistente aplique patrones de arquitectura robustos, como la inyección de dependencias por constructor, al mismo tiempo que respeta normas internas del equipo, como escribir comentarios exclusivamente en español.

Para adaptarse a las distintas fases del desarrollo, Cascade ofrece dos modos de trabajo complementarios:

• Modo chat: ideal para un pair programming conversacional, enfocado en resolver tareas complejas, tomar decisiones de arquitectura y realizar depuraciones profundas.
• Modo code: funciona como un asistente de autocompletado inteligente que agiliza la escritura de código repetitivo y la aplicación de cambios localizados de forma instantánea.

En resumen, esta guía presenta a Cascade AI como una solución integral que fusiona un potente motor de reglas personalizables con modos de interacción flexibles, asegurando que cada proyecto no solo sea funcional, sino también mantenible, escalable y coherente con los más altos estándares de calidad.

Reglas (Rules)

Cascade utiliza un sistema de reglas multinivel para guiar la generación de código. Es fundamental entender la diferencia entre los tipos de archivos de reglas:

1. Archivos .md (Markdown estándar)

• Propósito: reglas globales que aplican a un lenguaje o tecnología específica.
• Ubicación: .windsurf/cascade/rules/ (ej: java.md, react.md).
• Alcance: se aplican automáticamente cuando Cascade detecta código en ese lenguaje.
• Contenido: mejores prácticas, patrones estándar de la industria, convenciones generales.

Ejemplo: el fichero java.md contiene las mejores prácticas de Java/Spring Boot que Cascade aplica automáticamente en cualquier proyecto Java.

2. Archivos .mdc (Markdown Cascade)

• Propósito: reglas específicas del proyecto actual.
• Ubicación: .windsurf/rules/ (ej: projectRules.mdc).
• Alcance: se aplican solo a este proyecto y tienen prioridad sobre las reglas .md.
• Contenido: convenciones personalizadas, arquitectura específica, flujos de trabajo del equipo.

Ejemplo: el fichero projectRules.mdc define que los comentarios deben estar en español, que se mantenga homogeneidad en el código, no introducir “*” en las importaciones, inyección de dependencias por constructor etc.. Es decir, defino reglas generales, de convención de código, preferencias de desarrollo, de flujo de trabajo (como planificar antes de implementar, guardar en el memory-bank tras cambios significativos).

Estas reglas deben de ser congruentes con las que definamos a nivel global para que no haya conflictos ya que, aunque hay una jerarquía, esta herramienta también comete errores y debemos de evitarlos en la medida de lo posible

Jerarquía de aplicación

• Prioridad 1. Reglas .mdc del proyecto (máxima prioridad).
• Prioridad 2. Reglas .md globales del lenguaje.
• Prioridad 3. Memorias persistentes del proyecto.
• Prioridad 4. Conocimiento base del modelo de IA.

Caso práctico

Por un lado, java.md dice: "Usar constructor injection para DI". Por otro, projectRules.mdc dice: "Comentarios en español". ¿Cuál es el resultado? Cascade genera código con constructor injection con comentarios en español.

Mejores prácticas de Java/Spring Boot aplicadas

Cascade tiene integrado un conjunto completo de mejores prácticas de Spring Boot, definidas en java.md, que aplica automáticamente en el proyecto. Estas son las reglas que marcamos en el fichero:

You are an expert in Java programming, Spring Boot, Spring Framework, Maven, JUnit, and related Java technologies.

Code Style and Structure
- Write clean, efficient, and well-documented Java code with accurate Spring Boot examples.
- Use Spring Boot best practices and conventions throughout your code.
- Implement RESTful API design patterns when creating web services.
- Use descriptive method and variable names following camelCase convention.
- Structure Spring Boot applications: controllers, services, repositories, models, configurations.

Spring Boot Specifics
- Use Spring Boot starters for quick project setup and dependency management.
- Implement proper use of annotations (e.g., @SpringBootApplication, @RestController, @Service).
- Utilize Spring Boot's auto-configuration features effectively.
- Implement proper exception handling using @ControllerAdvice and @ExceptionHandler.

Naming Conventions
- Use PascalCase for class names (e.g., UserController, OrderService).
- Use camelCase for method and variable names (e.g., findUserById, isOrderValid).
- Use ALL_CAPS for constants (e.g., MAX_RETRY_ATTEMPTS, DEFAULT_PAGE_SIZE).

Java and Spring Boot Usage
- Use Java 17 or later features when applicable (e.g., records, sealed classes, pattern matching).
- Leverage Spring Boot 3.x features and best practices.
- Use Spring Data JPA for database operations when applicable.
- Implement proper validation using Bean Validation (e.g., @Valid, custom validators).

Configuration and Properties
- Use application.properties or application.yml for configuration.
- Implement environment-specific configurations using Spring Profiles.
- Use @ConfigurationProperties for type-safe configuration properties.

Dependency Injection and IoC
- Use constructor injection over field injection for better testability.
- Leverage Spring's IoC container for managing bean lifecycles.

Testing
- Write unit tests using JUnit 5 and Spring Boot Test.
- Use MockMvc for testing web layers.
- Implement integration tests using @SpringBootTest.
- Use @DataJpaTest for repository layer tests.

Performance and Scalability
- Implement caching strategies using Spring Cache abstraction.
- Use async processing with @Async for non-blocking operations.
- Implement proper database indexing and query optimization.

Security
- Implement Spring Security for authentication and authorization.
- Use proper password encoding (e.g., BCrypt).
- Implement CORS configuration when necessary.

Logging and Monitoring
- Use SLF4J with Logback for logging.
- Implement proper log levels (ERROR, WARN, INFO, DEBUG).
- Use Spring Boot Actuator for application monitoring and metrics.

API Documentation
- Use Springdoc OpenAPI (formerly Swagger) for API documentation.

Data Access and ORM
- Use Spring Data JPA for database operations.
- Implement proper entity relationships and cascading.
- Use database migrations with tools like Flyway or Liquibase.

Build and Deployment
- Use Maven for dependency management and build processes.
- Implement proper profiles for different environments (dev, test, prod).
- Use Docker for containerization if applicable.

Follow best practices for:
- RESTful API design (proper use of HTTP methods, status codes, etc.).
- Microservices architecture (if applicable).
- Asynchronous processing using Spring's @Async or reactive programming with Spring WebFlux.

Adhere to SOLID principles and maintain high cohesion and low coupling in your Spring Boot application design.

En base a esto, ¿cómo interpreta Cascade estas reglas?

Estructura y arquitectura

Cascade organiza el código siguiendo patrones de Spring Boot:

// ✅ Estructura de 3 capas generada automáticamente
@RestController
@RequestMapping("/api/orders")
public class OrderController {
    // Constructor injection (mejor práctica)
    private final OrderService orderService;


    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }
}

@Service
public class OrderServiceImpl implements OrderService {
    private final OrderRepository orderRepository;


    public OrderServiceImpl(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }
}

Convenciones de nomenclatura

• Clases: PascalCase → UserController, OrderService, ProductRepository
• Métodos/variables: camelCase → findUserById, calculateTotal, isOrderValid
• Constantes: ALL_CAPS → MAX_RETRY_ATTEMPTS, DEFAULT_PAGE_SIZE

Spring Boot Specifics

// ✅ Anotaciones apropiadas
@SpringBootApplication
@EnableScheduling
public class InfiniaSportsApplication {
    public static void main(String[] args) {
        SpringApplication.run(InfiniaSportsApplication.class, args);
    }
}

// ✅ Manejo de excepciones centralizado
@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        // ...
    }
}

// ✅ Configuración type-safe
@ConfigurationProperties(prefix = "app.jwt")
public class JwtProperties {
    private String secret;
    private long expiration;
    // getters/setters
}

Testing con JUnit 5

// ✅ Test de servicios con @SpringBootTest
@SpringBootTest
class OrderServiceImplTest {
    @Autowired
    private OrderService orderService;

    @MockBean
    private OrderRepository orderRepository;

    @Test
    void shouldCreateOrderSuccessfully() {
        // given - when - then pattern
    }
}

// ✅ Test de controladores con MockMvc
@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private OrderService orderService;

    @Test
    void shouldReturnOrderById() throws Exception {
        mockMvc.perform(get("/api/orders/1"))
               .andExpect(status().isOk());
    }
}

Seguridad con Spring Security

// ✅ Configuración de seguridad robusta
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            );
        return http.build();
    }

    // ✅ Password encoding con BCrypt
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

Persistencia con Spring Data JPA

// ✅ Repositorios con queries personalizadas
public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT o FROM Order o WHERE o.user.email = :email")
    List<Order> findByUserEmail(@Param("email") String email);

    // ✅ Query methods con nomenclatura clara
    Optional<Order> findByOrderIdAndUserEmail(String orderId, String email);
}

// ✅ Entidades con relaciones bien definidas
@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id")
    private User user;
}

Configuración con Profiles

// ✅ Configuración por entorno
// application.properties
spring.profiles.active=dev

// application-dev.properties
spring.datasource.url=jdbc:h2:mem:testdb

// application-prod.properties
spring.datasource.url=jdbc:postgresql://prod-db:5432/infinia

Logging con SLF4J

// ✅ Logging apropiado con niveles correctos
@Slf4j
@Service
public class RefreshTokenService {

    public RefreshToken createRefreshToken(String email) {
        log.info("Creating refresh token for user: {}", email);

        try {
            // logic
            log.debug("Token created successfully");
            return token;
        } catch (Exception e) {
            log.error("Error creating refresh token for user: {}", email, e);
            throw new TokenCreationException("Failed to create token", e);
        }
    }
}

Documentación API con OpenAPI

// ✅ Documentación automática de endpoints
@RestController
@RequestMapping("/api/orders")
@Tag(name = "Orders", description = "API de gestión de pedidos")
public class OrderController {

    @Operation(summary = "Obtener pedido por ID")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Pedido encontrado"),
        @ApiResponse(responseCode = "404", description = "Pedido no encontrado")
    })
    @GetMapping("/{id}")
    public ResponseEntity<OrderDTO> getOrderById(@PathVariable Long id) {
        // implementation
    }
}

Performance y optimización

// ✅ Cacheo estratégico
@Service
@CacheConfig(cacheNames = "products")
public class ProductService {

    @Cacheable(key = "#id")
    public Product findById(String id) {
        return productRepository.findById(id).orElseThrow();
    }
}

// ✅ Procesamiento asíncrono
@Service
public class EmailService {

    @Async
    public CompletableFuture<Void> sendOrderConfirmation(Order order) {
        // send email asynchronously
        return CompletableFuture.completedFuture(null);
    }
}

Reglas específicas del proyecto

Además de las mejores prácticas globales, el proyecto tiene reglas específicas definidas en projectRules.mdc:

Reglas generales

• Comentarios en español: todo el código debe estar comentado en español para asegurar la comprensión de todos los miembros del equipo.
• No realizar cambios no solicitados: cíñete estrictamente a las tareas y requisitos especificados. No introduzcas funcionalidades o modificaciones adicionales.
• Mantener la homogeneidad del código: sigue las convenciones y patrones establecidos en el proyecto para asegurar un estilo consistente.
• Evitar importaciones con asterisco: nunca uses import com.example.*. Importa cada clase de manera específica para mantener la claridad sobre las dependencias.
• Actualización de la documentación: los documentos de planificación (planes) y la base de conocimiento (memory-bank) deben actualizarse después de cada avance significativo.

Convenciones de código

Backend (Java)

• Clases: PascalCase y en inglés (ej. UserService).
• Métodos: camelCase y en inglés (ej. getUserById).
• Variables: camelCase y en inglés (ej. userData).
• Comentarios y JavaDoc: exclusivamente en español.
• Arquitectura: se seguirá un modelo estricto de 3 capas: Controller → Service → Repository.

Frontend (React)

• Componentes: PascalCase y en inglés (ej. UserProfile).
• Funciones y variables: camelCase y en inglés (ej. fetchUserData).
• Comentarios: exclusivamente en español.
• Estilo visual: el diseño debe ser "divertido pero corporativo", equilibrando creatividad con profesionalismo.

Patrones de implementación

• Separación de capas: mantén una clara distinción de responsabilidades entre las capas de la aplicación.
• Validaciones: toda la lógica de validación de datos debe implementarse únicamente en la capa de servicio.
• Manejo de errores: utiliza un manejo de errores consistente, devolviendo los códigos de estado HTTP apropiados (ej. 400 Bad Request, 404 Not Found).
• Documentación de API: todos los endpoints deben estar documentados utilizando la especificación OpenAPI (Swagger).

Filosofía y flujo de trabajo

• Prioridades: la claridad y la mantenibilidad del código son más importantes que la optimización prematura.
• Estructura: dedica tiempo a definir una estructura de proyecto correcta desde el inicio.
• Alcance: implementa solo lo especificado. No añadas funcionalidades "extra" que no han sido solicitadas.
• Metodología:
  • Planifica la solución antes de empezar a programar.
  • Actualiza el Memory Bank después de realizar cambios significativos o descubrimientos importantes

Modos de trabajo: code vs chat

Cascade ofrece dos modos de interacción fundamentales que se adaptan a diferentes necesidades del desarrollo:

Modo chat

Diseñado para pair programming conversacional.

• Características: conversación natural, razonamiento visible, propuestas antes de actuar, iteración flexible y contexto compartido.
• Cuándo usarlo: para tareas complejas, debugging, decisiones arquitectónicas, aprendizaje y refactorizaciones grandes.

Modo code

Modo de autocompletado inteligente y asistencia en línea.

• Características: sugerencias en contexto, completado predictivo, refactorización rápida, generación de código y respuesta inmediata.
• Cuándo usarlo: para autocompletado, generación de código boilerplate (getters/setters, tests simples) y cambios localizados en un solo archivo.

Comparación de los modos

¿Cuál ha sido mi estrategia de uso?

Durante el desarrollo del piloto, he usado mayoritariamente el modo chat para tareas complejas que requerían análisis, aprendizaje y validación de planes. Sin embargo, el modo code lo he utilizado ocasionalmente para completar imports, generar tests repetitivos y escribir DTOs.

Mi recomendación es empezar con el modo chat para establecer la arquitectura y los patrones del proyecto. Una vez consolidado, alternar entre ambos modos según la tarea.

Conclusión

En conclusión, Cascade AI es una herramienta de desarrollo que genera código Java de alta calidad al aplicar un sistema jerárquico de reglas. Combina directrices globales de buenas prácticas para tecnologías como Spring Boot (definidas en archivos .md) con reglas personalizadas y prioritarias específicas del proyecto (en archivos .mdc), como el idioma de los comentarios.

Estas reglas deben de ser congruentes entre sí para ofrecer garantías de que haya los menores errores posibles con lo que definamos. Ofrece dos modos de trabajo complementarios: el modo chat, ideal para tareas complejas de arquitectura y diseño, y el modo code para autocompletado rápido y asistencia en línea. Esta fusión de reglas personalizables y modos de interacción flexibles permite mantener la consistencia y la eficiencia en todo el ciclo de desarrollo de software.