# Anatomía de CLAUDE.md

Imagina que [**CLAUDE.md**](http://CLAUDE.md) es el **manual de instrucciones definitivo** de tu proyecto de programación. Está diseñado específicamente para que una Inteligencia Artificial (o un programador nuevo que se sume al equipo) lo lea y entienda **exactamente cómo trabajar en tu proyecto sin cometer errores**.

Aquí tienes el resumen de las 7 cosas que debe tener este manual:

### 1\. Comandos de Compilación (Build Commands)

*   **¿Qué es?** Los "botones" que hay que presionar para que el código funcione y comprobar que no esté roto.
    
*   **En sencillo:** Las instrucciones exactas que se escriben en la terminal para arrancar el proyecto.
    

### 2\. Resumen de Arquitectura (Architecture Overview)

*   **¿Qué es?** El mapa del tesoro.
    
*   **En sencillo:** Una explicación corta (un par de párrafos) que explica cómo está organizado el proyecto y qué hace cada carpeta principal.
    

### 3\. Patrones Críticos (Critical Patterns)

*   **¿Qué es?** Los "Mandamientos" del proyecto.
    
*   **En sencillo:** Una lista de 5 a 10 cosas que **obligatoriamente** se deben hacer siempre que se escriba código nuevo para mantener el orden.
    

### 4\. Antipatrones (Anti-Patterns)

*   **¿Qué es?** Las "Líneas Rojas".
    
*   **En sencillo:** Lo opuesto a lo anterior. Una lista de 5 a 10 cosas que **están prohibidas** porque rompen el sistema o vuelven el código un caos.
    

### 5\. Flujo de Trabajo de Git (Git Workflow)

*   **¿Qué es?** Las reglas de convivencia del equipo.
    
*   **En sencillo:** Cómo se deben registrar los cambios, qué nombres ponerle a las carpetas de trabajo (ramas) y cómo pedir permiso para fusionar tu código con el de los demás.
    

### 6\. Requisitos de Prueba (Testing Requirements)

*   **¿Qué es?** El control de calidad.
    
*   **En sencillo:** Qué herramientas se usan para probar que el código funciona y qué porcentaje del proyecto debe estar vigilado por estas pruebas automáticas (por ejemplo, el 80%).
    

### 7\. Errores Comunes (Common Pitfalls)

*   **¿Qué es?** El muro de los lamentos (y aprendizajes).
    
*   **En sencillo:** Una lista de metidas de pata que ya ocurrieron en el pasado para que la IA (o tú) no las vuelva a repetir.
    

💡 **La regla de oro de la imagen:** Ese documento no debe ser una enciclopedia gigante. Debe ser directo al grano, idealmente con una extensión de **500 a 1,000 líneas de texto**. Así, cualquier IA lo lee en un segundo y programa exactamente como tú quieres.

## Ejemplo de [`CLAUDE.md`](http://CLAUDE.md) (Stack: Perú Corporativo)

### 1\. Comandos de Compilación (Build Commands)

*   **Backend (Spring Boot):**
    
    *   Levantar en desarrollo: `./mvnw spring-boot:run -`[`Dspring-boot.run`](http://Dspring-boot.run)`.profiles=dev`
        
    *   Ejecutar pruebas: `./mvnw clean test`
        
    *   Construir JAR: `./mvnw clean package -DskipTests`
        
*   **Frontend (Angular):**
    
    *   Instalar dependencias: `npm install`
        
    *   Levantar en desarrollo: `ng serve`
        
    *   Construir producción: `ng build --configuration production`
        

### 2\. Resumen de Arquitectura (Architecture Overview)

El proyecto es un sistema monolítico modular con backend y frontend separados.

*   `/backend`: Proyecto Java 25 estructurado bajo **Arquitectura Limpia (Clean Architecture)**. Capas: `domain` (reglas de negocio), `application` (casos de uso) e `infrastructure` (controladores REST, entidades JPA de PostgreSQL).
    
*   `/frontend`: Aplicación Angular estructurada por módulos funcionales (`auth`, `dashboard`, `shared`). Usamos **Standalone Components** y servicios reactivos con `RxJS`.
    

### 3\. Patrones Críticos (Critical Patterns)

*   **Java 25:** Usar siempre **Virtual Threads** (`Executors.newVirtualThreadPerTaskExecutor()`) para tareas asíncronas y procesamiento de reportes pesados.
    
*   **Spring Boot 4:** Toda inyección de dependencias debe ser por **constructor** usando Lombok (`@RequiredArgsConstructor`). Prohibido usar `@Autowired` en atributos.
    
*   **Angular:** El manejo de estados locales debe hacerse mediante **Signals** en lugar de `BehaviorSubject` tradicionales.
    
*   **PostgreSQL:** Usar `UUID` como llave primaria en lugar de IDs secuenciales para las tablas de transacciones financieras.
    

### 4\. Antipatrones (Anti-Patterns)

*   **NUNCA** uses `@CrossOrigin("*")` en los controladores de Spring Boot; la configuración de CORS se maneja centralizada en [`SecurityConfig.java`](http://SecurityConfig.java).
    
*   **NUNCA** realices consultas a la base de datos dentro de un bucle `for` (problema de consulta $N+1$). Usa `JOIN FETCH` en los repositorios de Spring Data JPA.
    
*   **NUNCA** hagas un `.subscribe()` manual en los componentes de Angular si puedes usar el pipe `async` o `toSignal` en el HTML. Evita fugas de memoria.
    

### 5\. Flujo de Trabajo de Git (Git Workflow)

*   **Ramas:** Usar GitFlow simplificado. Ramas principales: `main` (producción) y `develop` (desarrollo). Las tareas se crean como `feature/TICKET-descripcion` (ej. `feature/PE-102-login-biometrico`).
    
*   **Commits:** Seguir la convención *Conventional Commits*: `feat(backend): agregar endpoint de consulta de RUC` o `fix(frontend): corregir paginación en tabla de clientes`.
    
*   **PRs:** Todo Pull Request requiere la aprobación de al menos 1 Tech Lead antes de mezclarse a `develop`.
    

### 6\. Requisitos de Prueba (Testing Requirements)

*   **Backend:** Mínimo **80% de cobertura** de código en la capa de aplicación usando **JUnit 5** y **Mockito**. Las pruebas de integración con PostgreSQL deben usar **Testcontainers**.
    
*   **Frontend:** Pruebas unitarias para componentes críticos usando **Jasmine/Karma**. Cobertura mínima del 75%.
    

### 7\. Errores Comunes (Common Pitfalls)

*   **Error de Zona Horaria:** PostgreSQL está configurado en UTC. Al guardar fechas en Java, usa siempre `OffsetDateTime` o `Instant`. No uses `LocalDateTime`, ya que trunca la zona horaria de Perú (PET / UTC-5).
    
*   **Bloqueos de Base de Datos:** Las transacciones largas en Spring Boot con `@Transactional` suelen bloquear las tablas de facturación. Mantén los métodos transaccionales lo más cortos posible.
    

### ¿Por qué esto le cambia la vida a una IA (o a un dev nuevo)?

Si dejas este archivo en la raíz de tu repositorio, la IA ya no intentará sugerirte código antiguo de Java 8 o Angular 12. Sabrá de inmediato que estás usando lo último (Java 25, Angular moderno con Signals), que no debe usar `@Autowired`, y que si va a probar la base de datos, tiene que usar Testcontainers.

Enjoy!

Joe