Creía que estaba usando IA para programar.
En realidad, solo escribía más rápido.
Aquí está la diferencia — y el sistema de 7 agentes que lo cambió todo.
Guarda esto. Te ahorrará meses.
EL PROBLEMA DEL QUE NADIE HABLA
El bucle que se siente productivo pero no lo es:
→ Le pides a Claude que construya una función → Genera código → Algo se rompe → Le pegas el error de vuelta → Lo parchea → Algo más se rompe → Pides otra vez
Día 1: esto se siente como magia.
Día 30: pasas más tiempo supervisando a la IA del que solías pasar escribiendo código.
La misma lógica aparece en 3 sitios distintos.
Claude olvidó la convención que definiste hace dos semanas.
Las funciones nuevas rompen las antiguas.
Las pruebas faltan o son superficiales.
Te despiertas y te das cuenta: la IA no está fallando.
Tu flujo de trabajo sí.
El problema real es estructural.
Cuando escribes "construye esta función" en Claude Code, le estás pidiendo a una sola sesión de IA que sea:
→ Analista de producto → Arquitecto → Ingeniero de backend → Ingeniero de frontend → Ingeniero de pruebas → Revisor de código
Todo a la vez.
En la misma conversación desordenada.
Suposiciones erróneas en el plan se convierten en modelos de base de datos erróneos.
Modelos de base de datos erróneos se convierten en APIs erróneas.
APIs erróneas se convierten en interfaces erróneas.
Cuando te das cuenta, el error se ha extendido por todas partes.
A esto se le llama vibe coding.
Y tiene un techo duro.
EL CAMBIO: DEL VIBE CODING A UNA FÁBRICA DE SOFTWARE
Lo que realmente lo cambia todo:
Los equipos de ingeniería reales no trabajan en una gran conversación.
Personas distintas tienen trabajos distintos:
→ Alguien aclara el problema del usuario → Alguien piensa en la arquitectura → Alguien construye la API → Alguien construye la interfaz → Alguien piensa en casos límite → Alguien revisa
Cuando juntas todo eso en una sola sesión de IA, los errores se acumulan en silencio.
La solución es dividir el trabajo entre agentes especializados.
Cada agente recibe: → Un trabajo enfocado → Su propia ventana de contexto limpia → Solo las herramientas que realmente necesita → Reglas estrictas sobre lo que no puede tocar
El resultado: una fábrica de software.
Un desarrollador + siete agentes enfocados = un equipo coordinado.
Aquí están los siete agentes que lo hacen funcionar.
LOS 7 AGENTES
Agente 1: El Investigador del Código Base
¿El mayor error que cometen los desarrolladores con la IA?
Pedir código como primer paso.
La IA acepta la instrucción, hace suposiciones para llenar los vacíos y empieza a generar.
Ahí es cuando se cuelan los malos diseños.
El Investigador del Código Base soluciona esto.
Su único trabajo: inspeccionar el código base y explicar cómo funcionan las cosas — antes de escribir una sola línea.
Lo que hace: → Mapea los archivos relevantes y sus funciones → Documenta los patrones existentes a seguir → Encuentra funciones similares ya construidas → Señala riesgos (zona horaria, multiinquilino, lógica de reintento) → Enumera qué pruebas habrá que actualizar
Lo que no puede hacer: → Editar archivos (solo acceso de lectura) → Ejecutar cualquier comando que modifique el estado → Hacer suposiciones: pregunta en su lugar
Herramientas: Solo Read, Grep, Glob.
La regla: explora antes de construir, siempre.
El Investigador se ejecuta primero. Siempre.
Agente 2: El Redactor de Historias
La mayoría de las funciones fallan no porque el código fuera incorrecto.
Sino porque el problema nunca se definió claramente.
El Redactor de Historias convierte una idea de función aproximada en una historia de usuario real antes de tomar cualquier decisión técnica.
Entrada que recibe: → Tu descripción aproximada de la función → Los hallazgos del Investigador
Lo que produce:
Una historia de usuario:"Como [rol], quiero [comportamiento], para [resultado]."
Criterios de aceptación:Enunciados que una prueba puede verificar directamente. Camino feliz. Caminos de fallo. Reglas de negocio.
Casos límite:Límites, reintentos, preocupaciones de multiinquilino.
Fuera de alcance:Lo que explícitamente NO se está construyendo.
Preguntas abiertas:Cosas que realmente no sabe — nunca adivina.
Lo que no puede hacer: → Inventar reglas de negocio → Escribir cualquier código o diseño técnico → Avanzar si algo no está claro
Herramientas: Solo lectura.
La regla: lees esta historia y la apruebas antes de que ocurra cualquier otra cosa.
Este es el punto de control humano que salva todo lo que viene después.
Agente 3: El Redactor de Especificaciones
Una vez que la historia está aprobada, el Redactor de Especificaciones la convierte en un informe técnico.
Este es el plano que seguirá cada agente constructor.
Entrada que recibe: → Tu historia de usuario aprobada → Los hallazgos del Investigador → Las reglas de tu proyecto en CLAUDE.md
Lo que produce:
→ Cambios en el modelo de datos (campos, tipos, migraciones) → Flujo de fondo / flujo de proceso → Cambios en la API (endpoints, formas de solicitud/respuesta) → Cambios en el frontend (componentes, páginas, hooks) → Pruebas requeridas (éxito, fallo, casos límite) → Riesgos y preguntas abiertas → Cada archivo que cambiará
Lo que no puede hacer: → Editar ningún archivo → Inventar nueva infraestructura — lo señala explícitamente en su lugar → Omitir preocupaciones de aislamiento de inquilinos o zona horaria → Dejar preguntas sin respuesta
Herramientas: Solo Read, Grep, Glob.
La regla: este informe es el segundo punto de control humano.
Lo lees y lo apruebas antes de tocar un solo archivo.
Si ves "almacenar IDs en memoria" — esa es tu bandera roja.
Captúralo ahora. No después de que se hayan cambiado 10 archivos.
Agente 4: El Constructor de Backend
Ahora comienza la construcción.
El Constructor de Backend implementa la mitad del backend de la función — y solo la mitad del backend.
Entrada que recibe: → Informe técnico aprobado → Hallazgos del Investigador → CLAUDE.md de tu proyecto
Lo que construye: → Rutas de API → Servicios y lógica de negocio → Acceso a base de datos y migraciones → Trabajos en segundo plano → Pruebas unitarias para todo lo que escribe
Lo que no puede hacer: → Tocar componentes de React, páginas o hooks del lado del cliente (eso es del Agente 5) → Inventar nuevas dependencias sin instrucción → Modificar archivos fuera del alcance acordado → Detenerse sin ejecutar typecheck, lint y el conjunto de pruebas
Al terminar, devuelve un resumen: → Cada archivo añadido o editado → Cada helper o patrón existente reutilizado → Cualquier regla de CLAUDE.md que habría sido útil
Herramientas: Read, Edit, Write, Bash — limitado solo a las carpetas de backend.
La separación es la clave.
El Constructor de Backend nunca puede romper el frontend. Nunca.
Agente 5: El Constructor de Frontend
El Constructor de Frontend implementa la mitad de la interfaz — y solo la mitad de la interfaz.
Primero lee el resumen del Constructor de Backend.
Esto es importante.
Consume la API exactamente como la produjo el backend.
No inventa nuevos endpoints.
Si la forma de la API no es adecuada para la interfaz, expone el desajuste como retroalimentación — no como un parche.
Entrada que recibe: → Informe técnico aprobado → Hallazgos del Investigador → Resumen del Constructor de Backend (el contrato de la API)
Lo que construye: → Componentes y páginas de React → Hooks y estado del lado del cliente → Estados de carga y error → Pruebas de componentes y unitarias para todo lo que escribe
Lo que no puede hacer: → Tocar servicios, rutas de API, workers o migraciones (eso es del Agente 4) → Inventar endpoints o formas de respuesta → Añadir dependencias sin instrucción → Detenerse sin ejecutar typecheck, lint y el conjunto de pruebas
Herramientas: Read, Edit, Write, Bash — limitado solo a las carpetas de frontend.
Dos constructores.
Dos ventanas de contexto limpias.
Cero posibilidades de que uno rompa el trabajo del otro.
Agente 6: El Verificador de Pruebas
Ambos constructores escribieron pruebas unitarias para su propio código.
Eso no es suficiente.
El Verificador de Pruebas hace solo una cosa: demostrar que la función realmente hace lo que la historia de usuario decía que debía hacer.
Escribe pruebas de aceptación.
No pruebas unitarias.
Pruebas de aceptación.
Estas prueban la función desde fuera — como la experimentaría un usuario real.
Entrada que recibe: → Historia de usuario aprobada (con todos los criterios de aceptación) → Informe técnico aprobado → Resúmenes de ambos constructores
Lo que produce: → Un archivo de prueba de aceptación que cubre cada criterio de aceptación → Un informe: qué criterios pasaron, cuáles fallaron, cuáles no se pueden cubrir limpiamente
Lo que no puede hacer: → Modificar ningún código de backend o frontend → Inventar soluciones alternativas para criterios no comprobables → Marcar un criterio como cubierto si realmente no lo está
Si una prueba falla: la función no cumple la historia.
Informa exactamente qué criterio falló.
No parchea el código.
Eso vuelve al constructor correspondiente.
Herramientas: Read, Edit, Write (solo archivos de prueba), Bash.
La regla: no tienes una función hasta que pasen las pruebas de aceptación.
Agente 7: El Validador de Implementación
Este es el agente que detecta todo lo que los demás pasaron por alto.
El Validador compara la implementación actual con la historia y el informe aprobados — e informa las diferencias.
Nunca arregla nada.
Solo dice la verdad.
Cada comprobación que ejecuta, cada vez:
→ Criterios de aceptación de la historia aún no implementados → Caminos de fallo sin cobertura de pruebas → Problemas de seguridad: comprobaciones de autenticación faltantes, brechas de aislamiento de inquilinos, secretos en registros, errores sin procesar expuestos a los clientes → Archivos modificados fuera del alcance acordado → Patrones inconsistentes con CLAUDE.md o el código existente → Lógica duplicada que debería reutilizar helpers existentes → Preocupaciones de zona horaria o multiinquilino del informe que se omitieron silenciosamente
La salida siempre se agrupa por gravedad:
Crítico — debe arreglarse antes de fusionar Importante — debería arreglarse antes de fusionar Menor — basado en opinión, decisión del revisor
Cada hallazgo incluye la ruta del archivo y el número de línea.
Si no hay nada malo, lo dice claramente.
No inventa problemas para parecer minucioso.
Herramientas: Solo Read, Grep, Glob.
Este agente es por qué la fábrica es confiable.
Un trabajo autoevaluado no vale nada.
Un validador que solo ve lo que hay en el disco — no cómo se escribió — es honesto.
CÓMO FUNCIONA LA CADENA
El flujo completo — un solo prompt lo inicia todo:
Abres Claude Code y escribes:
"Crea recordatorios de facturas para facturas impagadas desde hace más de 7 días."
Esto es lo que sucede sin que escribas nada más:
Paso 1 → Investigador mapea tu código de facturas, pagos y correos electrónicos. Devuelve archivos relevantes, patrones existentes, riesgos.
Paso 2 → Redactor de Historias produce la historia de usuario y los criterios de aceptación.
⏸ PAUSA: Lees y apruebas la historia.
Paso 3 → Redactor de Especificaciones convierte la historia aprobada en un informe técnico.
⏸ PAUSA: Lees y apruebas el informe.(Detecta ese error de "almacenar IDs en memoria" justo aquí.)
Paso 4 → Constructor de Backend implementa el servicio, la ruta de API, el trabajo de BullMQ y las pruebas unitarias. Devuelve: archivos cambiados, patrones reutilizados, todas las pruebas en verde.
Paso 5 → Constructor de Frontend lee el resumen de la API del Constructor de Backend, construye el mosaico de la interfaz de administración y el botón de recordatorio, escribe pruebas de componentes. Todas las pruebas en verde.
Paso 6 → Verificador de Pruebas escribe pruebas de aceptación para los seis criterios de aceptación. Informa: 7 pasan, 1 falla — el disparador manual no comprueba la propiedad del inquilino.
Paso 7 → Validador lo encuentra. Lo informa como Crítico con la ruta del archivo y el número de línea.
→ Bucle de vuelta al Constructor de Backend. Corrección aplicada. Las 8 pruebas de aceptación pasan. El Validador se ejecuta de nuevo. Limpio.
⏸ PAUSA: Revisas y abres el PR.
Tres puntos de control humanos.
Todo lo demás se ejecuta solo.
LA BASE: ANTES DE QUE LOS AGENTES TRABAJEN, NECESITAS ESTO
CLAUDE.md — la memoria que sobrevive a cada sesión:
Cada vez que abres Claude Code, empieza con cero memoria.
CLAUDE.md soluciona esto.
Es un archivo Markdown en la raíz de tu repositorio que se carga automáticamente en cada sesión.
Ahí es donde viven los datos permanentes del proyecto:
→ Tu stack (Next.js App Router, Node.js, Prisma, BullMQ, Resend) → Tus comandos (npm run dev, npm test, npx prisma migrate dev) → Reglas de arquitectura ("La lógica de negocio vive en los servicios. Las rutas de API se mantienen ligeras.") → Qué no hacer ("No añadas cron — usa BullMQ. No registres cargas de pago en bruto.") → Punteros a documentación más profunda (docs/billing.md, docs/architecture.md)
Mantenlo entre 100 y 300 líneas.
Cada vez que la IA comete un error que te sorprende, pregúntate: ¿una regla en CLAUDE.md lo habría evitado?
Añade la regla.
En unas semanas, tu CLAUDE.md se convierte en un registro de cada suposición que la IA se equivocó — y tus sesiones mejoran notablemente.
Deriva de contexto — el asesino silencioso:
La mayoría de las sesiones de Claude Code no fallan de forma dramática.
Se desvían.
Una suposición errónea entra en el contexto.
El modelo sigue construyendo sobre ella.
Le pides a Claude que construya la gestión de suscripciones.
Diseña: Usuario → Suscripción.
Recuerdas: las suscripciones pertenecen a la empresa, no al usuario.
Si solo dices "no, las suscripciones pertenecen a las empresas" — Claude parchea.
Ahora tienes tanto user.subscriptionId como company.subscriptionId por ahí.
Regla:
→ ¿Un pequeño error tipográfico? Corrígelo en línea. → ¿Una suposición arquitectónica errónea? Descarta la conversación y empieza de nuevo con la suposición correcta incorporada en el primer prompt.
Una sesión limpia con el modelo mental correcto vence a una sesión parcheada siempre.
LOS RESULTADOS: LO QUE REALMENTE CAMBIA
Antes de la fábrica:
→ Bucle de vibe coding: prompt → generar → error → parchear → repetir → El contexto de la sesión se llena de ruido → Las suposiciones erróneas se acumulan en funciones rotas → Un ingeniero solo puede hacer una cosa a la vez → Cada función espera a que la persona adecuada esté disponible
Después de la fábrica:
→ Cadena estructurada: investigación → historia → informe → construir → verificar → validar → Cada agente recibe una ventana de contexto limpia con solo lo que necesita → Las suposiciones erróneas se detectan en la aprobación del informe — no después de 10 archivos → Un ingeniero envía una porción vertical completa: backend, frontend, pruebas, validación → El mejor conocimiento del equipo vive en los agentes — no atrapado en las personas
El cambio real:
El especialista en pagos construye un agente de integración de pagos.
Ahora cualquier ingeniero del equipo puede enviar una función que toque la facturación.
Sin esperar.
Sin una transferencia.
Los patrones de componentes del líder de frontend viven en el agente constructor de frontend.
Las comprobaciones de CI del ingeniero de DevOps viven en un hook.
Los casos límite del líder de control de calidad viven en las reglas del verificador de pruebas.
Conocimiento experto, compartido como agentes.
No atrapado en la disponibilidad.
CÓMO CONSTRUIR EL TUYO ESTE FIN DE SEMANA
Lista de verificación de configuración en 8 pasos:
1. Instala Claude Code → code.claude.com
2. Crea la estructura de carpetas: → .claude/agents/ → .claude/skills/feature-factory/ → .claude/skills/build-with-tests/ → .claude/hooks/
3. Escribe tu CLAUDE.md (100–300 líneas: stack, comandos, reglas de arquitectura, lista de lo que no hacer)
4. Crea los 7 agentes usando el comando /agents en Claude Code. Describe el rol de cada agente. Claude escribe el archivo. Tú revisas y confirmas.
5. Crea la habilidad orquestadora feature-factory. Pide a Claude que la escriba — lee tus 7 archivos de agente y conecta la cadena.
6. Crea la habilidad build-with-tests. Describe cómo construye tu equipo: sigue patrones existentes, escribe pruebas junto al código, ejecuta typecheck al final.
7. Añade un hook previo a la confirmación. Bloquea confirmaciones que incluyan archivos .env, .key, .pem o secrets.json. Tarda 5 minutos. Evita desastres.
8. Ejecuta una función real a través de la cadena completa. Elige algo pequeño. Observa dónde tropieza. Añade reglas. La fábrica se ajusta sola.
Tiempo total: 2–3 horas.
Luego ejecuta algunas funciones.
Después de 3–4, la fábrica conoce tu código base.
Pasarás menos tiempo supervisando.
Más tiempo decidiendo qué construir a continuación.
LOS 7 AGENTES — REFERENCIA RÁPIDA
→ Investigador — mapea el código antes de construir nada (Solo lectura) → Redactor de Historias — convierte una idea en historia de usuario con criterios de aceptación (Solo lectura) → Redactor de Especificaciones — convierte la historia en informe técnico (Solo lectura) → Constructor de Backend — construye API, servicios, trabajos, pruebas unitarias (solo carpetas de backend) → Constructor de Frontend — construye componentes, páginas, hooks, pruebas de interfaz (solo carpetas de frontend) → Verificador de Pruebas — escribe pruebas de aceptación contra la historia de usuario (solo archivos de prueba) → Validador — compara la implementación con la historia y el informe, informa diferencias (Solo lectura)
3 puntos de control humanos:→ Aprueba la historia → Aprueba el informe → Aprueba el PR
Todo lo demás se ejecuta solo.
La mayoría de los desarrolladores que usan Claude Code siguen haciendo vibe coding.
Dar instrucciones → generar → parchear → esperar.
Eso no está mal.
Es solo un techo.
La fábrica no te elimina del proceso.
Te elimina de las partes que no te necesitan.
Te quedas en el bucle donde tu criterio importa:
¿Es este el problema correcto? ¿Es este el diseño correcto? ¿Es seguro enviarlo?
Los agentes manejan todo lo demás.
Esa es la diferencia entre usar la IA como un teclado más rápido —
y usar la IA como un equipo coordinado.
Si esto fue útil:
→ Repostealo para compartirlo con tu red → Sigue a @sairahul1 para más análisis como este → Guárdalo en marcadores — querrás consultar los 7 agentes
Escribo sobre IA, creación de productos y sistemas que funcionan mientras duermes.
