🏗 Setup do Orchestrator
O GitHub Issue Bot usa uma sessao principal de Claude Code como orchestrator que despacha 4 workflows paralelos. Cada workflow e uma sessao independente que recebe uma issue, implementa o fix, roda testes e cria o PR.
"We can use Archon to send off workflows to run in parallel, handling multiple GitHub issues at the exact same time. And this is very much like loop engineering because we have our primary cloud code here as our orchestrator."
📋 Prompt do 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 Isolamento
Quando multiplos workers editam codigo em paralelo, eles precisam de isolamento total. Git worktrees resolvem isso: cada worker opera em seu proprio checkout do repositorio, com sua branch separada.
"Work trees are also a really important part of loop engineering. Boris talks about this as well. If we're having many different agents handling tasks in a loop, we need to make sure they're running in isolation so they're not stepping on each other's toes."
💻 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
💾 Database Branches com Neon
Isolamento de codigo (worktrees) resolve metade do problema. A outra metade e isolamento de dados. Neon permite criar branches do banco Postgres para cada worker, evitando que migracoes e dados de teste conflitem.
"One thing that you have to do a lot is branches in your database. If each coding agent is working on something in parallel, you don't want them to be stepping on each other's toes, not just with code changes, but also database changes. So work trees and Neon is a super powerful thing."
🗄 Branch 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
🎯 Ponto de Reflexao
Database branches sao essenciais quando os workers fazem migracoes ou alteram schema. Sem isso, um worker pode quebrar o banco que outro esta usando. Neon torna isso trivial, mas qualquer sistema de branching de banco (PlanetScale, Supabase branching) resolve.
🔄 Fluxo Completo: Issue ate PR
Cada worker segue um pipeline deterministico de 7 steps. O processo e fixo (o humano define os steps), mas cada step usa um LLM para executar. Isso combina o melhor de loops e workflows deterministicos.
"Another really important thing with Archon is that we're not having the agent drive the entire thing. It's more deterministic because we set up the process in this workflow file."
🔧 Pipeline do Worker (7 Steps)
Extract issue number
Deterministico: parse do input para obter issue ID
Fetch issue context
GitHub API: titulo, descricao, labels, comentarios
Classify (bug vs feature)
LLM pequeno (Haiku/Kimi): decide o tipo de issue
Research
LLM medio: investiga codebase, identifica arquivos relevantes
Implement
LLM forte (Claude): escreve o codigo do fix
Validate
Deterministico: roda testes, lint, type check
Create PR
Deterministico: git push + gh pr create
💰 Mix de Modelos por Step
Uma das maiores vantagens de workflows deterministicos sobre loops puros e a capacidade de usar modelos diferentes em cada step. Isso reduz custo drasticamente sem sacrificar qualidade onde ela importa.
"One of the other big issues I see with using slash goal or routines or loops in cloud code is you're just using one model for pretty much everything. That's part of the problem of why it's so expensive."
🎯 Mapa de Modelos por Step
| Step | Modelo | Justificativa |
|---|---|---|
| Extract / Fetch | Deterministico | Sem LLM, puro codigo |
| Classify | Haiku / Kimi K2.7 | Decisao simples, modelo barato |
| Research | Kimi K2.7 | Exploracao, modelo medio |
| Implement | Claude Code | Precisa de qualidade maxima |
| Validate | Deterministico | Roda testes, sem LLM |
| Review | Codex / Claude | Code review precisa de raciocinio |
❓ Questionamentos
O issue bot e poderoso, mas nao e magico. Questoes reais que surgem na pratica.
Custo real de 4 issues em paralelo
Cole reporta que um unico run com orchestrator + workers custou mais de 1 milhao de tokens. Com 4 em paralelo, multiplique. O mix de modelos ajuda, mas o custo ainda e significativo para quem nao tem budget infinito.
Qualidade dos PRs gerados
PRs automaticos precisam de revisao humana. O code review por agente ajuda, mas Cole enfatiza o human-in-the-loop: "we can always have it pause for us to validate something before it continues."
Quando vale vs. quando nao vale
Para batch de issues simples (typos, updates de deps, refactorings padrao), vale muito. Para issues complexas que exigem design thinking, o agente vai produzir fixes superficiais. Use com criterio.
🎯 Ponto de Reflexao
O issue bot e a ponte entre o loop simples (modulo 4.1) e o orchestrator multi-agent (modulo 4.3). Ele introduz paralelismo, isolamento e mix de modelos. Quando voce dominar esses conceitos, o salto para o multi-agent sera natural.
📋 Resumo do Modulo
Proximo Modulo:
4.3 -- Loop Avancado: Orchestrator Multi-Agent (spec, rounds, HITL)