Seis reglas contra el vibe coding dentro de AI-DLC

El ciclo de vida frena el vibe coding en los gates. No hace nada con el ingeniero que abre el archivo y lo corrige a mano.

El vibe coding es el hábito de mandarle prompts a un agente hasta que la cosa parece funcionar, sin leer el código ni decidir nada a propósito. AI-DLC se diseñó como lo opuesto: especificar primero, dejar que la IA conduzca, aprobar cada paso en un gate. En el papel, un equipo que corre AI-DLC no puede hacer vibe coding.

En la práctica vuelve a colarse, entre los gates. Alguien ve un bug en el código generado y lo parcha directo. Alguien le hace al agente una pregunta por curiosidad y el agente reescribe una spec como respuesta. Alguien le pregunta al agente si su propio diseño está bien, en la misma conversación en la que escribió ese diseño. Nada de esto rompe una regla del método. Todo esto lo deshace sin hacer ruido.

Las seis reglas de abajo no son mías. Vienen de un equipo que corre AI-DLC en producción y que las escribió después de ver a sus propios ingenieros cometer estos errores. Las reescribí con mis palabras y agregué el razonamiento que vi detrás de cada una. Las palabras para escribir son la parte para robarse.

Por qué un ciclo de vida igual deja pasar vibe coding

Cada regla de esta lista existe por el mismo motivo: el atajo es más rápido ahora, y el costo aparece después, en otro lado.

AI-DLC mantiene una cadena de artefactos, de los requisitos al diseño y al código, y cada uno debería describir al siguiente. Esa cadena es la memoria que el agente usa en cada sesión futura. En el momento en que cambias el código sin cambiar el diseño, la cadena miente. La próxima vez que el agente genere código para esa área, construye a partir de un diseño que ya no coincide con la realidad, y tu corrección desaparece sin aviso o choca con lo que él escribe.

Uno de los desafíos que surgieron en el piloto lo resumió bien: es tentador, y más rápido en el corto plazo, corregir el error en lugar de corregir lo que hizo que el error pasara. Cada regla de acá te obliga a corregir la causa.

Corregir el error

1. 01Parchar el código generado a mano
2. 02Pedirle al agente que solo haga pasar el test
3. 03Seguir en una sesión larga y cansada
4. 04Confiar en la revisión que el agente hace de su propio trabajo

Corregir la causa

1. 01Corregir el diseño y después volver a generar
2. 02Encontrar qué requisito o decisión estaba mal
3. 03Hacer commit, limpiar el contexto, retomar desde el estado
4. 04Pedir la crítica en un contexto limpio

Las seis reglas

Seis reglas, y qué escribir

1. 01

   Nunca edites código generado a mano. Vuelve al diseño.

   Un parche a mano hace que los artefactos mientan sobre el código. La siguiente generación construye a partir del diseño viejo y deshace tu corrección, o pelea con ella.

   En lugar de

   Abrir el archivo, cambiar tres líneas, hacer commit y seguir.

   Escribe esto

   I found a problem in the order service: cancelled orders keep their stock reservation. Let's review the design and make a plan to fix it.

2. 02

   Ponle un prefijo a cada pregunta exploratoria.

   Sin el prefijo, el agente lee una pregunta curiosa como un pedido de cambio y edita la spec en medio de la conversación.

   Escribe esto

   Do not update any documents. What happens if we move the reservation release into a background job?

3. 03

   Antes de un cambio grande, pide el impacto sin editar.

   Un cambio grande de diseño sobre trabajo ya aprobado se propaga por requisitos, historias y Units terminadas. Quieres el mapa del daño antes de aprobar el cambio.

   Escribe esto

   Do not change anything. Assess the impact of splitting the order service in two on the requirements, the user stories, and the Units already implemented.

4. 04

   Dile al agente qué bibliotecas internas existen antes de que escriba código.

   Toda empresa tiene sus propios starters y bibliotecas para autenticación, tracing y feature flags. Un agente que no las conoce inventa dependencias o reescribe lo que ya tienes.

   Escribe esto

   Before generating code, read docs/internal-libraries.md. Use these for auth, tracing, and feature flags, and do not add a dependency that duplicates one of them.

5. 05

   Pide la segunda opinión en un contexto limpio.

   En la misma conversación, el agente defiende las decisiones que tomó. Racionaliza. Un contexto limpio lee el artefacto como lo leería un extraño.

   Escribe esto

   /clear
   Read design/order-service.md. Produce a critique of it as if you hadn't written it.

6. 06

   Limpia el contexto en cada gate de aprobación, después de hacer commit y push.

   La calidad cae a medida que la sesión crece: intentos fallidos, idas y vueltas, borradores viejos. Limpiar en el gate obliga al agente a reconstruir el contexto solo a partir de lo oficial, los archivos aprobados y el estado.

   Escribe esto

   git add -A && git commit -m "Approve requirements" && git push
   /clear

Regla uno: la fuente de verdad es el diseño, no el código

Es la regla que los equipos más rompen, porque parece un desperdicio. El bug está ahí. La corrección son tres líneas. ¿Para qué volver a un documento de diseño?

Porque en AI-DLC el documento de diseño no es documentación. Es la entrada de la siguiente generación. Parcha el código y la próxima vez que alguien le pida al agente tocar esa área, regenera a partir del diseño viejo y tu corrección se pierde, o peor, se pierde a medias. Corrige el diseño y vuelve a generar, y la corrección sobrevive a todas las sesiones futuras.

Hay una segunda ganancia. Volver al diseño hace la pregunta que un parche nunca hace: ¿por qué el agente se equivocó en esto? Muchas veces la respuesta es un requisito que falta o una respuesta ambigua en el archivo de preguntas. Corregir eso corrige una clase de bugs, no un bug.

Reglas dos y tres: una pregunta no es una instrucción

Un agente que trabaja dentro de AI-DLC está listo para actuar. Tiene artefactos abiertos, un workflow que avanzar y una tendencia fuerte a tratar cualquier cosa que digas como un pedido para cambiar algo. Entonces, cuando preguntas “¿y si lo hiciéramos de otra forma?”, muchas veces lo hace de otra forma, ahí mismo, en la spec.

El prefijo es la protección más barata de esta lista. “Do not update any documents” convierte al agente de ejecutor en consultor por una respuesta. Úsalo cada vez que estés pensando en voz alta.

La regla tres es la misma idea a mayor escala. Antes de aprobar un cambio que toca la arquitectura, pide el impacto como reporte, con la edición explícitamente prohibida. Recibes una lista de requisitos, historias y Units terminadas que el cambio invalidaría. Después decides, con el costo enfrente, en lugar de descubrirlo un archivo regenerado a la vez.

Regla cuatro: el agente no conoce tu empresa

Un modelo leyó buena parte de la internet pública. No leyó tu starter interno de autenticación, tu biblioteca de tracing ni el cliente de feature flags que se supone que usa cada servicio. Si lo dejas solo, agarra el equivalente open source popular, y recibes un pull request que agrega una dependencia que tu equipo de plataforma pasó un año sacando.

La solución es decírselo, explícitamente, antes de que empiece la generación de código. Mantén un documento corto que liste las bibliotecas internas, para qué sirve cada una y qué alternativas públicas están prohibidas y por qué. El porqué importa. Un agente al que le dicen “no uses la biblioteca X” va a encontrar la biblioteca Y. Un agente al que le dicen “usamos nuestro propio cliente porque maneja los retries y los headers de tenant” va a buscar nuestro cliente.

Este también es el tipo de corrección que AI-DLC 2 puede volver permanente. Cuando corriges al agente durante un stage, su loop de aprendizaje ofrece guardar la corrección como regla del proyecto, y esa regla aplica desde el siguiente workflow. Dile que sí a esta. Solo quieres escribirla una vez.

Regla cinco: nunca le pidas al autor que se revise a sí mismo

Pregúntale a un agente, en la misma conversación, si el diseño que acaba de escribir está bien, y te va a explicar por qué está bien. Eso no es deshonestidad. El razonamiento que produjo el diseño sigue en su contexto, y lee su propio trabajo a través de ese razonamiento.

Limpia el contexto, carga solo el artefacto y pide una crítica como si no lo hubiera escrito. La diferencia en lo que vuelve es grande. Encuentra el supuesto que hizo en silencio, el caso que no manejó, el requisito que leyó sin rigor.

AI-DLC 2 ya trae parte de esto. Sus agentes revisores corren como subagents separados después de que un stage produce sus artefactos, así que leen el trabajo sin el razonamiento del autor en su contexto. Es el mismo principio. Úsalo, y mantén el hábito para cada artefacto que los revisores no cubren.

Regla seis: la conversación es descartable, los archivos no

Las sesiones largas se degradan. La ventana se llena de intentos fallidos, correcciones y borradores que se reemplazaron hace tres pasos, y el agente empieza a perder el hilo de decisiones que tomó antes. En los equipos que seguí, la calidad caía de forma visible cuando la context window pasaba de unas tres cuartas partes.

La respuesta es tratar la conversación como papel borrador. En cada gate de aprobación, haz commit y push de los artefactos aprobados, y después limpia el contexto. El agente retoma desde el archivo de estado y los archivos aprobados, que son justo las cosas que se supone que son verdad. Lo que se tira es el ruido.

El orden importa. Primero el commit, después la limpieza. Si limpias primero, puedes perder el único artefacto que la siguiente sesión necesitaba. Si una sesión se trabó en una investigación larga, pídele al agente un resumen corto de lo que encontró y lo que descartó antes de limpiar, y carga ese resumen en la sesión nueva. Cómo manejar todo esto en una codebase grande está en AI-DLC en brownfield.

Regla siete: limita el tamaño de cada Unit

La lista del equipo tenía seis reglas. El rollout les enseñó una séptima, y es la que tiene el efecto más medible.

Cuando AI-DLC genera código, genera mucho, rápido. Antes de la construcción, el agente divide el trabajo en Units, las piezas independientes que se construyen y se revisan por separado. Si lo dejas solo, propone sin problema una Unit que entrega una feature entera: migration, entidad, API, tests, todo en un merge request con cientos de cambios. Nadie revisa eso con atención real. El throughput sube, los merge requests se acumulan en review, y el tiempo entre el primer commit y el deploy empeora en lugar de mejorar. Ese patrón tiene su propio artículo: por qué AI-DLC primero te hace más lento.

La corrección pasa cuando el agente propone las Units. Pídele que estime el tamaño de cada una, y divide cualquiera que pase de un límite que tu equipo acuerde. Cien cambios por merge request es un punto de partida razonable. Un review de cincuenta cambios se puede manejar. Un review de trescientos cambios es un sello de goma.

La séptima regla

1. 01

   Limita el tamaño de cada Unit antes de aprobar el plan.

   El review se vuelve el cuello de botella cuando generar sale barato. Una Unit chica recibe un review de verdad. Una enorme recibe una mirada. Decide el límite con quienes revisan, y escríbelo para que las próximas sesiones lo respeten.

   Escribe esto

   Before I approve the Units, estimate the files and lines each one will change. Split any Unit above about a hundred changes: one per endpoint, and migrations in a Unit of their own.

Lo que AI-DLC 2 ya hace cumplir por ti

El motor nuevo cierra algunas de estas puertas por su cuenta, y vale la pena saber cuáles, para no pelear con la herramienta.

Corre cinco guardas que llama fences, que rechazan trabajo que nadie pidió. Reabren una aprobación cuando algo que ya aprobaste se cambió por debajo, congelan un artefacto mientras está en review, bloquean las escrituras directas al estado del workflow, mantienen a los revisores dentro de su alcance de lectura y exigen que una persona de verdad responda el gate. Una configuración llamada Guard Policy decide qué tan fuerte sostienen las primeras cuatro. Nada afloja la última. Cada Unit también necesita su propia aprobación de plan. El comando que verifica cada Unit lo elige y lo autoriza una persona, y cambiarlo exige una autorización nueva. Los revisores corren en su propio contexto. El archivo de estado sobrevive a la compactación de contexto.

Lo que no puede hacer cumplir son tus manos en el teclado. Nada en el motor te impide abrir un archivo generado en tu editor y cambiarlo. Nada te impide hacer una pregunta curiosa sin el prefijo. Las guardas protegen el workflow. Las reglas protegen el código.

Pon las reglas donde el agente las lee

Una regla que vive en la wiki del equipo se recuerda en los días buenos. Una regla que vive donde el agente la lee se aplica todos los días, por el agente, en la sesión de cada ingeniero.

Pon las bibliotecas internas, el límite de tamaño de las Units y los prefijos en las instrucciones de tu agente. Puede ser tu AGENTS.md, tu CLAUDE.md o, en AI-DLC 2, el archivo de memoria del equipo que cada workflow carga al inicio. Deja las reglas que son solo para personas, como hacer commit antes de limpiar, en el onboarding de quien corre el workflow.

¿Estás haciendo vibe coding dentro de AI-DLC?

• ✗Anti-pattern:
  Alguien corrigió código generado a mano esta semana.Revisa si el diseño también se actualizó. Si no, la siguiente generación va a deshacer la corrección.
• ✗Anti-pattern:
  Una spec cambió en una conversación que se suponía que era una pregunta.Faltó el prefijo. El agente tomó la pregunta como una instrucción.
• ✗Anti-pattern:
  El agente revisó su propio diseño en la misma sesión.Ese review fue una defensa, no una crítica.
• ✗Anti-pattern:
  Una sesión pasó de las tres cuartas partes de la context window.La calidad de la salida ya venía cayendo. Commit, limpiar, retomar.
• ✗Anti-pattern:
  Un merge request con cientos de cambios se aprobó en minutos.Nadie lo revisó. La próxima vez, divide las Units antes de la construcción.
• ✓Obligatorio:
  La lista de bibliotecas internas vive donde el agente la lee.Así nadie tiene que acordarse de pegarla.

Preguntas frecuentes

¿Qué es el vibe coding?+

El vibe coding es mandarle prompts a un agente de IA hasta que el resultado parece funcionar, sin leer el código ni tomar decisiones deliberadas sobre él. Sirve para un prototipo descartable. Se rompe cuando el código hay que mantenerlo, porque nadie decidió nada y nadie entiende lo que se construyó.

¿Se puede hacer vibe coding dentro de AI-DLC?+

Sí, entre los gates. El ciclo de vida revisa la salida de cada fase, pero no puede impedir que un ingeniero parche código generado a mano, haga preguntas exploratorias que el agente convierte en ediciones o deje que el agente revise su propio trabajo. Esos hábitos deshacen el método sin romper ninguna de sus reglas.

¿Por qué no corregir a mano un bug chico en el código generado?+

Porque en AI-DLC el diseño es la entrada de la siguiente generación. Un parche a mano hace que el diseño y el código no coincidan, y la próxima vez que el agente toque esa área regenera a partir del diseño viejo y tu corrección desaparece. Corrige el diseño y después vuelve a generar.

¿Pierdo mi trabajo cuando limpio el contexto?+

No, si haces commit y push antes. AI-DLC guarda el trabajo en archivos versionados y en un archivo de estado que registra dónde te quedaste. Limpiar el contexto tira la conversación, que para ese momento es ruido, y el agente retoma desde los archivos.

¿De qué tamaño debería ser una Unit de trabajo?+

Lo bastante chica para que una persona revise su merge request con atención real. Un primer límite razonable es de unos cien cambios por merge request. Acuerda un número con quienes hacen los reviews, pídele al agente que estime el tamaño de cada Unit antes de aprobar el plan y divide cualquiera que lo pase.

A dónde ir ahora

AI-DLC te da gates. Estas reglas son lo que haces entre ellos. El patrón debajo de las siete es el mismo: corrige la causa, no el síntoma, y mantén los archivos verdaderos, porque los archivos son la única memoria que tiene el agente.