Por qué creo en las Agentic Recipes

Construí mis herramientas de IA primero para ayudarme a trabajar en proyectos y sitios Drupal, y en los plugins de Claude Code que desarrollo. Mi esposa usa las mismas herramientas en su trabajo ahora, y esa es la parte que convirtió un hack personal en algo que tuve que mantener de verdad.

Las construí porque dos cosas fallaban. La IA no siempre seguía las instrucciones en CLAUDE.md, y yo me saltaba pasos. La propia documentación de Anthropic es honesta al respecto. Llama a las instrucciones de CLAUDE.md "advisory" y a los hooks "deterministic". Esa es la versión precisa de lo que yo estaba sintiendo. Leer una regla y seguir una regla no son lo mismo, ni para una IA ni para un humano cansado. Así que construí herramientas alrededor de los lugares donde esa brecha más importaba, una pieza a la vez, porque cada pieza surgió de algo que acababa de romperse.

El alcance, eventualmente

El alcance es el primer paso en mi flujo de trabajo ahora, pero no fue el primero que agregué. Se convirtió en el primer paso después de ver cómo la IA resolvía un objetivo distinto al que yo le había pedido, sobrediseñaba cambios que no necesitaban diseño, y buscaba la abstracción equivocada con suficiente frecuencia como para que yo necesitara un paso que simplemente detuviera el trabajo y nombrara lo que estábamos haciendo en realidad.

El alcance no son necesariamente especificaciones. Las especificaciones son el cómo. El alcance es qué estamos haciendo aquí, qué no estamos haciendo, y qué cuenta como terminado. Ahora corre antes que cualquier otra cosa, y verificaciones de alineación breves van con él a lo largo de las etapas siguientes para que el agente no derive hacia su propia versión del objetivo.

Me sorprendió la frecuencia con la que la primera oración que escribía en el alcance me hacía darme cuenta de que estaba a punto de construir la cosa equivocada.

La investigación y las guías

La investigación vino después. Empecé con frameworks locales para el trabajo de Drupal que hago mucho. Flujos de trabajo con el módulo ECA. Pipelines del módulo AI. Cada framework creció como crecen estas cosas, lleno de decisiones que había tomado, olvidado, y vuelto a tomar de forma diferente. Con el tiempo los frameworks se volvieron demasiado grandes para compartirlos con mi esposa. Ella no los habría leído, y yo no podía señalarle una parte sin arrastrar otras veinte.

Así que los desarmé. Una decisión por archivo. Una pregunta, una respuesta. Publicados en línea para que ambos pudiéramos acceder a ellos desde cualquier proyecto, y para que el agente pudiera traer solo lo que la tarea actual necesitaba. Eso son las guías atómicas. Alrededor de 1.600 ahora, distribuidas en 88 temas, con metadatos de enrutamiento que le permiten al agente decidir cuál leer para cada pregunta.

Eso funcionó, hasta que noté que la IA se perdía partes. No en las guías pequeñas. En las estructuradas, las que tienen secuencias y decisiones. Cuando le pides a la IA que lea una guía via WebFetch, el contenido se resume al entrar. Algunos pasos sobreviven. Otros se describen con un lenguaje más vago. Otros se pierden. El agente no sabe cuáles son cuáles.

Así que forcé curl. Bytes que entran, bytes que se leen. Sin capa de resumen entre el agente y el contenido. El skill que trae mis guías está construido alrededor de esta regla, y tres lugares distintos en su texto le recuerdan al agente por qué curl es obligatorio. La regla la hace cumplir el skill, no un hook, pero el skill se invoca en cada fetch, así que en la práctica se sostiene.

Diseño, implementación y mucho review

Después del alcance y la investigación vinieron el diseño y la implementación. Los patrones aquí son bien conocidos. Dividir el trabajo en fases. Definir criterios de aceptación antes de escribir. Hacer primero los tests cuando el test es más barato que el código que está verificando. Consultar al humano en cada paso que es difícil de revertir. Nada original. El valor está en la consistencia. La IA no hace esto sola a menos que yo haga el flujo de trabajo visible, así que lo hice visible.

Luego agregué review. Siete validadores, cada uno corriendo contra el diff y escribiendo una auditoría. Los checks de TDD verifican que los tests llegaron primero. SOLID y DRY capturan la deriva estructural. El escaneo de seguridad busca las clases de errores que la IA sabe cometer y los humanos saben no ver. El validador de guías verifica el trabajo contra las guías atómicas citadas en el diseño. La regresión visual y la paridad visual capturan la deriva en el output renderizado que los otros filtros pasarían por alto. Los agregué porque tests que pasan y buen código no son lo mismo, y he enviado suficientes diffs de aspecto limpio con problemas ocultos como para conocer la diferencia.

Las opiniones y el playbook

Luego me di cuenta de que necesitaba opiniones en una forma que el framework pudiera cargar. Algunas opiniones son reglas. Usa comandos drush, no PHP puro, cuando necesitas hacer algo en Drupal desde la línea de comandos. Usa Composer en el orden correcto cuando quitas un módulo. Breakpoints mobile-first con imágenes responsivas basadas en sizes para el cuerpo del contenido, basadas en breakpoints para heroes con art direction. Reglas. Una regla, aplicada en muchos contextos.

A esta capa la llamé el playbook, a nivel de proyecto. Las reglas locales siempre ganan en caso de conflicto. Conjuntos publicados a los que puedes suscribirte para los patrones que sigues usando entre proyectos. Eso funcionó. El agente dejó de buscar PHP puro cuando drush era la herramienta correcta, y dejó de elegir imágenes responsivas basadas en breakpoints para contenido del cuerpo donde las basadas en sizes eran la respuesta más limpia.

El muro

Trabajando en la herramienta más grande que todavía estoy construyendo, la que toma una definición de marca y llega hasta una app implementada, topé con un muro que tuve que nombrar.

Usar drush es una instrucción del playbook. Es una regla sobre cómo hacer una clase de cosas en este proyecto cuando estoy usando Drupal. Esa forma está bien. El playbook la sostiene bien.

Pero cómo configurar imágenes responsivas no es una regla. Es dirigir la orquestación de un objetivo específico en Drupal con IA. Lo primero es una sola instrucción, aplicada ampliamente. Lo segundo es un plan para una capacidad nombrada, aplicado una vez, de principio a fin, con decisiones específicas del proyecto integradas en el medio. Ambas son opiniones. No tienen la misma forma.

No tenía un artefacto para la segunda. El playbook cubre piezas. Hay incluso una entrada llamada responsive-image-sizing-per-context, que es una regla real que aplica de forma real. Pero la orquestación de extremo a extremo de wire-responsive-images-for-this-project vive en hilos de chat, donde yo guío al agente a través de la estrategia de imágenes del proyecto a mano. 16:9 a ancho completo para un hero. 16:9 en una tarjeta, misma proporción pero un image style diferente porque el tamaño renderizado es distinto. 4:3 portrait en otro lugar. Cada proyecto tiene su propia estrategia, y el agente tiene que traducirla en image styles, breakpoints y asignaciones de field display por view mode por content type. Sigo diciendo más o menos la misma secuencia con palabras ligeramente distintas, y el agente sigue haciendo más o menos lo mismo con una calidad ligeramente distinta.

La misma brecha aparece en otros lugares. Drupal tiene una receta de SEO declarativa que instala los módulos y configura defaults razonables, lo que funciona bien en proyectos donde los defaults coinciden con lo que necesitas. Pero en un proyecto donde el equipo quiere campos separados para metatag, Open Graph y Twitter cards por content type, la receta declarativa no puede tomar esa decisión por ti. Algo tiene que dirigir la orquestación para la forma específica de ese proyecto. Un front-end de Next.js conectado a un back-end de Drupal es la misma historia. Las guías atómicas cubren JSON:API, menús desacoplados, enrutamiento de contenido, y el procedimiento de extremo a extremo con las decisiones de este proyecto no tiene un artefacto donde vivir. El muro no es específico de las imágenes. Es la forma de la orquestación en sí.

Las recetas

De ahí las recetas. No es una guía, porque las guías son atómicas y una receta lleva orquestación sobre múltiples átomos. No es una entrada del playbook, porque eso es una sola regla, y una orquestación es por definición más de una decisión. No es un skill, porque un skill es algo que la IA instala, que vive en el front-matter del agente para cada sesión, sin importar si este proyecto necesita configurar imágenes responsivas o no. Una receta es algo que el agente lee cuando este proyecto necesita esta capacidad, y omite en caso contrario.

El modelo mental es directo. Las primeras diez líneas describen la feature, como el frontmatter de un skill, para que el agente pueda leer solo eso y decidir si seguir. Más o menos así:

recipe: responsive_image_wiring

describes: Wire Drupal responsive image styles, breakpoints, and field display modes from declared image use-cases per content type.

applies_when: project has image fields rendered across multiple breakpoints, art direction or resolution switching, or both.

requires: image, responsive_image, breakpoint

produces: image styles, responsive image styles, field display config per view mode per content type

Debajo de ese encabezado, el cuerpo. La opinión (cómo lo hacemos, qué nos negamos a hacer). La secuencia de pasos, cada uno citando su fuente atómica para que el agente traiga la decisión en lugar de adivinarla. El flujo de datos desde los inputs declarados hasta el estado aplicado en Drupal. El patrón de repetición (una vez, por content type, por view mode). El contrato sobre qué estado lee la receta antes de actuar. Las referencias, con la regla de curl respetada, para que el agente lea bytes y no resúmenes.

Se carga bajo demanda. No se instala. Se actualiza cuando los módulos y el core sobre los que se apoya la receta cambian, porque llevo suficiente tiempo refinando mis guías atómicas a mano como para saber que el mismo mantenimiento aplica un nivel más arriba. Ahora mismo estoy integrando la automatización de actualizaciones en mi propia configuración, pero el formato es lo que importa. El formato tiene que permitir esa automatización para cualquiera que quiera construirla, no depender de que una sola persona sea su dueña.

Hago esto en Drupal porque Drupal es mi comunidad. El patrón es el mismo en cualquier lugar donde haya una capa de capacidades estable sobre APIs atómicas. Next.js. Rails. Sistemas de diseño. Cualquier lugar donde la orquestación de una feature nombrada sea repetible pero las decisiones dentro de ella sean específicas del proyecto.

Comparto esto para ver si resuena. Construí cada capa de mis herramientas porque algo se rompía cuando no la tenía, y las recetas son la pieza más reciente en esa secuencia. Planes de orquestación para capacidades nombradas. Cargados bajo demanda. Sin instalar. Me gustaría saber si otras personas que corren IA en proyectos reales están topando con el mismo muro, ese donde puedes sentir la diferencia entre una regla y una orquestación pero no tienes un artefacto para sostener la segunda. Si lo estás viviendo, me gustaría escucharte.