🏗 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."
📋 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
🌳 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í."
💻 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
💾 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."
🗄 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.
🔄 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."
🔧 Pipeline del worker (7 steps)
Extract issue number
Determinista: analiza el input para obtener el ID de la issue
Fetch issue context
GitHub API: título, descripción, labels, comentarios
Clasificar (error o funcionalidad)
LLM pequeño (Haiku/Kimi): decide el tipo de issue
Research
LLM intermedio: investiga el codebase e identifica los archivos relevantes
Implement
LLM potente (Claude): escribe el código del fix
Validate
Determinista: ejecuta pruebas, lint y type check
Crear PR
Determinista: git push + gh pr create
💰 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."
🎯 Mapa de modelos por step
| Paso | Modelo | Justificación |
|---|---|---|
| Extract / Fetch | Determinista | Sin LLM, solo código |
| Clasificar | Haiku / Kimi K2.7 | Decisión sencilla, modelo barato |
| Research | Kimi K2.7 | Exploración, modelo medio |
| Implement | Claude Code | Necesita la máxima calidad |
| Validate | Determinista | Ejecuta pruebas, sin LLM |
| Review | Codex / Claude | La revisión de código requiere razonamiento |
❓ 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
Módulo siguiente:
4.3 -- Ciclo avanzado: Orchestrator Multi-Agent (spec, rounds, HITL)