Anatomía de CLAUDE.md

Imagina que 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 (Stack: Perú Corporativo)

1. Comandos de Compilación (Build Commands)

• Backend (Spring Boot):

  • Levantar en desarrollo: ./mvnw spring-boot:run -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.

• 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