PTENES
MÓDULO 4.2

🐛 Loop intermedio: bot de issues de GitHub

Un orchestrator distribuye workflows paralelos para resolver 4 GitHub issues simultáneamente, con worktrees y database branches.

6
Temas
30
Minutos
Intermedio.
Nivel
Práctica
Tipo
1

🏗 Configuración del Orchestrator

El GitHub Issue Bot usa una sesión principal de Claude Code como orchestrator que envía 4 workflows paralelos. Cada workflow es una sesión independiente que recibe una issue, implementa el fix, ejecuta pruebas y crea el PR.

"Podemos usar Archon para poner en marcha workflows en paralelo y gestionar varios issues de GitHub exactamente al mismo tiempo. Esto se parece mucho a la ingeniería con loops porque aquí tenemos nuestro cloud code principal como orquestador."
-- Cole Medin

📋 Prompt del orchestrator

You are the orchestrator for a GitHub issue fixing system.

1. Read the list of open issues from the GitHub API
2. For each issue, dispatch a worker workflow in a separate worktree
3. Each worker will: extract context, classify (bug/feature), implement, validate, create PR
4. Monitor all workers. When all PRs are ready, dispatch review workflows
5. Report final status with PR links

Issues to handle: #42, #45, #51, #58
Orchestrator Claude Code (sesión principal) Worker #42worktree-42 Worker #45worktree-45 Worker #51worktree-51 Worker #58worktree-58 PR #42 PR #45 PR #51 PR #58 Validate + Review 9+ sesiones de agente: 1 orquestador + 4 fix + 4 review
2

🌳 Worktrees para aislamiento

Cuando varios workers editan código en paralelo, necesitan aislamiento total. Git worktrees resuelven esto: cada worker opera en su propio checkout del repositorio, con una branch separada.

"Los work trees también son una parte muy importante de la ingeniería con loops. Boris también habla de esto. Si muchos agentes gestionan tareas dentro de un loop, tenemos que asegurarnos de que se ejecuten de forma aislada para que no se estorben entre sí."
-- Cole Medin

💻 Comandos de worktree

# Criar worktree para cada issue
git worktree add ../worktree-42 -b fix/issue-42
git worktree add ../worktree-45 -b fix/issue-45
git worktree add ../worktree-51 -b fix/issue-51
git worktree add ../worktree-58 -b fix/issue-58

# Cada worker roda em seu diretorio
cd ../worktree-42 && claude --prompt "Fix issue #42..."

# Limpar apos merge
git worktree remove ../worktree-42
3

💾 Ramas de base de datos con Neon

El aislamiento del código (worktrees) resuelve la mitad del problema. La otra mitad es aislamiento de datos. Neon permite crear branches de la base de datos Postgres para cada worker, lo que evita conflictos entre migraciones y datos de prueba.

"Algo que tienes que hacer mucho es crear ramas en tu base de datos. Si cada agente de programación trabaja en algo en paralelo, no quieres que se estorben entre sí, no solo con los cambios de código, sino también con los cambios en la base de datos. Por eso los work trees y Neon son algo muy potente."
-- Cole Medin

🗄 Rama por worker

# Criar branch de banco para cada worker (via Neon CLI)
neonctl branches create --name worker-42 --parent main
neonctl branches create --name worker-45 --parent main

# Cada worker recebe sua DATABASE_URL isolada
export DATABASE_URL=$(neonctl connection-string --branch worker-42)

# Apos merge do PR, deletar branch
neonctl branches delete worker-42

🎯 Punto de reflexión

Las database branches son esenciales cuando los workers hacen migraciones o modifican el schema. Sin ellas, un worker puede dañar la base de datos que otro está usando. Neon lo hace muy sencillo, pero cualquier sistema de branching de bases de datos (PlanetScale, Supabase branching) resuelve el problema.

4

🔄 Flujo completo: desde la issue hasta el PR

Cada worker sigue un pipeline determinista de 7 pasos. El proceso es fijo (la persona define los pasos), pero cada paso usa un LLM para ejecutarse. Esto combina lo mejor de los loops y los workflows deterministas.

"Otra cosa muy importante de Archon es que no dejamos que el agente se encargue de todo el proceso. Es más determinista porque configuramos el proceso en este archivo de flujo de trabajo."
-- Cole Medin

🔧 Pipeline del worker (7 steps)

1

Extract issue number

Determinista: analiza el input para obtener el ID de la issue

2

Fetch issue context

GitHub API: título, descripción, labels, comentarios

3

Clasificar (error o funcionalidad)

LLM pequeño (Haiku/Kimi): decide el tipo de issue

4

Research

LLM intermedio: investiga el codebase e identifica los archivos relevantes

5

Implement

LLM potente (Claude): escribe el código del fix

6

Validate

Determinista: ejecuta pruebas, lint y type check

7

Crear PR

Determinista: git push + gh pr create

5

💰 Combinación de modelos por step

Una de las mayores ventajas de los workflows deterministas frente a los loops puros es la capacidad de usar modelos diferentes en cada step. Esto reduce drásticamente el costo sin sacrificar la calidad donde importa.

"Otro de los grandes problemas que veo al usar slash goal, rutinas o loops en cloud code es que usas un solo modelo para prácticamente todo. Eso es parte del motivo por el que resulta tan caro."
-- Cole Medin

🎯 Mapa de modelos por step

PasoModeloJustificación
Extract / FetchDeterministaSin LLM, solo código
ClasificarHaiku / Kimi K2.7Decisión sencilla, modelo barato
ResearchKimi K2.7Exploración, modelo medio
ImplementClaude CodeNecesita la máxima calidad
ValidateDeterministaEjecuta pruebas, sin LLM
ReviewCodex / ClaudeLa revisión de código requiere razonamiento
6

❓ Preguntas

El issue bot es potente, pero no es mágico. Preguntas reales que surgen en la práctica.

Costo real de 4 issues en paralelo

Cole reporta que una sola ejecución con orchestrator + workers costó más de 1 millón de tokens. Con 4 en paralelo, multiplica esa cifra. La combinación de modelos ayuda, pero el costo sigue siendo significativo para quien no tiene presupuesto infinito.

Calidad de los PR generados

Los PR automáticos necesitan revisión humana. La revisión de código por agentes ayuda, pero Cole enfatiza la participación humana en el proceso: "we can always have it pause for us to validate something before it continues."

Cuándo vale la pena y cuándo no

Para lotes de issues simples (errores tipográficos, actualizaciones de dependencias, refactorizaciones estándar), vale mucho la pena. Para issues complejas que requieren pensamiento de diseño, el agente producirá fixes superficiales. Úsalo con criterio.

🎯 Punto de reflexión

El issue bot es el puente entre el loop simple (módulo 4.1) y el orchestrator multi-agent (módulo 4.3). Introduce paralelismo, aislamiento y una combinación de modelos. Cuando domines estos conceptos, el salto al multi-agent será natural.

📋 Resumen del módulo

✓
Orchestrator -- sesión principal que despacha y monitorea workers
✓
Worktrees -- aislamiento del código para workers paralelos
✓
Branches de Neon -- aislamiento de la base de datos por worker
✓
Pipeline de 7 pasos -- extract, fetch, classify, research, implement, validate, PR
✓
Combinación de modelos -- el modelo adecuado para cada step reduce el costo

Módulo siguiente:

4.3 -- Ciclo avanzado: Orchestrator Multi-Agent (spec, rounds, HITL)