El momento en que el vibe coding dejó de escalar
En febrero de 2025, Andrej Karpathy publicó en X lo que parecía una broma. Describió el "vibe coding" como aceptar lo que sea que el LLM produjera sin leerlo realmente. "Solo veo cosas, digo cosas, ejecuto cosas y copio y pego cosas", escribió, "y la mayoría de las veces funciona".
Y la mayoría de las veces funcionaba. Durante alrededor de un año.
A finales de 2025, la industria empezó a recibir la cuenta. Una investigación de Forrester publicada en 2025 encontró que el código con una participación significativa de IA presentaba aproximadamente 1.7 veces más problemas graves. Auditorías separadas de firmas de seguridad ubicaron la proporción de código generado por IA con fallas de seguridad entre el 40 y el 62 por ciento, dependiendo del estilo del prompt y el lenguaje. Los modelos alucinan APIs, omiten la validación de entradas, filtran secretos en logs y llaman con confianza a funciones que no existen.
Lo que se rompió fue el supuesto de que un solo prompt y una sola ventana de contexto podían sostener un código base real. Los repositorios crecieron. Las convenciones se volvieron más específicas. Los efectos secundarios (migraciones, despliegues, llamadas a APIs de pago) se volvieron más peligrosos. El flujo de trabajo que se sentía mágico en una app desde cero colapsó cuando lo apuntabas a un servicio con cinco años de decisiones acumuladas.
Las grietas se mostraron de tres formas. Los modelos olvidaban las convenciones del proyecto a mitad de sesión y reintroducían patrones que el equipo había dedicado meses a eliminar. Las sesiones largas acumulaban tanto contexto irrelevante que el modelo empezaba a ignorar la tarea real. Los agentes ejecutaban con total tranquilidad comandos destructivos porque nada los detenía. Un prompt que decía "no hagas push a main" funcionaba alrededor del 95 por ciento de las veces, lo cual es otra forma de decir que fallaba 1 de cada 20 sesiones.
Para fines de 2025, todo equipo serio que usaba Claude Code, Cursor o herramientas similares había construido alguna versión del mismo andamiaje alrededor del modelo. Nadie tenía un nombre para eso todavía.
El renombre de Karpathy hacia la ingeniería agéntica
En febrero de 2026, Karpathy volvió a publicar. El nuevo término era "agentic engineering" (ingeniería agéntica).
El vibe coding, argumentaba, describía el modo de juguete. La ingeniería agéntica describía lo que estaban haciendo quienes realmente lanzaban a producción: escribir archivos de contexto específicos del proyecto, definir skills acotadas, lanzar subagents para trabajo aislado y controlar el uso de herramientas mediante hooks deterministas. El modelo sigue siendo el que escribe. El humano hace la ingeniería del sistema dentro del cual corre el modelo.
El tooling maduró entre las dos publicaciones. Claude Code Best Practices de Anthropic documentó la convención CLAUDE.md y el patrón de subagent. Building Agents with the Claude Agent SDK presentó el bucle del agente y el papel de los hooks. Las Skills llegaron en octubre de 2025: pequeños archivos markdown que el agente carga solo cuando la tarea los dispara. Cursor 2.0 lanzó agentes en segundo plano corriendo en VMs en la nube con aislamiento mediante git-worktree y hasta ocho agentes en paralelo.
"Context Engineering for Coding Agents" de Martin Fowler capturó el principio que unía todo esto. El trabajo ya no es prompt engineering, que optimizaba una cadena de texto. El trabajo es context engineering: decidir qué ve el modelo, cuándo lo ve y qué puede hacer con eso.
Esto no es exclusivo de Anthropic. Cursor los llama rules y background agents. GitHub Copilot usa la convención AGENTS.md. Gemini CLI usa GEMINI.md. Los nombres difieren. La forma no.
Los cuatro pilares de la ingeniería agéntica
Antes de profundizar en cada pilar, ayuda verlos lado a lado. Se parecen entre sí (todos son "cosas que le das al agente"), pero resuelven problemas distintos.
| Pilar | Qué almacena | Cuándo se carga | Modo de falla si no está |
|---|---|---|---|
| CLAUDE.md | Contexto del proyecto siempre vigente: stack, convenciones, comandos, reglas duras | En cada sesión, de forma automática | El modelo reinventa convenciones, olvida el gestor de paquetes, corre npm install en un repo de yarn |
| Skills | Conocimiento procedimental para tareas acotadas (rebase, migración de esquema, revisión de Stripe) | A demanda, cuando la tarea coincide con la descripción del skill | El modelo improvisa pasos específicos del dominio y se equivoca de orden |
| Subagents | Una ventana de contexto fresca más un system prompt para un único rol | Cuando el agente principal delega una tarea definida | El contexto principal se contamina con desvíos; una mala llamada a una herramienta corrompe toda la sesión |
| Hooks | Comandos de shell disparados en eventos de herramientas (PreToolUse, PostToolUse, Stop) | De forma determinista, cada vez que se dispara el trigger | Comandos riesgosos corren sin control; el formateador nunca se ejecuta; el prompt "siempre haz X" falla en silencio |
El patrón: CLAUDE.md es lo que el modelo sabe. Las Skills son lo que el modelo puede consultar. Los Subagents son a quién más le puede preguntar el modelo. Los Hooks son lo que el modelo no puede evitar.
Cada pilar existe porque los otros tres no pueden resolver ese modo de falla específico.
CLAUDE.md: la capa orientativa
CLAUDE.md (o AGENTS.md, o GEMINI.md, según tu herramienta) es un archivo markdown en la raíz de tu repo. El agente lo lee al inicio de cada sesión y lo trata como contexto de fondo.
No es memoria en el sentido de los productos de consumo. Es el archivo que tú, el humano, escribes para decirle al agente lo que habría aprendido si hubiera estado en el equipo durante un año.
Qué pertenece ahí:
- Stack y versiones: "Next.js 16 App Router, React 19, Yarn 1.22 (npm prohibido), Node 22."
- Estructura del repo: qué hace cada directorio.
- Comandos:
yarn dev,yarn test,yarn build:ci, con notas sobre cuál es seguro ejecutar. - Reglas duras: "Nunca hagas push directamente a
main. Siempre crea una rama de feature." - Convenciones de estilo: ancho de tabulación, reglas de lint que pican, convenciones de nombres.
- Atajos de dominio: términos del glosario específicos de tu producto.
Qué no pertenece: instrucciones paso a paso para tareas ocasionales (esas van en Skills), documentación de referencia larga (el modelo solo le da un vistazo, mejor enlaza hacia afuera) y cualquier cosa secreta (el contenido de CLAUDE.md se carga al contexto, y el contexto puede citarse de vuelta).
La trampa en la que cae la mayoría de los equipos es el CLAUDE.md tipo bandeja de todo. Un archivo de 4,000 líneas con cada estándar de código y cada decisión de arquitectura. El modelo carga todo eso en cada tarea y empieza a tratar el 5 por ciento relevante igual que el 95 por ciento irrelevante. Los costos en tokens suben. La adherencia a reglas específicas baja.
Un buen CLAUDE.md se parece más a un post-it que a una wiki. Apunta a una pantalla de contexto esencial. Si te encuentras escribiendo una sección que empieza con "Al hacer X..." entonces X probablemente quiere ser una skill. CLAUDE.md es para lo "siempre cierto". Las Skills son para lo "cierto cuando".
Skills: archivos de conocimiento justo a tiempo
Las Skills son pequeños archivos markdown (típicamente de menos de 200 líneas) que el agente carga solo cuando la tarea coincide. Cada skill tiene un nombre, una descripción y un cuerpo. La descripción es lo que el agente lee primero para decidir si carga el skill completo.
Anthropic lanzó las skills como concepto de primer nivel a finales de 2025. Pones un archivo de skill en un directorio conocido; su frontmatter describe cuándo usarlo. Al planificar una tarea, el agente escanea las descripciones de skills disponibles y carga las que coincidan.
Buenos ejemplos de skills:
rebase-cleanly: cómo hacer rebase sobredevelop, reglas de resolución de conflictos, qué hacer si los tests fallan después del rebase.review-stripe-integration: checklist para cambios que tocan webhooks de Stripe, claves de idempotencia, IDs de precios.add-shadcn-component: los comandos exactos y convenciones de import para agregar un componente de shadcn/ui a este repo.debug-flaky-test: el orden de operaciones preferido del equipo cuando un test de CI es intermitente.
Cada uno es procedimental y acotado. Cada uno tendría demasiado detalle para vivir en CLAUDE.md, pero es demasiado importante para dejárselo al conocimiento general del modelo.
El modelo mental: CLAUDE.md es tu colega explicándole lo básico al nuevo el primer día. Una skill es el runbook que le entregan al nuevo cuando un webhook de Stripe falla a las 2 a.m. No memorizas el runbook; lo lees cuando lo necesitas.
Las Skills se combinan. El agente puede cargar tres skills en una sola tarea ("agregar una nueva ruta de API" más "validar la entrada con Zod" más "escribir un test con Vitest") sin que tú anticipes la combinación de antemano.
Las descripciones de las skills importan más de lo que pensarías. Las vagas ("útil para cosas de código") o no se disparan nunca o se disparan con todo. Escribe descripciones que nombren la situación: "Usa cuando el usuario pida hacer rebase de una rama, resolver conflictos de merge o limpiar el historial de commits."
Subagents: trabajadores con contexto aislado
Un subagent es un agente al que el agente principal puede llamar. Tiene su propio system prompt, su propia ventana de contexto y sus propios permisos de herramientas. Cuando termina, devuelve un resultado al agente principal. Y luego desaparece.
La lectura ingenua es "los subagents sirven para el paralelismo". Eso es parte (Cursor 2.0 publicita hasta ocho agentes en segundo plano en paralelo), pero el paralelismo no es el beneficio principal. El beneficio principal es el aislamiento del contexto.
Tres patrones donde los subagents rinden:
1. El investigador. Quieres que el agente busque en 200 archivos y resuma lo que encuentra. Si el agente principal lo hace, los 200 archivos terminan en el contexto principal, aunque solo necesitabas tres oraciones de resumen. Un subagent de investigación lee los 200 archivos, resume y devuelve un párrafo. El contexto principal queda limpio.
2. El revisor. Antes de un commit, quieres una pasada fresca sobre el diff. Un subagent revisor carga una skill de "code review", lee el diff sin ningún otro contexto y reporta problemas. Como no tiene memoria de la discusión de implementación que el agente principal tuvo contigo, no puede racionalizar los problemas para hacerlos desaparecer.
3. La operación riesgosa. Un script de migración. Un renombrado masivo. Un cambio de esquema. El agente planifica y lo ejecuta de forma aislada, y luego reporta. Si algo sale mal, el desastre queda contenido en el contexto del subagent.
Hay un costo real. Cada subagent es otra llamada al modelo y otra ventana de contexto. Agregan complejidad de coordinación. Un equipo que lanza un subagent para cada tarea quema tokens y se hace más lento.
La regla práctica: lanza un subagent cuando se cumpla una de tres cosas. (1) La tarea volcaría mucha basura en el contexto principal. (2) La tarea se beneficia de una perspectiva fresca. (3) La tarea es riesgosa y la quieres en un sandbox. De lo contrario, sigue trabajando en la sesión principal.
Colecciones open source como awesome-claude-code-subagents de VoltAgent catalogan cientos de subagents prefabricados. A la mayoría de los equipos les va mejor con tres o cuatro subagents personalizados afinados a su código base que con docenas genéricos.
Hooks: barreras deterministas
Los Hooks son la parte del stack de la que el modelo no puede zafarse hablando. Son comandos de shell conectados a eventos de herramientas. Cuando el evento se dispara, el comando se ejecuta. El modelo no tiene voz.
Los eventos canónicos:
- PreToolUse: se dispara antes de una llamada a una herramienta. Puede bloquearla.
- PostToolUse: se dispara después de una llamada a una herramienta. Útil para formateadores, validadores, efectos secundarios.
- Stop: se dispara cuando el agente termina un turno. Útil para notificaciones.
- Notification: se dispara con ciertos mensajes del agente.
Por qué los hooks le ganan a los prompts en seguridad: los prompts son probabilísticos. Incluso una instrucción clara como "nunca ejecutes rm -rf" fallará ocasionalmente, porque el modelo está haciendo completado de patrones. Un hook que hace grep al comando buscando rm -rf y sale con código distinto de cero antes de que el shell lo vea, fallará cero por ciento de las veces. Es una regex, no una vibra.
Tres hooks que vale la pena tener:
pre-bash-guard (PreToolUse en Bash). Lee el comando y bloquea patrones peligrosos: rm -rf /, git push --force contra ramas protegidas, DROP TABLE, sobrescrituras directas de archivos .env*. Un script de shell de 30 líneas te salva de desastres que los prompts no pueden prevenir de forma confiable.
post-edit-prettier (PostToolUse en Edit/Write). Después de que el agente edita un archivo .ts o .tsx, ejecuta prettier. Atraparlo de forma determinista mantiene el estilo consistente a lo largo de la sesión.
notify-on-stop (Stop). Cuando el agente termina una tarea larga, dispara una notificación de macOS o un ping a Slack. Calidad de vida, pero cambia cómo trabajas: puedes dejar al agente corriendo durante diez minutos y no estar cuidándolo.
Hay un pequeño costo de rendimiento. Cada hook implica lanzar un proceso. En la práctica esto es imperceptible comparado con la latencia del propio modelo, y el determinismo lo vale.
El cambio de mentalidad: deja de pensar la seguridad como algo que le pides al modelo que haga. Empieza a pensar la seguridad como algo que el entorno hace cumplir, de la misma manera en que un pipeline de CI hace cumplir los tests. El modelo es un junior rápido. Los hooks son el pre-commit hook que el junior no puede deshabilitar.
Cómo se combinan los cuatro pilares
Así se ve la configuración real de un equipo, en prosa.
El repo tiene un CLAUDE.md en la raíz. Unas 80 líneas. Lista el stack (Next.js 16, React 19, Yarn, Node 22), la estructura de directorios, el comando de test, la regla de deploy y un glosario de cinco términos de dominio.
En .claude/skills/, seis archivos de skill: rebase-cleanly.md, add-api-route.md, review-stripe.md, debug-firestore.md, write-deep-dive.md, sql-migration.md. Cada uno de 80 a 150 líneas.
En .claude/subagents/, tres. Un reviewer corre antes de los commits y reporta problemas del diff. Un researcher se invoca cuando el agente principal necesita leer más de diez archivos. Un test-runner se invoca cuando un test falla al primer intento; aísla la falla sin contaminar el contexto principal.
En .claude/hooks/, cuatro. pre-bash-guard.sh bloquea comandos peligrosos. pre-edit-env-guard.sh bloquea ediciones a .env.local. post-edit-prettier.sh corre prettier tras editar archivos .ts/.tsx. notification.sh hace ping en macOS cuando termina una tarea larga.
Una sesión normal: el desarrollador le pide al agente "agrega una nueva ruta de API que devuelva los bookmarks del usuario". El agente lee CLAUDE.md, hace match con la skill add-api-route y la carga, escribe el archivo. El post-edit hook corre prettier. Escribe un test, prettier corre de nuevo. Le pide al subagent revisor que revise el diff. El revisor marca falta de validación de entrada; el agente principal la agrega. El desarrollador pide hacer commit. El pre-bash hook revisa la rama y permite el commit. El stop hook le hace ping al desarrollador.
Ninguna parte de ese flujo necesitó un prompt largo. El prompt fue "agrega una nueva ruta de API que devuelva los bookmarks del usuario". Todo lo demás estaba cableado al entorno.
Antipatrones que los equipos siguen lanzando
Algunos patrones a evitar, extraídos de equipos que adoptaron este stack mal.
El CLAUDE.md gigante. Algunos equipos tratan CLAUDE.md como vertedero de cada decisión en tres años. El resultado es un archivo de 5,000 líneas que el modelo carga pero no internaliza. La regla de no usar npm queda intercalada entre dos páginas de justificación arquitectónica, y el modelo recoge la justificación y olvida la regla. Mantén CLAUDE.md compacto.
La apuesta sin hooks. Algunos equipos se saltan los hooks por completo y se apoyan en prompts para mantener al agente seguro. Esto funciona la mayor parte del tiempo, que es exactamente el problema. "La mayor parte del tiempo" no es suficiente para rm -rf o git push --force. Si la consecuencia es "perdí una hora de trabajo", los prompts están bien. Si la consecuencia es "borré una tabla de producción", necesitas un hook.
Proliferación de subagents. Algunos equipos construyen un subagent para cada rol concebible. Investigador, revisor, planificador, resumidor, nombrador, refactorizador, documentador, tester. Cada uno es otro archivo que mantener, otro conjunto de tokens, otra sobrecarga de coordinación. Los equipos que tienen éxito con subagents suelen tener de tres a cinco, cada uno con una función clara. No veinte.
Skill como vertedero de documentación. Una skill no es un lugar para tus viejas páginas de wiki. Si una skill tiene 800 líneas, el modelo carga 800 líneas cada vez que se dispara. Si tu skill es larga, probablemente son dos skills.
Tratar las Skills como CLAUDE.md. Poner contexto siempre vigente en una skill significa que se carga solo a veces. La regla de equipo "nunca uses npm" pertenece a CLAUDE.md, porque aplica a cada tarea.
Hooks que bloquean al agente por diez segundos. Un hook que corre una suite de tests completa en cada edición vuelve al agente inusable. Los hooks deben ser rápidos. Las verificaciones costosas pertenecen al CI.
La configuración práctica que puedes adoptar esta semana
Si has leído hasta aquí y quieres un punto de partida, esta es la versión esbelta. Una persona ingeniera senior puede armarla en un día, y es suficiente para hacer que la programación agéntica sea significativamente más confiable que el default del vibe coding.
CLAUDE.md (unas 50 líneas). Stack y versiones. Gestor de paquetes (y cuál nunca usar). Directorios de nivel superior. Las cinco reglas duras (no hagas push a main, no toques .env.local, usa estos comandos de test). Una lista corta de términos de dominio. Resiste el impulso de agregar más.
Dos skills. rebase-cleanly.md (los pasos de rebase de tu equipo, 80 líneas máximo) y review-changes.md (tu checklist de code review, 100 líneas máximo).
Un subagent revisor. Carga review-changes.md, lee el diff y reporta problemas. Se invoca antes de los commits.
Tres hooks. PreToolUse en Bash bloquea rm -rf, git push --force contra ramas protegidas y ediciones a archivos .env*. PostToolUse en Edit/Write corre prettier en archivos .ts/.tsx editados. Stop dispara una notificación de macOS cuando el agente termina.
Eso es todo. CLAUDE.md más dos skills más un subagent más tres hooks. Una carpeta con quizás ocho archivos, todos bajo control de versiones, todos revisables por el resto del equipo.
Vas a iterar. Después de una semana, vas a notar tareas que el agente sigue tropezando y las codificarás como nuevas skills. Vas a ver categorías de comandos malos y los agregarás al pre-bash guard. Vas a detectar el momento en que un subagent investigador habría mantenido limpio tu contexto principal y agregarás uno. Los cuatro pilares son la forma. El contenido es tuyo.
El paso del vibe coding a la ingeniería agéntica no es un escalón de astucia. Es un paso hacia la disciplina operativa. Estás tratando al agente como tratarías a cualquier otro sistema que corre en producción: con convenciones, barreras y aislamiento entre responsabilidades. Menos magia, más ingeniería, y un flujo de trabajo que escala más allá del primer mes.
Preguntas frecuentes
¿Esto es específico de Claude Code o aplica también a Cursor y otros agentes?
Los pilares aplican entre herramientas; los nombres difieren. Cursor usa archivos de "rules" y "background agents". GitHub Copilot usa AGENTS.md. Gemini CLI usa GEMINI.md. Los Hooks aún no son universales (Claude Code tiene la implementación más madura), pero la mayoría de las herramientas tienen algún equivalente. El modelo mental (capa de contexto, conocimiento bajo demanda, trabajadores aislados, controles deterministas) generaliza incluso donde la implementación difiere.
¿Cuál es la diferencia entre una Skill y poner todo en CLAUDE.md?
La carga. CLAUDE.md se carga al inicio de cada sesión. Las Skills se cargan solo cuando su descripción coincide con la tarea. Si pones conocimiento procedimental para diez tareas distintas en CLAUDE.md, el modelo carga todo eso en cada tarea, el contexto se llena de contenido mayormente irrelevante y la adherencia a reglas específicas cae. Las Skills mantienen CLAUDE.md compacto y los detalles procedimentales disponibles bajo demanda.
¿Cuándo debería crear un subagent en lugar de usar un prompt más largo?
Tres condiciones te empujan hacia un subagent. (1) La tarea volcaría mucho contenido en el contexto principal. (2) Quieres una perspectiva fresca que el razonamiento acumulado del agente principal no pueda viciar. (3) La tarea es riesgosa y la quieres en un sandbox. De lo contrario, un prompt más largo o una skill suele ser la mejor herramienta. Los subagents cuestan tokens y coordinación.
¿Los hooks ralentizan al agente?
Cada hook implica lanzar un proceso, así que agrega de milisegundos a segundos según lo que haga. En la práctica, esto queda eclipsado por la propia latencia del modelo. Los hooks largos (correr una suite de tests completa en cada edición) harán que el agente se sienta lento; esos pertenecen al CI. Una buena regla: los hooks PreToolUse deberían salir en menos de 200ms en el caso común; los hooks PostToolUse como formateadores pueden tomar uno o dos segundos sin que nadie lo note.
¿Debería hacer commit de mi CLAUDE.md al repo?
Sí, casi siempre. CLAUDE.md es un artefacto de equipo: codifica las convenciones que todos (humanos o agentes) deberían seguir. Hacerle commit significa que los agentes de todo el equipo trabajan desde el mismo contexto, y el archivo se revisa como cualquier otro código. Lo único que podrías mantener local son las configuraciones de permisos por persona desarrolladora (Claude Code soporta un settings.local.json para eso).
Reflexiones finales
Las dos publicaciones de Karpathy, separadas por un año, encuadran perfectamente lo que le pasó a la programación con IA en 2025. La primera fue permiso para jugar. La segunda fue la llegada de la cuenta. El vibe coding fue útil como modo de descubrimiento: le enseñó a la gente lo que estos modelos podían hacer sin obligarlos a aprender primero un SDK. No estaba diseñado para llegar a producción.
Lo que lo está reemplazando es reconocible para cualquiera que haya trabajado en sistemas reales. Anotas los invariantes (CLAUDE.md). Empaquetas los procedimientos (Skills). Lanzas trabajadores aislados para tareas riesgosas o pesadas en contexto (Subagents). Instalas barreras en los límites (Hooks). Nada de esto es exótico. Es la misma disciplina operativa que distingue un proyecto hobby de un servicio que corre el lunes por la mañana sin que nadie esté de guardia.
Lo que me sorprende de las configuraciones de los equipos que funcionan es lo pequeñas que son. Ocho archivos. Quizás mil líneas en total. Un subagent revisor. Tres hooks. Eso basta para convertir a un modelo que de vez en cuando tira tu base de datos en un compañero de equipo que no lo hace. El apalancamiento no está en el volumen. Está en poner el invariante correcto en el pilar correcto.
Si todavía estás en modo vibe coding puro a mediados de 2026, no estás atrasado. Estás en la etapa donde la mayor parte de la ganancia de productividad viene de hacer que el modelo sea aburrido: más predecible, más restringido, más revisable. Menos magia, a propósito. Ese es el trabajo.