Línea de apertura (opcional, para el feed): Le pediste a Claude que generara un endpoint Spring Boot. Lo hizo con Lombok cuando tu equipo usa records, con javax cuando ya migraron a jakarta, y con un nombre de rama que viola las convenciones del repositorio. El problema no fue el modelo. Fue la falta de contexto.
Parte de la serie "Los 6 pilares del desarrollo asistido por IA" — basado en el material de Thor Henning Hetland (Totto) / Ægis. Adaptado a proyectos Java.
Cuando un desarrollador nuevo entra al equipo, no lo sueltas al codebase sin onboarding. Le explicas la arquitectura, le muestras los patrones que usa el equipo, le dices qué no hacer y por qué. Le enseñas las convenciones de Git, los frameworks de testing, los errores que ya se cometieron.
La IA necesita exactamente lo mismo.
Sin ese contexto, Claude adivina. Y lo hace con confianza: genera código limpio, bien formateado, que compila... y que viola tres convenciones del proyecto, usa el stack equivocado y replica un bug que ya se resolvió hace dos sprints.
El Pilar 1 convierte a la IA en un colaborador que conoce el proyecto. No una herramienta que adivina, sino un miembro del equipo que ha leído el onboarding.
La arquitectura dual del contexto
El contexto inteligente se divide en dos capas complementarias:
CLAUDE.md es la guía universal: vive en la raíz del repositorio, cubre la arquitectura global, el flujo de Git y el enfoque de testing. Es lo primero que Claude lee en cada sesión.
.claude/skills/ son módulos de conocimiento especializado: cada archivo cubre un dominio concreto del proyecto (entidades JPA, diseño de API, convenciones de Spring Boot). Son más cortos (100–300 líneas) y más profundos que el CLAUDE.md.
El plano base: las 7 secciones del CLAUDE.md
El archivo inicial debe tener entre 500 y 1.000 líneas. No más. No menos. Estas son las siete secciones que no pueden faltar, con ejemplos directamente aplicables a un proyecto Spring Boot:
1. Comandos de construcción
Los comandos exactos para compilar, testear y ejecutar. Sin ambigüedad.
## Comandos de construcción
# Compilar
mvn clean compile -q
# Tests unitarios (sin tests de integración)
mvn test -Dgroups="unit"
# Tests de integración (requiere Docker para Testcontainers)
mvn verify -Dgroups="integration"
# Ejecutar localmente con perfil dev
mvn spring-boot:run -Dspring-boot.run.profiles=local
# Linting + checkstyle
mvn checkstyle:check
# Generar la especificación OpenAPI
mvn spring-boot:run & sleep 10 && curl http://localhost:8080/v3/api-docs -o docs/openapi.json
2. Visión general de la arquitectura
200–300 palabras explicando la estructura de paquetes, las capas y las decisiones de diseño clave.
## Arquitectura
Aplicación Spring Boot 3.x con arquitectura hexagonal.
Paquetes principales:
- com.empresa.pedidos.domain → Entidades, Value Objects, puertos
- com.empresa.pedidos.application → Casos de uso, servicios de aplicación
- com.empresa.pedidos.infrastructure → Repositorios JPA, adaptadores HTTP, Kafka
- com.empresa.pedidos.api → Controladores REST, DTOs, mappers
Reglas de dependencia (estrictas):
- domain NO depende de ninguna otra capa
- application depende SOLO de domain
- infrastructure y api dependen de application
Base de datos: PostgreSQL 16 via Spring Data JPA / Hibernate 6
Mensajería: Apache Kafka (Spring Kafka)
Autenticación: Spring Security + JWT
3. Patrones críticos — lo que SIEMPRE se hace
## Patrones críticos
1. SIEMPRE usar `java.math.BigDecimal` para montos monetarios.
Nunca Double, Float, ni int.
2. SIEMPRE usar `jakarta.*` (no `javax.*`). El proyecto está en Spring Boot 3.
3. Los DTOs son Java records inmutables. Nunca clases con setters.
Correcto: public record PedidoDTO(Long id, String numero, BigDecimal monto) {}
4. Los IDs de entidad son Long. Los IDs de API (expuestos) son UUID como String.
5. Todo endpoint REST devuelve ApiResponse<T> del proyecto.
Nunca devolver la entidad JPA directamente.
6. SIEMPRE incluir @Operation y @Parameter de OpenAPI 3 en los controladores.
7. Los mappers entre entidad y DTO usan MapStruct (ya configurado).
4. Anti-patrones — lo que NUNCA se hace
## Anti-patrones
1. NUNCA usar @Autowired en campos. Usar inyección por constructor siempre.
2. NUNCA hacer consultas JPA en el controlador o el DTO.
Las queries van en el repositorio o en el caso de uso.
3. NUNCA lanzar Exception genérica. Usar las excepciones del dominio:
PedidoNotFoundException, MontoInvalidoException, etc.
4. NUNCA usar Optional<T> como parámetro de método.
Solo como valor de retorno.
5. NUNCA hacer commit en main/develop directamente. Todo via PR.
6. NUNCA usar String para representar estados. Usar el enum EstadoPedido.
7. NUNCA usar Lombok en código nuevo. El proyecto migró a records y
constructores explícitos. Lombok solo existe en código legado no migrado.
5. Flujo de Git
## Flujo de Git
Naming de ramas:
- feat/JIRA-123-descripcion-corta
- fix/JIRA-456-nombre-del-bug
- chore/actualizacion-dependencias
Commits (Conventional Commits):
- feat(pedidos): agregar endpoint de cancelación
- fix(pagos): corregir cálculo de IVA con BigDecimal
- test(pedidos): agregar round-trip test para PedidoDTO
PRs:
- Mínimo 1 reviewer de otro squad
- CI debe estar verde (tests + checkstyle + coverage ≥80%)
- El título del PR sigue el mismo formato que los commits
6. Requisitos de testing
## Testing
Framework: JUnit 5 + AssertJ + Mockito
Cobertura mínima: 80% en clases de dominio y aplicación
Reglas:
- Tests unitarios: sin Spring context, sin base de datos
- Tests de integración: Testcontainers (PostgreSQL + Kafka)
- Todo DTO nuevo tiene test round-trip con Jackson
- El directorio src/test/resources/corpus/ contiene 5+ JSONs reales anonimizados
Nombrado:
- PedidoServiceTest → tests unitarios
- PedidoControllerIT → tests de integración
- PedidoDTORoundTripTest → tests de serialización
7. Errores comunes del equipo
Esta sección es oro puro: los bugs reales que ya ocurrieron y que la IA no debe repetir.
## Errores comunes (aprende de estos)
BUG-2024-01: Campo 'clienteId' desalineado en PedidoDTO
Causa: La IA añadió un campo 'referencia' que no estaba en el spec OpenAPI.
Solución aplicada: Round-trip test contra corpus real.
Regla: Todo DTO nuevo requiere test round-trip ANTES del merge.
BUG-2024-02: Double en lugar de BigDecimal para monto
Causa: La IA usó Double por defecto para campos numéricos.
Detectado en: cálculo de totales con pérdida de precisión.
Regla: Siempre BigDecimal para montos (ver Patrones Críticos #1).
BUG-2024-03: javax.persistence en Spring Boot 3
Causa: La IA usó javax.* por ser más común en sus datos de entrenamiento.
Regla: Siempre jakarta.* (ver Patrones Críticos #2).
Las 4 skills de alto impacto para empezar
No intentes construir 50 skills el primer día. Empieza con estas cuatro (15–30 minutos cada una):
Cada skill sigue la misma estructura:
Propósito (1 párrafo — qué resuelve este módulo)
Reglas con ejemplos de ✅ Correcto vs ❌ Incorrecto
Checklist de verificación al final
El efecto compuesto: de 2 horas a 20 minutos
El contexto no es un costo puntual. Es una inversión con retorno compuesto:
Los números de proyectos reales:
90% de reducción en errores de la IA
7.5 horas ahorradas en la generación de 15 parsers similares
Ciclo de revisión de PR de 2–3 días → 4–6 horas
60–70% menos uso de modelos costosos (Haiku hace lo que antes requería Sonnet)
El bucle de aprendizaje continuo
El contexto se vuelve más inteligente con cada ciclo de desarrollo, siempre que se actualice sistemáticamente:
La regla de mantenimiento es simple: después de cada bug de IA, actualizas el contexto antes de cerrar el ticket. En menos de 15 minutos. El mismo bug no vuelve a ocurrir.
Cronograma de implementación
| Cuándo |
Qué hacer |
Tiempo |
| Hoy |
CLAUDE.md básico (7 secciones) + 5 skills iniciales |
5h |
| Esta semana |
Ejecutar contra tareas reales, registrar errores, actualizar contexto |
30 min/día |
| Este mes |
Expandir a 10–15 skills; medir tiempo por tarea |
- |
| Este trimestre |
30–50 skills; contexto en onboarding del equipo |
- |
Para empezar hoy en un proyecto Spring Boot existente, los comandos son los de menos. Lo que cambia el juego son las secciones de Anti-patrones y Errores Comunes: ahí está el conocimiento del equipo que la IA normalmente nunca tiene.
Las métricas que indican que el contexto está funcionando
| Métrica |
Qué medir |
Señal de éxito |
| Precisión al primer intento |
¿Cuántos prompts necesitas antes de que el código sea usable? |
De 3–4 iteraciones a 1 |
| Adherencia a patrones |
¿La IA sigue las convenciones sin que se las recuerdes? |
javax.* desaparece de los PRs |
| Repetición de errores |
¿El mismo tipo de bug aparece dos veces? |
Bugs registrados en CLAUDE.md no vuelven |
| Ahorro de tiempo |
Minutos por tarea con vs. sin contexto |
Reducción medible en el sprint |
| Consistencia del equipo |
¿El código de Dev A y Dev B se ve igual? |
Menos comentarios de estilo en PRs |
Por qué este pilar habilita los otros dos
El Pilar 2 (delegación estratégica) dice: usa Haiku 4.5 para el 60–70% de las tareas de seguir patrones. Pero Haiku sin contexto no puede seguir tus patrones: los desconoce. Con un CLAUDE.md sólido y las skills del dominio, Haiku 4.5 genera código que sigue tus convenciones Java, usa el stack correcto y evita los anti-patrones conocidos del equipo.
El Pilar 3 (verificación) dice: todo DTO nuevo necesita round-trip test. Pero si esa regla no está en CLAUDE.md, la IA no la aplica por defecto. El contexto convierte las reglas de verificación en comportamiento automático.
Los tres pilares se sostienen mutuamente. El Pilar 1 es la base.
¿Tu proyecto Java ya tiene un CLAUDE.md? ¿Qué secciones tienes y cuáles te faltan? Cuéntame en los comentarios.
Enjoy!
Joe
