Saber que Claude Code existe y saber usarlo bien son cosas distintas. La diferencia está en los prompts: uno genérico produce respuestas mediocres; uno específico produce trabajo terminado. Esta guía te da los flujos exactos — con los prompts reales — para las cuatro tareas que hacen el 80% del trabajo de desarrollo.
Si aún no has hecho tu primera sesión, ve primero a la guía de primer proyecto. Esta guía asume que ya tienes Claude Code funcionando.
El patrón que funciona en todos los flujos
Antes de los ejemplos, el patrón base. Cada prompt que funciona tiene tres partes:
- Contexto: dónde está el problema o qué estamos tocando.
- Tarea: qué queremos que haga, en concreto.
- Criterio de "listo": cómo sabe Claude (y tú) que terminó bien.
Prompts sin contexto producen suposiciones. Prompts sin criterio de "listo" producen trabajo interminable. Con los tres elementos, la tasa de éxito sube mucho.
Flujo 1: arreglar un bug
El escenario más común. Tienes un error, sabes más o menos dónde está, y quieres que Claude lo encuentre y lo corrija.
Prompt que NO funciona:
Hay un bug en el login. Arréglalo.Prompt que SÍ funciona:
Tengo un bug en el flujo de login. Cuando un usuario intenta iniciar sesión con un email que tiene mayúsculas (ej: Usuario@mail.com), falla con un error 401 aunque la contraseña sea correcta. El backend devuelve "Invalid credentials".
El archivo relevante es src/auth/authService.ts, función validateLogin.
Diagnostica por qué falla y arréglalo. Después corre el test de autenticación con `npm test -- src/auth/auth.test.ts` para confirmar que no rompiste nada.Lo que tiene este prompt: el comportamiento exacto del bug, el caso que lo reproduce, el archivo donde buscar, y la instrucción de verificar. Claude va directo al problema en vez de explorar todo el proyecto.
Si no sabes el archivo exacto, está bien — incluye los síntomas y el error completo y deja que Claude lo busque:
Tengo este error cuando guardo un formulario:
TypeError: Cannot read properties of undefined (reading 'id')
at ProductForm.handleSubmit (src/components/ProductForm.tsx:45)
No sé exactamente por qué pasa. Investiga, propón la causa raíz y arréglala.Flujo 2: agregar una nueva funcionalidad
Aquí es donde Claude Code brilla más si le das suficiente contexto de diseño. El error más común: pedir solo el "qué" sin el "cómo debe integrarse".
Prompt que NO funciona:
Agrega un sistema de notificaciones.Prompt que SÍ funciona:
Quiero agregar notificaciones en tiempo real para que los administradores vean cuando se crea un pedido nuevo.
Contexto:
- Estamos usando Socket.io en el backend (ya instalado en package.json)
- El frontend tiene un componente Navbar en src/components/Navbar.tsx
- Los pedidos se crean en src/services/orderService.ts función createOrder
- El modelo de pedido está en src/models/Order.ts
Qué necesito:
1. Que cuando se llame a createOrder, se emita un evento via Socket.io
2. En el frontend, un badge en el navbar que muestre el número de notificaciones nuevas
3. Al hacer clic en el badge, una lista con los últimos 5 pedidos
No necesita persistencia en base de datos por ahora — solo en memoria mientras la sesión esté activa.
Antes de implementar, dime cómo lo vas a hacer para que lo apruebe.El último párrafo — "antes de implementar, dime cómo" — es muy valioso. Evita que Claude construya algo en la dirección equivocada y tengas que revertir muchos archivos.
Flujo 3: escribir pruebas (tests)
Claude Code es muy bueno escribiendo tests. La clave: darle el contexto de qué framework usa el proyecto y qué nivel de cobertura necesitas.
Prompt base para tests:
Escribe tests unitarios para la función calculateDiscount en src/services/pricingService.ts.
El proyecto usa Jest con ts-jest. Los tests existentes están en src/services/__tests__/ como referencia de cómo están estructurados.
Cubre estos casos:
- Descuento del 10% para clientes con más de 5 pedidos anteriores
- Sin descuento para clientes nuevos
- Descuento máximo del 25% aunque se calcule más
- Que lanza error si el precio base es negativo
Después corre los tests con `npm test -- src/services/__tests__/pricingService.test.ts` para confirmar que pasan.Si quieres tests de integración o end-to-end en vez de unitarios, especifícalo. Claude toma decisiones distintas según el tipo de test.
Para agregar tests a código existente que no tiene ninguno:
El archivo src/utils/dateUtils.ts no tiene ningún test. Lee las funciones que hay ahí y escribe los tests que cubrirían los casos más importantes y los edge cases más probables. Usa Jest, como el resto del proyecto.Flujo 4: entender código ajeno
Llegaste a un proyecto sin documentación, heredaste código de otro desarrollador, o estás revisando un módulo que nadie ha tocado en dos años. Claude Code es excelente para esto.
Para entender un módulo completo:
Lee todos los archivos en src/payments/ y explícame:
1. Qué hace este módulo y cuál es su flujo principal
2. Cómo interactúa con el resto del sistema
3. Qué pasaría si quisiera agregar un nuevo proveedor de pagos
4. Qué partes son frágiles o tienen deuda técnica visiblePara entender una función difícil:
Esta función en src/inventory/stockCalculator.ts es difícil de seguir. Explícamela línea por línea, y al final dime en un párrafo qué hace sin tecnicismos.Para hacer una pregunta antes de cambiar algo:
Antes de que haga cualquier cambio: si cambio el formato de los IDs en la tabla products de integer a UUID, ¿qué otros archivos del proyecto se romperían? Dame la lista completa con el impacto de cada uno.Este último patrón — "antes de que hagas cualquier cambio, analiza el impacto" — es muy útil para operaciones riesgosas. Claude mapea las dependencias antes de tocar nada.
Flujo 5 (bonus): refactorizar sin romper nada
Refactorizar código con Claude Code funciona bien si separas la exploración de la ejecución:
El archivo src/utils/helpers.ts tiene 400 líneas y hace demasiadas cosas distintas. Quiero dividirlo.
Primero, léetelo completo y propón cómo dividirlo en archivos más pequeños con responsabilidades claras. No hagas ningún cambio todavía.Cuando apruebes el plan:
El plan 2 se ve bien. Procede con la refactorización. Al terminar, confirma que no hay imports rotos corriendo `npm run build`.Dividir en dos pasos (planear → ejecutar) evita que Claude empiece a mover archivos en una dirección que luego no te gusta.
Cómo manejar cuando Claude se equivoca
Claude Code comete errores. La forma de corregirlo importa tanto como el prompt inicial. Lo que funciona:
Eso no está bien. El problema es que cambiaste la lógica de validación en la línea 89, pero esa función también la usa el módulo de reportes y ahora fallaría. Revierte solo ese cambio y busca otra manera que no afecte la validación existente.Lo que no funciona: "está mal, arréglalo". Sin decir qué está mal y por qué, Claude puede repetir el mismo error de otra forma.
En resumen
Los cuatro flujos que cubren el 80% del trabajo de desarrollo con Claude Code: arreglar bugs (con el error exacto y el archivo), agregar funcionalidades (con el "antes de implementar, dime cómo"), escribir tests (con el framework y los casos), y entender código ajeno (con preguntas de impacto antes de tocar nada). El denominador común: contexto específico + criterio de "listo" + verificación.
En Aldama usamos exactamente estos flujos en proyectos reales de desarrollo con IA. Si quieres que un equipo que domina estas herramientas construya tu proyecto, lo conversamos. Sin humo. Para sacar aún más provecho, mira las funcionalidades avanzadas de Claude Code.