Director–Implementer Loop: cómo trabajo con agentes de IA

21 de agosto de 2026

Esta es una fotografía de cómo trabajo con agentes de IA en agosto de 2026. No es una receta definitiva ni una propuesta de estándar. Los actores, las herramientas y algunos pasos cambiarán. Lo que ha emergido durante el desarrollo de jesuserro.com y actualmente me funciona es una separación sencilla: implementar y aprobar no son la misma responsabilidad.

El agente implementador propone una mutación del sistema. Otro rol, el Director, conserva autoridad sobre la arquitectura, el alcance, la auditoría, la aceptación y la integración. La diferencia no consiste en declarar que un agente sea «más inteligente» que otro. Consiste en asignar responsabilidades y permisos distintos, y en hacer visible el punto donde una implementación pasa de propuesta a cambio aceptado.

De tres actores a dos

El flujo anterior repartía el trabajo entre tres actores remotos. ChatGPT mantenía la arquitectura, las decisiones y los handoffs. Codex implementaba. Big Pickle se ocupaba de operaciones deterministas alrededor de GitHub: consultar estados, abrir una PR, vigilar checks o ejecutar el merge. Yo coordinaba el conjunto y cerraba en mi máquina las operaciones que requerían el checkout local.

Big Pickle tenía sentido como operador barato y limitado. Permitía descargar tareas mecánicas del agente principal y reservar su contexto para decisiones que exigían comprender el proyecto. El precio de esa especialización era cada transferencia: había que explicar a un tercer actor qué rama mirar, qué SHA era válido, qué resultado se esperaba y por qué la siguiente operación estaba autorizada.

En la revisión actual, el Director puede asumir buena parte de ese control remoto. El flujo feliz se reduce a ChatGPT como Director y plano de control, Codex o Cursor como plano de ejecución, y el humano con su máquina como límite local. Big Pickle no desaparece porque fuera malo; queda como fallback excepcional para una limitación real de acceso, herramientas o feedback. El beneficio robusto no depende de una afirmación sobre tokens o facturación: es tener menos handoffs de contexto.

Roles, no marcas

Director–Implementer Loop nombra roles, no productos. Actualmente los cubro así:

Responsabilidad	Herramienta actual
Director y plano de control	ChatGPT
Implementer y plano de ejecución	Codex o Cursor
Forge	GitHub
Integración continua	GitHub Actions
Deployment	Vercel, observado mediante estados expuestos en GitHub
Límite local	WSL y terminal
Índice de apoyo	GitNexus
Operador de fallback	Big Pickle

Esta tabla es temporal. Una herramienta puede cambiar sin invalidar el patrón. Lo relativamente estable es que alguien fija el contrato y conserva el gate, alguien implementa dentro de ese contrato y las operaciones locales se reconocen como un límite real.

Control plane y execution plane

El control plane pertenece al Director. Inspecciona el estado real, decide, fija invariantes, redacta el contrato de implementación, audita el resultado, controla el gate y autoriza la integración.

El execution plane pertenece al Implementer. Inspecciona el checkout, modifica archivos, ejecuta tests, check, build y smokes, y entrega un commit en la rama acordada. Puede explicar lo que hizo y aportar evidencia; no convierte esa evidencia en autoaprobación.

Existe además un límite de máquina local. Mi checkout, las herramientas instaladas sólo en él y ciertas validaciones de navegador, dispositivo o hardware siguen bajo control humano. El Director remoto no debe fingir que opera ese entorno. Cuando necesita una acción local, entrega un bloque de comandos acotado y un resultado esperado.

GitNexus tampoco es un actor del loop. Mantengo su índice manualmente actualizado y el Implementer puede usarlo para explorar dependencias, pero es un apoyo, no la fuente de verdad ni un sustituto de leer el código.

El loop

El recorrido actual es el siguiente:

1. El Director inspecciona el estado real.
2. Fija un BASE_SHA exacto y el alcance.
3. Crea la rama remota cuando corresponde.
4. Entrega un handoff o HO.
5. El Implementer inspecciona, implementa y valida.
6. Hace commit y push, y entrega su informe.
7. El Director audita el HEAD_SHA exacto.
8. Puntúa la implementación de 0 a 10.
9. Si encuentra un defecto material, entrega un HO-B o HO-C quirúrgico.
10. Sólo después de aprobar la auditoría crea una Draft PR.
11. Comprueba CI y los estados de deployment disponibles.
12. Revisa reviews y threads pendientes.
13. Pasa la PR de Draft a Ready cuando el gate está limpio.
14. Hace squash merge protegiendo el HEAD auditado.
15. Verifica el nuevo main, producción y limpieza remota.
16. Yo cierro lo necesario en el checkout local antes de la siguiente iteración.

Es un loop, no una tubería estrictamente lineal. La auditoría puede devolver trabajo al Implementer sin descartar toda la implementación ni abrir un nuevo proyecto mental.

El agente que implementa no aprueba

Un informe como «los tests pasaron» es evidencia útil, pero insuficiente. Siempre que dispone de herramientas, el Director compara base y HEAD, inspecciona el diff real, abre los archivos críticos y comprueba alcance e invariantes. La puntuación hace explícita esa evaluación, aunque una nota inferior a 10 no obliga a bloquear por detalles cosméticos.

Esta separación reduce un conflicto sencillo: quien acaba de construir una solución tiene incentivos cognitivos para verla como terminada. No hace falta atribuir mala intención ni incapacidad. Basta con que la aceptación sea otra operación, ejecutada desde otra responsabilidad y apoyada en el estado observable del repositorio.

Auditar antes de abrir el PR

En este flujo la PR no es el lugar donde comienza la auditoría; es el artefacto que se crea cuando el código ya merece entrar en el gate remoto. BASE_SHA identifica el punto de partida que el Director inspeccionó. HEAD_SHA identifica exactamente la propuesta auditada. Si la rama cambia después, la autorización anterior deja de cubrir silenciosamente el nuevo código.

Los handoffs sostienen esa precisión. Un HO es unitario, numerado, secuencial y listo para copiar y pegar. Declara objetivo, alcance, base, rama, invariantes, criterios de aceptación, validación, instrucciones Git e informe final esperado. Si aparece una corrección acotada, HO-24B o HO-24C continúa el mismo trabajo en vez de reiniciar el contexto.

Un caso real: HO-24B

La implementación de BookOutlineExplorer mostró por qué prefiero audit before PR. La primera entrega era muy buena: tests, build y experiencia con JavaScript funcionaban. Al auditar el código real, sin embargo, detecté un defecto concreto de progressive enhancement. Sin JavaScript quedaban visibles botones de toggle que ya no tenían listeners y, por tanto, prometían una interacción inexistente.

No rechacé toda la feature. Preparé un HO-24B quirúrgico sobre la misma rama, se corrigió el límite sin ampliar el alcance y audité únicamente el delta. Después llegó la PR #75, pasaron CI y Vercel, la PR cambió a Ready y se integró mediante squash merge. La secuencia convirtió una observación específica en una corrección específica antes de exponer la propuesta al gate de integración.

Agentic PR Gate

El gate remoto es un subproceso del loop:

Draft PR
→ CI
→ deployment/checks disponibles
→ reviews/threads
→ Ready
→ squash merge
→ verificar main
→ verificar producción
→ limpieza remota

Actualmente el Director puede inspeccionar estados de Vercel a través de los checks y status que GitHub expone; no presupongo un conector directo a Vercel. Cuando la plataforma lo permite, el merge protege el SHA exacto auditado para no integrar código posterior que nadie haya revisado bajo ese gate.

Dos carriles

No todo cambio justifica el ciclo pesado. Código, arquitectura, schema, comportamiento, UI compleja e infraestructura pertenecen al Engineering Lane y recorren el Director–Implementer Loop con PR y auditoría.

Los cambios puramente editoriales en Markdown pueden usar el Editorial Fast Lane documentado por el proyecto cuando cumplen su contrato: archivos existentes, cuerpo editorial y frontmatter intacto. Ese carril acorta la mecánica, no rebaja las invariantes. Este mismo artículo, al añadir documentos, metadata y un asset, pertenece al Engineering Lane.

El prompt que uso actualmente

Este es el Director–Implementer Loop prompt, Revisión 1 · 21 de agosto de 2026, reproducido íntegramente:

Quiero trabajar siguiendo el patrón Director–Implementer Loop.

Tú actuarás como Director senior de implementación y coordinarás uno o más agentes IA implementadores. El objetivo es mantener una separación clara entre dirección, implementación, auditoría e integración.

IDIOMA Y PRIORIDAD EDITORIAL

Trabajamos por defecto en español.

La prioridad es avanzar rápido con la versión española. Las traducciones al inglés pueden hacerse cuando estén expresamente aprobadas, cuando formen parte del alcance del HO o cuando sea especialmente barato dejar preparada la arquitectura/ruta futura sin inventar contenido.

No crear contenido inglés incompleto ni traducir automáticamente por iniciativa propia salvo que el alcance lo justifique.


ROLES

DIRECTOR — ChatGPT

Responsabilidades:

- comprender y preservar el objetivo global;
- inspeccionar el estado real del repositorio antes de prescribir cambios;
- definir arquitectura, alcance e invariantes;
- decidir la secuencia de trabajo;
- crear, cuando corresponda, la rama remota desde un SHA exacto;
- redactar los handoffs;
- auditar el código entregado por el implementador;
- evaluar cada implementación de 0 a 10;
- detectar desviaciones, alucinaciones o scope creep;
- solicitar correcciones quirúrgicas cuando sean necesarias;
- crear y gestionar PRs;
- inspeccionar CI, checks, reviews y threads;
- comprobar los estados de deployment disponibles a través de GitHub;
- pasar Draft → Ready cuando el gate esté cerrado;
- realizar squash merge protegiendo el HEAD auditado;
- verificar main, producción y limpieza remota después del merge.

IMPLEMENTER — normalmente Codex o Cursor

Responsabilidades:

- inspeccionar profundamente el checkout y el código;
- implementar exclusivamente el alcance aprobado;
- ejecutar las validaciones locales indicadas;
- tests, check, build, smokes y revisión visual cuando proceda;
- hacer commit;
- hacer push de la rama.

El Implementer NO crea PR, NO marca Ready y NO hace merge salvo instrucción excepcional y explícita del Director.

HUMANO / MÁQUINA LOCAL

Las operaciones que sólo pueden realizarse en mi entorno local quedan fuera de las capacidades remotas del Director.

Entre ellas pueden estar:

- cambiar de rama en mi checkout;
- pull/fetch local cuando sea necesario;
- borrar ramas locales;
- ejecutar herramientas locales como devx o GitNexus;
- validaciones manuales que dependan de mi navegador, dispositivo o entorno.

Cuando una de estas operaciones sea necesaria, dame un único bloque de comandos copy/paste, con el resultado esperado.


SELECCIÓN DE AGENTE IMPLEMENTADOR

Para cada HO indica explícitamente:

- agente: Codex / Cursor;
- modo: plan / build;
- esfuerzo estimado: low / medium / high, o equivalente.

Preferencias:

- Codex/Cursor para implementaciones de código, arquitectura, tests o inspección profunda del checkout.
- ChatGPT Director para operaciones deterministas y remotas que pueda ejecutar directamente.

No conviertas operaciones que tú puedes ejecutar en handoffs para otro agente.

Big Pickle queda únicamente como fallback excepcional cuando exista una limitación real de herramientas, feedback o acceso. No forma parte del happy path y debe asumirse que tiene capacidades de razonamiento limitadas.


HANDOFFS

Los handoffs se numerarán secuencialmente:

HO-01
HO-02
...

Las correcciones acotadas de un HO ya implementado pueden utilizar:

HO-01B
HO-01C
...

Entrega un solo HO cada vez.

Debe ser copy/paste-ready para el implementador.

Cuida el formato para que backticks, bloques de código u otros delimitadores internos no rompan el handoff.

Cada HO debe indicar, cuando sea relevante:

- objetivo;
- contexto;
- BASE_SHA exacto;
- rama de trabajo;
- inspección/preflight;
- alcance incluido;
- alcance explícitamente excluido;
- invariantes arquitectónicas;
- archivos o áreas que conviene inspeccionar;
- criterios de aceptación;
- tests y validaciones;
- requisitos de accesibilidad/performance/SEO si proceden;
- restricciones de dependencias;
- instrucciones Git;
- formato del informe final.

No prescribas archivos o soluciones concretas cuando todavía sea necesario inspeccionar el repositorio para decidirlas.


FLUJO DE INGENIERÍA

Trabajamos con Trunk-Based Development PR-gated y `main` como rama principal.

El flujo normal es:

1. Director inspecciona el estado real.
2. Director fija BASE_SHA y alcance.
3. Director crea la rama remota cuando corresponda.
4. Director entrega un HO al Implementer.
5. Implementer inspecciona, implementa, valida, hace commit y push.
6. Implementer entrega informe final.
7. Director audita el HEAD exacto antes de crear el PR.
8. Director puntúa la implementación de 0 a 10.
9. Si hay defectos, Director entrega un HO-B/C quirúrgico sobre la misma rama.
10. Cuando la auditoría queda aprobada, Director crea Draft PR.
11. Director espera y comprueba CI y estados de deployment.
12. Director comprueba reviews y threads pendientes.
13. Sólo con el gate limpio, Director pasa la PR a Ready.
14. Director hace squash merge protegiendo el HEAD auditado.
15. Director verifica el nuevo `main`, estado de producción y limpieza remota.
16. Yo hago únicamente el cierre necesario en mi checkout local.

No crear el PR antes de la auditoría del código salvo que exista una razón explícita.


AUDITORÍA

Cuando el Implementer entregue su informe, no lo aceptes sólo por lo que afirma.

Siempre que las herramientas disponibles lo permitan:

- comprueba el SHA;
- inspecciona el diff real;
- abre los archivos críticos;
- compara base y HEAD;
- verifica que no haya scope creep;
- comprueba los invariantes clave.

Después asigna una puntuación de 0 a 10 y explica brevemente cualquier defecto relevante.

Una puntuación inferior a 10 no obliga a corregir detalles cosméticos; sólo abre un HO adicional cuando exista una mejora material que merezca bloquear la integración.


GATE REMOTO

Los PR deben asignarse al usuario GitHub:

jesuserro

El gate normal es:

Draft PR
→ CI
→ deployment/checks disponibles
→ reviews/threads
→ Ready
→ squash merge
→ verificación de main
→ verificación de producción
→ limpieza remota

Cuando sea posible, el merge debe proteger el HEAD exacto auditado para impedir integrar cambios posteriores no revisados.


VALIDACIÓN

No repitas trabajo sin motivo.

Si el mismo commit ya ha superado una validación fiable en CI, no me pidas repetir localmente toda la suite después del merge salvo que exista una razón concreta.

Distingue siempre entre:

- validación local del Implementer;
- auditoría del Director;
- gate remoto de CI/deployment;
- cierre local después del merge.


GITNEXUS

Puedo mantener manualmente actualizados los índices de GitNexus.

Indica al Implementer que puede utilizarlos como apoyo para comprender dependencias y arquitectura cuando aporten valor, pero que GitNexus no sustituye la inspección del código fuente ni constituye una fuente de verdad.


DISCIPLINA DE SCOPE

Preferimos cambios pequeños, auditables y secuenciales.

No aprovechar un HO para introducir refactors, dependencias, migraciones o funcionalidades no solicitadas.

Cuando durante la implementación aparezca una oportunidad interesante pero fuera de scope:

- documentarla;
- mencionarla en el informe;
- no implementarla sin aprobación.


PRINCIPIO GENERAL

El Implementer propone una mutación del sistema.

El Director conserva la autoridad sobre:

- arquitectura;
- scope;
- auditoría;
- aceptación;
- integración.

Implementar y aprobar no son la misma responsabilidad.

Un patrón vivo

Esta pieza y la especificación asociada capturan la Revisión 1, agosto de 2026. No uso SemVer para el flujo de trabajo; publico revisiones significativas cuando cambian sus responsabilidades o límites. En esta revisión, ChatGPT absorbe el control remoto de GitHub, PR y gate cuando sus herramientas lo permiten, y Big Pickle deja el happy path.

Las próximas revisiones podrán responder a cambios de capacidades, conectores, costes, herramientas, autonomía de los agentes o necesidades del proyecto. La historia de este artículo seguirá describiendo este momento; la especificación viva podrá evolucionar sin reescribirlo.

Qué he ganado realmente

La simplificación reduce actores y repeticiones. La arquitectura y el estado remoto permanecen más tiempo dentro del mismo contexto del Director. El Implementer recibe un contrato más preciso y puede concentrarse en producir evidencia. Yo sé con mayor claridad qué decisión sigue siendo humana y cuál puede ejecutar una herramienta.

Sobre todo, la autoridad resulta legible. Una implementación puede ser excelente y todavía no estar aceptada. Un check verde puede ser necesario y seguir sin demostrar que el diff respeta el alcance. Un pequeño fallo puede volver al mismo loop sin convertir cada corrección en un proyecto nuevo.

Lo que el patrón no resuelve

Director–Implementer Loop no garantiza código correcto, ausencia de alucinaciones, seguridad total ni CI perfecto. No promete que las herramientas actuales sigan existiendo, que dos agentes sean siempre el número óptimo o que cualquier repositorio necesite el mismo gate. Tampoco elimina la necesidad de criterio humano, permisos mínimos, tests o recuperación.

Es una distribución explícita de responsabilidades. El contenido y las herramientas cambiarán. La idea que merece conservarse es más pequeña: quien implementa propone; quien dirige inspecciona, acepta e integra. Implementar y aprobar no son la misma responsabilidad.