Entregamos tickets reales a agentes de programación todos los días, y casi siempre entregan algo que funciona. Esa nunca fue la preocupación. La preocupación es cómo trabajan: un nuevo helper junto a otros tres que ya hacen ese trabajo, una abstracción recién creada para un único consumidor, una corrección que parchea la única ruta que mencionaba el ticket y deja cuatro hermanas rotas, un hallazgo que “probablemente sea un bug” sin pruebas en ningún sentido. Cada cambio es razonable a nivel local. En conjunto, son entropía.
TL;DR: En cinco pull requests Tier 3 sobre nuestro núcleo de orquestación de agentes, tres habilidades componibles —
ponytail(restar),grain(alinear) yreview-proof(demostrar) — eliminaron 821 líneas mientras entregaban cinco funcionalidades, detectaron una ruptura de contrato silenciosa que la sola plausibilidad habría fusionado, y mantuvieron cada cambio avanzando a favor de la veta de la arquitectura existente. Esto es lo que hace cada una, con los diffs reales que lo respaldan.
Quita las barandillas y un agente de programación se convierte en un generador muy rápido de responsabilidades que parecen plausibles. Así que nos apoyamos en tres habilidades pequeñas que empujan en la dirección contraria: un instinto cada una: restar, alinear, demostrar.
ponytail— escribe lo más vago que funcione de verdad. Borra antes de añadir. (Esta no la escribimos nosotros: es una habilidad de código abierto de Dietrich Gebert que adaptamos a nuestro stack.)grain/grain-review— ponlo donde el código base ya decidió que va. No inventes una segunda forma.review-proof— no te creas un hallazgo hasta que se reproduzca como un test que falla.
grain y review-proof las construimos con el mismo espíritu que ponytail, ajustadas a nuestra arquitectura. Cada uno de los cinco PR de abajo toca nuestro núcleo de orquestación de agentes —el lugar más caro del repositorio para volverse descuidado— y todos están clasificados como Tier 3: cobertura de tests adicional y revisión humana por encima del revisor automatizado, sin excepciones.
Las tres habilidades de un vistazo: ponytail resta, grain alinea, review-proof demuestra.
Parte 1 · QUÉ — la entropía es lo predeterminado
Esto es lo que nadie te advierte cuando entregas un repositorio a agentes de IA: cada agente optimiza a nivel local y no recuerda nada. Ve el ticket, no los meses de convenciones en los que convergió tu equipo. No tiene ninguna razón para preferir tu servicio de correo existente a uno nuevo, no recuerda que el conjunto de estados de redirección ya está definido tres archivos más allá, no tiene el instinto de que “la corrección va en la función compartida, no en este consumidor concreto”. Si los dejas sueltos, N agentes producen N formas ligeramente distintas de hacer lo mismo. Eso no es un problema de calidad de código que puedas eliminar con un linter: es una deriva estructural que se acumula.
Las tres habilidades apuntan cada una a un eje de esa deriva.
ponytail — lo más vago que funcione
Ponytail es un desarrollador sénior al que han despertado a las 3 de la mañana por la abstracción ingeniosa de otra persona y que se niega a escribir la siguiente. Recorre una escalera y se detiene en el primer peldaño que aguanta: ¿hace falta que esto exista siquiera (YAGNI) → ya está en este código base → lo hace la biblioteca estándar → es una característica nativa de la plataforma → es una dependencia ya instalada → puede ser una sola línea → solo entonces, el mínimo código que funciona.
El peldaño que más importa con los agentes es "¿ya está en este código base?". Reimplementar algo que está unos archivos más allá es la forma más común de basura generada por agentes. Y la regla de ponytail para corregir bugs mantiene los diffs honestos: corrige la causa raíz, no el síntoma. Haz grep de todos los consumidores de la función que estás a punto de tocar; una guarda en la función compartida es un diff más pequeño que una guarda en cada consumidor, y no deja a las hermanas rotas.
grain / grain-review — a favor de la veta
Si ponytail gobierna qué poco escribes, grain gobierna dónde va y qué forma tiene. Su única regla: encuentra el ejemplo existente más cercano, copia su forma, nombra lo que copiaste. El código nuevo debería leerse como si lo hubiera escrito la misma persona que escribió el archivo de al lado.
Grain es también donde se impone la arquitectura. Nuestro backend es un diseño bastante estándar de vertical slice + hexagonal: presentación llama a aplicación, aplicación llama a dominio, la infraestructura depende hacia dentro y el dominio nunca alcanza hacia fuera. Un hallazgo como “esta ruta se salta su controlador y llama directamente al servicio” no es pedantería: es la diferencia entre un código base que un agente podrá navegar el mes que viene y uno que no. grain-review caza exactamente esto: helpers duplicados, fronteras de capas cruzadas, intromisión en las tripas de otra funcionalidad, una segunda convención para algo que ya se hacía de una sola forma.
review-proof — gánate el hallazgo
La revisión de código con IA estándar produce hallazgos plausibles. Algunos son reales; otros son tonterías seguras de sí mismas; desde fuera parecen idénticos. review-proof se niega a confiar en sí misma: revisa y luego obliga a cada hallazgo de corrección a reproducirse como un test que falla de verdad o como un repro ejecutable, y descarta todo lo que no lo consiga. Cierra con una pasada de grain-review para el encaje estructural. Lo que se entrega es una revisión en la que cada punto viene con evidencia ejecutable, no con una intuición.
Qué deberíamos ver si esto funciona
- H1 — La eliminación aparece en los PR de funcionalidades. Si ponytail + grain funcionan, añadir una funcionalidad debería eliminar estructura neta con frecuencia, no solo añadirla.
- H2 — Las correcciones aterrizan una vez, en el lugar compartido. Las correcciones de causa raíz deberían colapsar muchos puntos de llamada en una sola guarda, no salpicar guardas por consumidor.
- H3 — La revisión detecta rupturas de contrato que un humano pasa por alto. La revisión respaldada por pruebas debería sacar a la luz bugs que una revisión de “parece bien” se pierde, sobre todo los silenciosos.
Parte 2 · Y QUÉ — cinco PR, un instinto cada uno
Cinco cambios reales en nuestro núcleo de agentes. Mantenemos las tripas vagas a propósito —el repositorio es privado—, pero los números se calculan a partir de los diffs reales y las lecciones son la parte transferible.
Restar: una guarda para una docena de puntos de fetch
Una familia de pasos de flujo obtenía URLs proporcionadas por el usuario sin una comprobación de seguridad con resolución DNS, así que un nombre de host que resolvía a una dirección interna podía alcanzar metadatos de la nube desde el backend. La corrección tentadora añade una comprobación en cada uno de los más de una docena de puntos de fetch. La respuesta de ponytail fue la contraria: un único helper de fetch compartido y con guarda, usado en todas partes, y eliminamos una tabla de red privada hecha a mano que un truco de DNS comodín atravesaba sin problema, además de tres bucles de redirección duplicados y una comprobación de red copiada y pegada en varios archivos.
El diff añadió el helper compartido y eliminó unas 90 líneas de duplicación en 22 archivos. Esa eliminación es la historia: esto es H2 en carne viva, la corrección de causa raíz encaminó a todos los consumidores por una sola guarda en lugar de parchear la única ruta que mencionaba el ticket.
La corrección de causa raíz: una docena de puntos de fetch ad hoc se colapsan en un único helper compartido y con guarda. La corrección vaga y la corrección segura son la misma corrección.
Restar + demostrar: una guarda de forma, probada en el runtime real
Nuestro runtime de workers persiste el resultado de una ejecución como una cadena serializada, a veces envuelta en una lista de un solo elemento. Los consumidores que esperaban un objeto plano se caían con ella. La corrección equivocada esparce comprobaciones de tipo defensivas en cada consumidor. En su lugar: un pequeño helper que normaliza la forma, y todos los consumidores redirigidos a él: una adición casi pura de una guarda que sustituye las N guardas ad hoc que habría escrito un agente menos disciplinado (+558 / −24, 7 archivos).
La parte que convierte esto en una historia de review-proof es el test. En lugar de comprobar contra una forma de serialización supuesta, ejecutamos un flujo de trabajo real a través del runtime y el almacenamiento reales —sin mocks— y demostramos la forma que el runtime realmente persiste. La pregunta abierta del ticket era literalmente ¿qué serializa el runtime aquí?, y la única respuesta honesta es una que puedas ejecutar.
Demostrar: la revisión detectó una ruptura de contrato silenciosa
Funcionalidad: un modelo de respaldo por nodo, para que un flujo fijado a un proveedor se degrade con elegancia durante una caída. El primer corte obvio envolvía el modelo en el combinador de respaldo integrado del framework.
Funcionaba en el camino feliz. También desactivaba silenciosamente dos características del proveedor que dependen del tipo concreto del modelo mediante isinstance: un objeto envuelto ya no es de ese tipo, así que tanto la salida estructurada nativa como el almacenamiento en caché de prompts se apagaban sin hacer ruido. Sin error. Sin test del camino feliz que fallara. Exactamente el tipo de cosa que una revisión humana pasa por alto y que un agente que “parece bien” aprueba.
review-proof no lo aprobó: reprodujo ambas roturas como tests que fallan, lo que forzó el rediseño: aplicar el respaldo más abajo, en tiempo de ejecución, para que cada modelo siga siendo de su tipo concreto y las características condicionadas por tipo sigan funcionando. H3, confirmada de forma contundente: la prueba detectó un bug que la plausibilidad habría enviado a producción.
Alinear: un solo selector, no dos copias
Añadir un segundo canal de notificaciones significaba que la interfaz de selección de canal tenía ahora dos hogares: un asistente de creación y un modal de ajustes. El movimiento por defecto de un agente añade la nueva rama a ambos, haciendo crecer dos copias de la misma máquina de estados. grain dijo: ya existe una forma en la que esto debería tener forma: hazlo compartido. Extraímos un único hook de selección y llevamos ambas pantallas a través de él, encajamos el nuevo canal en la unión de configuración existente y reutilizamos el servicio de correo existente en lugar de añadir nueva maquinaria de envío.
+1.735 / −340 en 24 archivos. Que una funcionalidad de este tamaño elimine 340 líneas es H1 hecha visible: la deduplicación de dos copias del selector en una pagó buena parte del nuevo canal.
Alinear + demostrar: reutiliza el endpoint, refleja la ruta
Permitir que los usuarios adjunten archivos al crear una incidencia podría haber significado un nuevo endpoint de subida, un nuevo mecanismo de despacho, una nueva ruta de prompt. grain encaminó casi todo por raíles existentes: el endpoint de subida existente, una lista de aceptación del frontend que refleja exactamente la lista blanca del backend, y una corrección de despacho diferido que reutilizó el mecanismo de elegibilidad que ya usaba el trabajo programado. Se entregó con correcciones respaldadas por pruebas, incluido un bug real de aislamiento de transacciones que habría perdido datos con subidas en paralelo. +1.776 / −218 en 27 archivos: una funcionalidad grande que aun así encontró 218 líneas que eliminar uniéndose a slices existentes en lugar de inventar otros nuevos.
El marcador
Cinco PR Tier 3: qué añadió cada uno, qué eliminó y el instinto que hay detrás.
Cinco PR de funcionalidades y correcciones sobre el núcleo de agentes eliminaron 821 líneas, no por hacer menos, sino por negarse a duplicar lo que ya existía y a mantener parches de síntoma que una corrección de causa raíz dejaba redundantes.
Divulgación completa
- Estas son habilidades, no un estudio. Esto no es un experimento controlado con un brazo de referencia; son cinco PR reales en los que se aplicó la disciplina. El contrafactual —lo que el mismo agente habría entregado sin las habilidades— es una estimación informada, no una medición. La historia de la ruptura de contrato silenciosa es la evidencia más limpia, porque vimos a la revisión reproducir el bug antes del rediseño.
- Los recuentos de líneas son indicadores indirectos. El −821 es un número real de los diffs, pero “líneas eliminadas” representa “duplicación y flexibilidad muerta evitadas”. Una habilidad que convence a un agente de no escribir 200 líneas especulativas no deja rastro alguno en un diff: las mayores victorias son invisibles aquí.
- El ahorro de tokens es direccional. Diffs más pequeños, menos archivos tocados y estructuras reutilizadas significan menos tokens gastados en generar, revisar y volver a revisar, pero no estamos citando un delta duro de tokens por PR.
ponytailno es nuestra. Es una habilidad de código abierto de Dietrich Gebert ; la adaptamos.grainyreview-proofson nuestras, construidas con el mismo espíritu. Las tres funcionan como habilidades locales de proyecto en Claude Code: prompt y procedimiento, no un binario que instalas.
¿Listo para hacer crecer tu negocio?
Comienza tu prueba gratuita hoy y ve resultados en días.
Parte 3 · AHORA QUÉ
Qué se entregó. Tres habilidades componibles. ponytail y grain se ejecutan mientras se escribe; ponytail-review, grain-review y review-proof se ejecutan sobre un diff. review-proof encadena grain-review como su fase final, así que una sola revisión demostrada también recibe gratis una pasada estructural.
Qué puedes hacer el lunes — no necesitas nuestras habilidades exactas:
- Haz que “reutilizar” sea el peldaño dos, no el diez. Antes de que un agente escriba un helper, haz que busque uno que ya exista. “¿Ya está en este código base?” pertenece por encima de “¿puedo escribirlo limpiamente?”
- Corrige en la raíz, demuéstralo con la lista de consumidores. Exige que cada corrección de bug nombre a todos los consumidores de la función tocada. Una guarda en la función compartida gana a una guarda por consumidor, y es un diff más pequeño.
- Dale al código nuevo un hermano cercano que copiar. “Encuentra el ejemplo existente más cercano y refleja su forma” convierte la arquitectura de un documento que nadie lee en un valor por defecto que el agente sigue.
- Impón las fronteras de capas en CI, no con intuiciones. Un trinquete que solo falla con importaciones nuevas entre capas te permite mantener la línea sin hervir el océano de deuda existente.
- No entregues un hallazgo que no puedas reproducir. Haz que el agente escriba primero el test que falla. Si no consigue reproducir el bug, no es un bug: es una opinión. Deséchala.
- Deja que la revisión elimine. Apunta una pasada de revisión específicamente a la sobreingeniería —“qué podemos recortar”—, separada de la corrección. El mejor resultado de un diff es que se vuelva más corto.
Pruébalo, sobre todo si a ti te falla. Si ejecutas agentes de programación sobre un código base real, la entropía ya está ocurriendo: simplemente no la has medido. Convierte una de estas ideas en una pasada de revisión en tus próximos diez PR de agentes y cuenta las eliminaciones. Si restar-alinear-demostrar no reduce tus diffs ni detecta una ruptura silenciosa, nos encantaría saberlo de verdad. Las correcciones y los contraejemplos son especialmente bienvenidos.
Un agente añade. El trabajo consiste en hacer que el agente se gane cada línea.
