Trabajar con Claude en proyectos reales: del prompt al pull request
El hype sobre IA en desarrollo dice que vas a escribir el 80% del código con prompts. La realidad de los devs senior que la usan bien es más matizada: la IA suma cuando sabés exactamente en qué paso del flujo meterla y cómo verificar lo que produce.
Este post es el flujo que funciona. No el que venden — el que se usa.
El error más común: prompt → copiar → commit
El flujo que no funciona:
- Escribir un prompt grande describiendo toda la feature.
- Copiar el código generado.
- Commitear.
El problema no es la IA — es el tamaño del contexto y la falta de verificación. Un prompt que describe una feature completa produce código que funciona en el vacío pero no encaja con el resto del proyecto: naming distinto, abstracciones que no coinciden, casos edge no cubiertos, dependencias que ya resolviste de otra manera.
El flujo que funciona es granular y verificado.
Paso 1: planificación — Claude como rubber duck con memoria
Antes de escribir código, usá a Claude para pensar el problema en voz alta. No para que te dé la solución — para que te haga las preguntas correctas.
"Necesito implementar un sistema de notificaciones push para usuarios mobile.
El stack es Spring Boot + PostgreSQL + Firebase. Qué preguntas debería
responder antes de escribir una línea de código?"
La respuesta te da un checklist de decisiones: ¿notificaciones síncronas o en cola? ¿qué pasa si Firebase falla? ¿cómo manejás dispositivos múltiples por usuario? ¿retry policy?
Respondé esas preguntas vos. Con ese contexto, el código que generes después va a ser mucho más coherente.
Paso 2: generación por bloques, no por feature completa
La regla: un prompt = una unidad de código que podés leer y verificar en 5 minutos.
En lugar de:
"Implementá el sistema completo de notificaciones push"
Hacés:
"Implementá la entidad DeviceToken con estos campos: userId, token, platform
(ANDROID|IOS), createdAt, lastUsedAt. JPA + PostgreSQL. El proyecto usa
Hibernate y nuestro BaseEntity ya tiene id y timestamps — heredá de él."
Cada bloque tiene scope acotado, se verifica rápido y se integra con contexto real del proyecto.
El orden natural:
- Entidades y DTOs
- Repositorios e interfaces
- Lógica de servicio
- Controller / endpoint
- Tests
Nunca al revés — sin entidades, el service va a inventar la estructura de datos.
Paso 3: dar contexto real, no describir el contexto
El error más frecuente en los prompts es describir el código en lugar de mostrarlo. Describir genera interpretaciones. Mostrar genera coherencia.
En lugar de:
"El proyecto usa repositorios que extienden JpaRepository"
Pegás:
// Esto es nuestro patrón de repositorio:
public interface UserRepository extends JpaRepository<User, Long> {
Optional<User> findByEmail(String email);
List<User> findByStatusAndCreatedAtAfter(UserStatus status, Instant since);
}
// Implementá DeviceTokenRepository siguiendo este mismo patrón.
Claude va a replicar el estilo exacto: naming, tipos, convenciones de método. No va a inventar algo distinto.
Paso 4: review iterativo — el diff es tu herramienta
Cada bloque generado pasa por el mismo proceso antes de integrarse:
Leer el diff completo. No "escanearlo" — leerlo. Buscando activamente el error, no validando que "se ve bien".
Verificar el contrato. ¿Los nombres de métodos, tipos de retorno y parámetros son consistentes con lo que el resto del código va a llamar?
Buscar lo no pedido. ¿El LLM agregó algo que no pediste? Cada adición no solicitada es un riesgo.
Compilar y correr los tests existentes. Si algo rompió, entender por qué antes de parcharlo.
Si algo en el diff no entendés completamente, no lo mergees todavía. Preguntale a Claude que explique ese fragmento específico.
Paso 5: tests — primero describí, después generá
Los tests generados por IA sin guía son superficiales: happy path, mocks que no verifican lo importante, coverage numérico sin cobertura real.
El flujo que funciona:
Primero, describís los casos a cubrir vos:
"Para DeviceTokenService.register(), necesito tests para:
1. Registro exitoso de device nuevo
2. Actualización de lastUsedAt si el token ya existe
3. Rechazo si userId no existe en la base
4. Manejo correcto cuando Firebase devuelve error 401"
Después pedís la implementación de esos tests específicos. La IA implementa — vos definiste qué importa.
Resultado: tests con semántica real, no coverage vacío.
Paso 6: documentación — el único lugar donde el 100% IA está bien
Docstrings, comentarios de clases, README de módulo, descripción de endpoint en OpenAPI: esto es donde la IA agrega valor sin riesgo. El código ya está verificado — la documentación lo describe.
"Generá el Javadoc para estos métodos. El público es otro desarrollador
del equipo que no conoce este módulo. Incluí los casos edge en @throws."
No revisás el código — revisás que la documentación describe con precisión lo que el código hace. Eso es verificable en segundos.
El PR final
Un PR bien armado con este flujo tiene:
- Commits atómicos por bloque (entidad, repositorio, service, controller, tests).
- Cada commit pasó los tests antes de avanzar al siguiente.
- La descripción del PR explica las decisiones de diseño, no solo qué hace el código.
- Sin cambios mezclados — el PR hace una cosa.
La diferencia con un PR generado en modo "copiar todo": el reviewer puede leer commit por commit, entender el razonamiento y hacer preguntas específicas. No tiene que digerir 800 líneas de contexto opaco.
Lo que la IA no reemplaza
- Entender el dominio: la IA genera código para el dominio que le describís. Si la descripción es vaga, el código es vago.
- Decisiones de diseño: cuándo usar eventos vs llamadas síncronas, cómo modelar el dominio, qué va en qué capa. Eso requiere entender el sistema completo.
- Leer el diff con criterio: si no sabés qué buscar en el diff, no podés detectar el error.
La IA es una herramienta de velocidad para el dev que ya sabe qué está construyendo. No es un reemplazo para saber qué construir.
Conclusión
El flujo que funciona no es "prompt grande → copiar → commit". Es granular, verificado y contextualizado: planificación primero, generación por bloques, contexto real en los prompts, review de cada diff, tests con semántica definida por el dev.
Con ese flujo, la IA genuinamente acelera. Sin él, introduce deuda que pagás el doble después.