Todo el mundo habla de vibe coding. "Le digo a la IA lo que quiero y me genera el código." Suena genial. Y para un prototipo de fin de semana, funciona.

Pero en producción, con un equipo real, con usuarios reales, con dinero de por medio — el vibe coding puro es una bomba de tiempo. Generas código que nadie entiende, sin tests, sin arquitectura, sin convenciones. Y cuando algo se rompe a las 3am, nadie sabe por qué.

La diferencia entre vibe coding y Vibe Engineering es la misma que entre hackear algo en un hackathon y construir un producto que escala.

Vibe Coding: le tiras un prompt a la IA, copias lo que sale, y rezas.

Vibe Engineering: diseñas un sistema donde la IA es un miembro del equipo con contexto, convenciones, y estructura — y tú diriges.

flowchart LR
    subgraph VC[Vibe Coding]
        v1[Prompt sin contexto] --> v2[IA genera codigo] --> v3[Copiar y pegar] --> v4[Funciona a veces]
    end
    subgraph VE[Vibe Engineering]
        e1[Spec 15 min] --> e2[IA con contexto] --> e3[Review con criterios] --> e4[Deploy con confianza]
    end

Voy a explicar cómo mi equipo usa esto en producción. Con herramientas reales, flujos reales, y resultados reales.

El problema del vibe coding

Vibe coding tiene una reputación mala. Y se la ganó.

El patrón típico: describes lo que quieres, la IA genera código, funciona en el momento, lo shipieas. Dos semanas después el código se vuelve inmantenible. Nadie sabe qué hace. Los tests no existen. Y cada cambio rompe algo que nadie entiende.

¿Por qué pasa esto? Porque la IA no tenía contexto. No sabía tu arquitectura, tus convenciones, ni tu stack. Generó código genérico que resuelve el prompt pero no se integra con tu sistema.

El vibe coding trata a la IA como una caja negra que genera código. Vibe Engineering la trata como un developer que necesita onboarding.

Qué es Vibe Engineering

Vibe Engineering es una metodología de desarrollo donde la IA trabaja como miembro del equipo — con contexto completo del proyecto, convenciones definidas, y estructura clara.

Los tres pilares:

1. Context Engineering — Darle a la IA toda la información que necesita antes de que escriba una línea de código. Arquitectura, convenciones, patrones, decisiones previas.

2. Spec-Driven Development — No le dices "hazme X". Le defines una spec clara: qué construir, por qué, qué constraints tiene, cómo se testea, y qué criterio de aceptación tiene.

3. Human-in-the-Loop — La IA ejecuta, tú diriges. Revisas cada output, tomas las decisiones de arquitectura, y mantienes la visión del producto.

Las herramientas que hacen esto posible

Claude Code — La base

Claude Code es la CLI de Anthropic para desarrollo con IA. No es un autocomplete — es un agente que puede leer tu codebase completo, ejecutar comandos, crear archivos, correr tests, y hacer PRs.

Lo que lo hace diferente de copiar y pegar en ChatGPT:

# No es esto (vibe coding):
# Copiar código → pegar en ChatGPT → copiar respuesta → pegar en VS Code

# Es esto (vibe engineering):
claude
> revisa src/modules/payments/ y proponme cómo refactorizar 
> el checkout para soportar múltiples procesadores.
> Constraints: no romper el flow actual, tests con Vitest, 
> Prisma para DB, errores con neverthrow.

El agente lee los archivos, entiende la arquitectura, y propone una solución que se integra con lo que ya existe. Con contexto.

Subagents y Agent Teams

Claude Code tiene dos formas de paralelizar trabajo:

Subagents — agentes que el agente principal spawna para tareas específicas. Hacen su trabajo y reportan de vuelta. Ideales para tareas independientes: "corre los tests", "revisa la seguridad de este módulo", "formatea todo el proyecto".

> crea subagents para: 1) implementar el PaymentRouter, 
> 2) escribir tests para cada procesador, 
> 3) actualizar la documentación

Agent Teams (experimental) — múltiples instancias de Claude Code que trabajan juntas, se comunican entre sí, y comparten un task list. Útil para features grandes que tocan múltiples capas:

> /team start --size 3
> teammate-1: implementa el backend del checkout
> teammate-2: implementa el frontend del flow
> teammate-3: escribe tests E2E para todo el flow

Los teammates trabajan en paralelo, cada uno en su propio contexto, y se coordinan a través de mensajes. El lead (tú o un agente coordinador) asigna tareas y sintetiza resultados.

SuperClaude — El framework de configuración

SuperClaude es un framework que transforma Claude Code en una plataforma de desarrollo estructurada. 30 comandos, 16 agentes especializados, 7 modos de comportamiento.

# Instalar
pipx install superclaude
superclaude install

# Ahora en Claude Code tienes:
/sc:research      # Investigación profunda sobre un tema
/sc:brainstorm    # Brainstorming estructurado
/sc:implement     # Implementación guiada
/sc:test          # Flujo completo de testing
/sc:code-review   # Review con criterios definidos
/sc:refactor      # Refactoring con patrones
/sc:pm            # Project management

Lo potente de SuperClaude es que trae 16 agentes especializados: un PM, un security engineer, un frontend architect, un debugger. Cuando le pides que revise seguridad, activa el agente de security con su contexto y criterios específicos. No es un prompt genérico — es un especialista.

Además, tiene MCPs (Model Context Protocol servers) opcionales que lo hacen 2-3x más rápido y reducen tokens 30-50%. Serena para entender código, Sequential para razonamiento eficiente, Tavily para búsqueda web.

Get Shit Done (GSD) — Context engineering sin burocracia

Get Shit Done resuelve un problema específico: context rot — la degradación de calidad que pasa cuando Claude llena su ventana de contexto.

# Instalar
npx get-shit-done-cc@latest

# Mapear tu codebase existente
/gsd:map-codebase

# Iniciar un proyecto nuevo con contexto completo
/gsd:new-project

La filosofía de GSD la dice su creador: "No soy una empresa de 50 personas. No quiero sprint ceremonies ni story points ni Jira workflows. Solo quiero construir cosas que funcionen."

¿Cómo funciona?

  1. /gsd:new-project — Te hace preguntas hasta que entiende exactamente qué quieres. Extrae specs, constraints, arquitectura.
  2. Genera un plan — Spec-driven, con tareas claras y criterios de aceptación.
  3. Ejecuta — Claude trabaja con contexto completo del plan, no solo del último prompt.

La complejidad está en el sistema, no en tu workflow. Por debajo hay context engineering, prompt formatting XML, orquestación de subagents, state management. Lo que tú ves: unos pocos comandos que simplemente funcionan.

Lo que me enganchó de GSD: es honesto sobre lo que es. No pretende ser enterprise. Es para personas que quieren describir lo que quieren y que se construya bien. Sin teatro corporativo.

El flujo real en mi equipo

Así trabajamos en BEU/Tikin:

1. Spec primero (humano, 15 min)

## Feature: Multi-procesador checkout

### Qué
- Usuario selecciona método de pago
- Backend rutea al procesador correcto (Stripe/Wompi/Conekta)
- Fallback automático si el primario falla
- Logs unificados en dashboard

### Constraints
- No romper el flow actual de single-processor
- Tests para cada procesador + fallback
- Migration reversible
- TypeScript strict, neverthrow para errores

### Criterio de aceptación
- [ ] Checkout con Stripe funciona
- [ ] Checkout con Wompi funciona  
- [ ] Fallback de Stripe → Wompi funciona
- [ ] Tests pasan (unit + integration)
- [ ] Migration up/down funciona

2. Exploración (agente, 10 min)

El agente lee el codebase, entiende la arquitectura actual, y propone un plan:

Plan propuesto:
1. Crear interfaz ProcessorAdapter
2. Implementar StripeAdapter, WompiAdapter, ConektaAdapter
3. Crear PaymentRouter con FallbackChain
4. Migration: agregar processor_id a payments table
5. Tests: 12 casos (4 por procesador × 3 escenarios)

Archivos a tocar:
- src/modules/payments/adapters/ (nuevo)
- src/modules/payments/router.ts (nuevo)
- src/modules/payments/checkout.ts (modificar)
- prisma/migrations/ (nuevo)
- tests/payments/ (nuevo)

¿Procedo?

3. Implementación (agente, 30-60 min)

"Dale." Y el agente escribe. Archivo por archivo. Puedes ver en tiempo real, interrumpir, redirigir. Si algo no te gusta, le dices y ajusta. No estás esperando 3 días a que un developer termine — estás pair-programming en tiempo real con un agente que no se cansa.

4. Review (humano, 15 min)

Revisas el PR como si lo hubiera hecho un developer nuevo en tu equipo. El código funciona, sigue convenciones, tiene tests. Tú revisas: lógica de negocio, edge cases, seguridad, mantenibilidad.

Total: 1-2 horas para una feature que antes tomaba 3-5 días.

¿Por qué? Porque el 80% del tiempo de desarrollo tradicional se va en:

  • Leer y entender código existente → el agente lo hace en segundos
  • Escribir boilerplate → el agente lo hace solo
  • Debuggear typos y syntax → el agente casi no comete
  • Escribir tests → al agente le encanta escribir tests

Tú te quedas con el 20% que necesita un humano: decisiones de arquitectura, lógica de negocio, y criterio.

Las reglas que nos funcionan

El agente no reemplaza al developer

Si no entiendes el código que el agente escribió, no lo mergees. Punto. No estás haciendo Vibe Engineering — estás generando deuda técnica a velocidad de la luz.

Contexto > Prompts

Un prompt de una línea con buen contexto genera mejor resultado que un prompt de 500 palabras sin contexto.

# .claude/CONVENTIONS.md
- TypeScript strict mode
- Errores con neverthrow (no throw)
- Tests: Vitest + Testing Library
- DB: Prisma, migrations versionadas
- API: tRPC con zod validation
- Naming: camelCase funciones, PascalCase tipos
- Commits: conventional commits

Ese archivo lo lee el agente una vez y aplica en cada interacción. No lo repites nunca.

Reviews más importantes que nunca

Con IA escribiendo más código, el code review humano es más importante, no menos. El agente puede escribir 500 líneas funcionales en 10 minutos. Si no las revisas, puedes mergear una bomba de tiempo.

Documenta decisiones, no código

El agente puede leer código y explicarlo. Lo que necesita saber es por qué tomaste ciertas decisiones. "Elegimos event-driven para pagos porque necesitamos retry automático y auditabilidad" — eso es contexto que cambia todo.

Si puedes shipiear hoy, no lo planees para la próxima semana

Feature pequeña, bien definida, con spec clara → del prompt al PR en una hora. Sin Jira ticket, sin sprint planning, sin esperar al siguiente ciclo.

Los anti-patterns

❌ "Hazme toda la app" — Divide en features, features en tareas, tareas en pasos. La granularidad es tu amiga.

❌ "No voy a leer el código, confío en la IA" — Si no lo revisaste, no lo mergees. Tú eres responsable de lo que se shipea.

❌ Sprints de 2 semanas para tasks de 2 horas — Si la IA lo puede ejecutar hoy, no lo metas en el backlog.

❌ Un prompt para todo — Un bug fix es diferente a un refactor es diferente a una feature nueva. Adapta el approach.

❌ Ignorar los tests del agente — Tests que pasan pero no testean nada útil son peor que no tener tests. Verificá qué están testeando.

La filosofía: Get Shit Done

Hay demasiado teatro en el desarrollo de software moderno. Sprint ceremonies que no generan valor. Story points que nadie calibra bien. Retrospectivas donde todos dicen que "la comunicación podría mejorar" y nada cambia.

Vibe Engineering no es anti-proceso. Es anti-proceso innecesario. El proceso debe ser proporcional a la complejidad de la tarea.

¿Feature compleja con implicaciones de arquitectura? Merece diseño, discusión, y un plan serio. Incluso ahí, la IA acelera cada paso.

¿Bug fix claro? ¿CRUD estándar? ¿Refactor mecánico? Del prompt al PR. Sin intermediarios.

La pregunta que me hago antes de cada tarea: ¿esto necesita una reunión o necesita una spec de 10 líneas y un agente que ejecute?

El 80% de las veces, es lo segundo.

Resultados

Desde que adoptamos este approach en BEU:

  • Tiempo promedio de feature: de 5 días a 1-2 días
  • PRs por semana: se triplicaron
  • Bugs en producción: se mantuvieron (no subieron, que era el miedo)
  • Tiempo del developer: menos boilerplate, más arquitectura y producto

El developer ya no pasa 6 horas escribiendo un CRUD. Pasa 30 minutos revisando un CRUD y 5 horas diseñando la feature del mes que viene.

Eso es Vibe Engineering. No es magia. No es "la IA hace todo". Es redistribuir el tiempo humano hacia donde realmente importa.

Cómo empezar mañana

  1. Instala Claude Code → npm install -g @anthropic-ai/claude-code
  2. Escribe un CONVENTIONS.md de tu proyecto → 20 líneas bastan
  3. Opcionalmente: instala SuperClaude para los 30 comandos o GSD para context engineering
  4. Elige una feature pequeña pendiente
  5. Escribe la spec en 10 líneas: qué, por qué, constraints, criterio de aceptación
  6. Deja que el agente proponga antes de decidir la implementación
  7. Revisa el output con rigor

No necesitas cambiar todo de una vez. Un dev, una feature, un día. Si funciona — y va a funcionar — el equipo lo adopta solo.

La diferencia entre vibe coding y Vibe Engineering es la diferencia entre un hack y un producto. Los dos usan IA. Uno construye castillos de arena. El otro construye edificios.

Elige bien.