Pensé que estaba usando IA para programar.
En realidad solo estaba escribiendo más rápido.
Esta es la diferencia — y el sistema de 7 agentes que lo cambió todo.
Guarda esto. Te ahorrará meses.
EL PROBLEMA DEL QUE NADIE HABLA
El ciclo 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 → Lo parchea → Algo más se rompe → Vuelves a pedir
Día 1: esto se siente como magia.
Día 30: pasas más tiempo supervisando a la IA del que antes pasabas escribiendo código.
La misma lógica aparece en 3 lugares distintos.
Claude olvidó la convención que estableciste hace dos semanas.
Las funciones nuevas rompen las viejas.
Las pruebas faltan o son superficiales.
Te despiertas y te das cuenta: la IA no está fallando.
Tu flujo de trabajo sí.
El verdadero problema es estructural.
Cuando escribes "construye esta función" en Claude Code, le pides a una sola sesión de IA que sea:
→ Analista de producto → Arquitecto → Ingeniero backend → Ingeniero frontend → Ingeniero de pruebas → Revisor de código
Todo al mismo tiempo.
En la misma conversación desordenada.
Las suposiciones equivocadas en el plan se convierten en modelos de base de datos equivocados.
Los modelos de base de datos equivocados se convierten en APIs equivocadas.
Las APIs equivocadas se convierten en interfaces equivocadas.
Para cuando te das cuenta, el error se ha propagado por todas partes.
Esto se llama vibe coding.
Y tiene un techo muy duro.
EL CAMBIO: DE VIBE CODING A UNA FÁBRICA DE SOFTWARE
Lo que realmente lo cambia todo:
Los equipos de ingeniería reales no trabajan en una sola conversación enorme.
Diferentes personas tienen diferentes responsabilidades:
→ Alguien aclara el problema del usuario → Alguien piensa en la arquitectura → Alguien construye la API → Alguien construye la interfaz → Alguien piensa en los casos límite → Alguien revisa
Cuando colapsas 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.
Estos son los siete agentes que lo hacen funcionar.
LOS 7 AGENTES
Agente 1: El Investigador del Código Base
¿El error más grande que cometen los desarrolladores con la IA?
Pedir código como primer movimiento.
La IA acepta el prompt, hace suposiciones para llenar los vacíos y empieza a generar.
Ahí es donde 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 que se escriba una sola línea.
Lo que hace: → Mapea los archivos relevantes y sus roles → Documenta los patrones existentes a seguir → Encuentra funciones similares ya construidas → Señala riesgos (zonas horarias, multiinquilino, lógica de reintentos) → Enumera qué pruebas necesitarán actualizarse
Lo que no puede hacer: → Editar archivos (solo acceso de lectura) → Ejecutar cualquier comando que modifique el estado → Hacer suposiciones — en su lugar, pregunta
Herramientas: Solo Read, Grep y 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 estuviera mal.
Sino porque el problema nunca se definió claramente.
El Redactor de Historias convierte una idea aproximada de función 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 poder [resultado]."
Criterios de aceptación:Afirmaciones que una prueba puede verificar directamente. Camino feliz. Caminos de error. 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 Read.
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 sigue cada agente constructor.
Entrada que recibe: → Tu historia de usuario aprobada → Los hallazgos del Investigador → Las reglas de CLAUDE.md de tu proyecto
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 — en su lugar, lo señala explícitamente → Omitir preocupaciones de aislamiento de inquilinos o zonas horarias → Dejar preguntas sin respuesta
Herramientas: Solo Read, Grep y Glob.
La regla: este informe es el segundo punto de control humano.
Lo lees y lo apruebas antes de que se toque un solo archivo.
Si ves "guardar IDs en memoria" — esa es tu señal de alerta.
Atrápalo ahora. No después de que se hayan cambiado 10 archivos.
Agente 4: El Constructor Backend
Ahora comienza la construcción.
El Constructor Backend implementa la mitad backend de la función — y solo la mitad 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 agregado o editado → Cada helper o patrón existente reutilizado → Cualquier regla de CLAUDE.md que hubiera ayudado
Herramientas: Read, Edit, Write, Bash — limitado a las carpetas del backend solamente.
La separación es el punto.
El Constructor Backend nunca puede romper accidentalmente el frontend. Nunca.
Agente 5: El Constructor Frontend
El Constructor Frontend implementa la mitad de la interfaz — y solo la mitad de la interfaz.
Primero lee el resumen del Constructor 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 la 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 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 → Agregar dependencias sin instrucción → Detenerse sin ejecutar typecheck, lint y el conjunto de pruebas
Herramientas: Read, Edit, Write, Bash — limitado a las carpetas del frontend solamente.
Dos constructores.
Dos ventanas de contexto limpias.
Cero probabilidad 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 dice que debería hacer.
Escribe pruebas de aceptación.
No pruebas unitarias.
Pruebas de aceptación.
Estas prueban la función desde el exterior — de la manera en que un usuario real la experimentaría.
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 del 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 con 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 las pruebas de aceptación pasen.
Agente 7: El Validador de Implementación
Este es el agente que atrapa 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 brechas.
Nunca arregla nada.
Solo dice la verdad.
Cada verificación que ejecuta, cada vez:
→ Criterios de aceptación de la historia aún no implementados → Caminos de error sin cobertura de prueba → Problemas de seguridad: verificaciones de autenticación faltantes, brechas de aislamiento de inquilinos, secretos en registros, errores sin procesar expuestos a los clientes → Archivos cambiados 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 y Glob.
Este agente es la razón por la que la fábrica es confiable.
Un trabajo auto calificado no vale nada.
Un validador que ve solo 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 impagas por 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.(Atrapa aquí el error de "guardar IDs en memoria".)
Paso 4 → Constructor 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 Frontend lee el resumen de la API del Constructor 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 verifica la propiedad del inquilino.
Paso 7 → Validador lo encuentra. Lo reporta como Crítico con la ruta del archivo y el número de línea.
→ Bucle de vuelta al Constructor 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, comienza con memoria cero.
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 delgadas.") → Qué no hacer ("No agregues cron — usa BullMQ. No registres cargas útiles de pago en bruto.") → Referencias 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 habría evitado esto?
Agrega la regla.
En unas pocas semanas, tu CLAUDE.md se convierte en un registro de cada suposición que la IA se equivocó — y tus sesiones mejoran notablemente.
Desviación de contexto — el asesino silencioso:
La mayoría de las sesiones de Claude Code no fallan de manera dramática.
Se desvían.
Una suposición incorrecta entra en el contexto.
El modelo sigue construyendo sobre ella.
Le pides a Claude que construya gestión de suscripciones.
Él 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 flotando.
Regla:
→ ¿Un pequeño error tipográfico? Corrígelo en el momento. → ¿Una suposición arquitectónica incorrecta? Descarta la conversación y comienza de nuevo con la suposición correcta incluida en el primer prompt.
Una sesión limpia con el modelo mental correcto vence a una sesión parcheada cada vez.
LOS RESULTADOS: LO QUE REALMENTE CAMBIA
Antes de la fábrica:
→ Ciclo de vibe coding: prompt → generar → error → parche → repetir → El contexto de la sesión se llena de ruido → Las suposiciones incorrectas 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: investigar → historia → informe → construir → verificar → validar → Cada agente recibe una ventana de contexto limpia con solo lo que necesita → Las suposiciones incorrectas se detectan en la aprobación del informe — no después de 10 archivos → Un ingeniero entrega un corte vertical completo: backend, frontend, pruebas, validación → El mejor conocimiento del equipo vive en los agentes — no atrapado en las personas
El verdadero cambio:
El especialista en pagos construye un agente de integración de pagos.
Ahora cada ingeniero del equipo puede entregar una función que toque facturación.
Sin esperar.
Sin una transferencia.
Los patrones de componentes del líder de frontend viven en el agente constructor de frontend.
Las verificaciones 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 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 qué 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. Pídele a Claude que la escriba — lee tus 7 archivos de agente y cablea la cadena.
6. Crea la habilidad build-with-tests. Describe cómo construye tu equipo: coincidir con patrones existentes, escribir pruebas junto con el código, ejecutar typecheck al final.
7. Agrega un hook de pre-commit. Bloquea confirmaciones que incluyan archivos .env, .key, .pem o secrets.json. Toma 5 minutos. Previene desastres.
8. Ejecuta una función real a través de toda la cadena. Elige algo pequeño. Observa dónde tropieza. Agrega reglas. La fábrica se ajusta sola.
Tiempo total: 2–3 horas.
Luego ejecuta algunas funciones.
Después de 3 o 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 Backend — construye API, servicios, trabajos, pruebas unitarias (solo carpetas backend) → Constructor Frontend — construye componentes, páginas, hooks, pruebas de interfaz (solo carpetas 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, reporta brechas (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 todavía están haciendo vibe coding.
Prompt → 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 juicio 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 te fue útil:
→ Republica para compartirlo con tu red → Sigue a @sairahul1 para más desgloses como este → Marca esto como favorito — querrás consultar los 7 agentes
Escribo sobre IA, creación de productos y sistemas que funcionan mientras duermes.
