Como uma IA coordena meus agentes de código
Meu fluxo com Orca, worktrees, skills e MCPs, com revisão e merge humano.
Neste post
Eu continuo construindo software todos os dias, mas já não preciso digitar cada linha sozinho. Hoje passo mais tempo definindo tarefas, preparando o contexto e revisando o que os agentes fizeram.
Claude Code e Codex CLI trabalham em cópias isoladas do repositório dentro do Orca. Uma terceira sessão acompanha as tarefas no Linear, prepara os briefings e responde boa parte das dúvidas. Eu continuo responsável pelas decisões de produto, pela revisão e pelo merge.
Este post explica como montei esse fluxo, quais peças uso e onde ele ainda falha. É o sistema que roda na minha workstation hoje, incluindo os problemas que fui encontrando no caminho.
Do chat ao agente dentro do repositório#
Meu primeiro uso de IA para programar era o mais comum: fazia uma pergunta no chat, copiava a resposta para o editor e, quando aparecia um erro, levava o erro de volta para o chat.
Esse jeito funciona para tarefas pequenas, mas depende de uma pessoa transportando o contexto o tempo todo. O modelo só conhece o que foi colado na conversa, não vê o restante do repositório e não consegue confirmar sozinho se o código compilou ou se os testes passaram.
Um agente de código muda essa dinâmica porque pode ler arquivos, editar o projeto, rodar comandos e usar o resultado como feedback para a próxima tentativa. Para isso, o modelo precisa de um ambiente preparado ao redor dele.
Foi aí que comecei a prestar mais atenção no harness, nas regras do repositório e no isolamento entre tarefas. O modelo continua importante, mas o resultado depende muito do acesso, do contexto e das verificações que ele recebe.
As peças do fluxo#
Não existe uma ferramenta única que resolva tudo. Meu setup combina algumas peças, cada uma com uma função bem definida.
Harness#
O harness é o programa que conecta o modelo ao ambiente de desenvolvimento. Ele permite ler arquivos, executar comandos, editar código e repetir o processo depois de um erro. Claude Code e Codex CLI são os dois que uso.
É também o que transforma uma conversa em uma execução contínua. O agente escreve, roda o teste, lê a falha, corrige e tenta de novo sem precisar que eu copie cada resultado entre ferramentas.
MCP#
MCP, ou Model Context Protocol, é o padrão que uso para conectar ferramentas e fontes de dados ao agente. Meu orquestrador, por exemplo, lê uma issue do Linear sem que eu precise copiar o conteúdo para o prompt.
Cada integração ocupa contexto e pode consumir bastante memória. Um MCP de browser headless chegou a abrir um Chrome de aproximadamente 470 MB, então tirei os MCPs de browser da configuração padrão. Deixo conectado apenas o que participa do fluxo.
Skills#
Uma skill é um procedimento reutilizável. Em vez de explicar o mesmo checklist em toda tarefa, deixo as instruções em um arquivo que o agente carrega quando precisa.
Uso skills para revisão de interface, entrevista de requisitos e criação de specs de integração. Isso deixa o processo mais consistente sem manter todas as regras na janela de contexto o tempo inteiro.
Git worktrees#
Git worktree cria várias cópias de trabalho ligadas ao mesmo repositório. Cada tarefa recebe sua própria worktree, branch e terminal.
Esse isolamento permite manter quatro agentes trabalhando ao mesmo tempo sem que um altere os arquivos do outro. Os conflitos ainda podem aparecer no merge, mas não durante a implementação de cada tarefa.
Plan mode e permissões#
Nenhum agente começa a implementar antes de apresentar um plano. Eu ou o orquestrador revisamos as decisões que mudam o resultado e só então liberamos a execução.
Também restrinjo comandos destrutivos e arquivos de alto impacto. Esse controle adiciona alguns minutos ao início da tarefa, mas evita descobrir uma interpretação errada depois de um diff inteiro pronto.
Regras versionadas no repositório#
As regras ficam no próprio repositório. O arquivo canônico é o AGENTS.md, com um
espelho em CLAUDE.md. Ali registro decisões de arquitetura, ações proibidas,
invariantes e arquivos que exigem confirmação antes de uma edição.
Também guardo detalhes do ambiente que costumam causar erro, como a porta usada pelo Postgres local. Quando uma sessão nova começa, essas informações já estão disponíveis e não dependem da memória de uma conversa anterior.
O Orca no dia a dia#
Todas essas peças ficam reunidas no Orcaabre em nova aba. Ele é um Agent Development Environment, uma IDE pensada para acompanhar vários agentes e worktrees em paralelo. O projeto é open source sob licença MIT, mantido pela stablyai, e roda em macOS, Windows e Linux. Também existe um modo headless para uso em VPS por SSH.
Cada worktree recebe terminal próprio, splits, scrollback persistente, um browser Chromium embutido e uma visão de diff com comentários por linha. Na tela principal, cada tarefa aparece como um card com o estado atual. Consigo revisar, commitar e preparar o merge sem trocar de aplicativo.
Os recursos que mais uso são:
- Agentes CLI diferentes. O Orca aceita Claude Code, Codex, Cursor, OpenCode e mais de 30 opções. Cada uma usa a própria assinatura e entra por configuração.
- Fan-out. Um prompt pode ser enviado para até cinco agentes, cada um em sua worktree. Depois é possível comparar os diffs e escolher hunks de cada solução. Uso isso apenas quando quero comparar abordagens para uma decisão difícil.
- Design Mode. No browser embutido, seleciono um elemento da página e envio ao agente o HTML, o CSS computado e um recorte da tela. Isso reduz bastante a descrição manual em tarefas de frontend.
- Integração com trackers. Linear e GitHub podem criar worktrees a partir de issues. No meu fluxo, o orquestrador usa o MCP do Linear, mas o caminho manual também existe.
- CLI scriptável. O próprio Orca expõe comandos para criar worktrees e operar o browser. Meus scripts de supervisão usam essa interface.
Acompanhamento pelo celular#
O companion mobile do Orca, disponível para iOS e Android, mostra o estado de cada agente e envia notificações quando uma tarefa termina ou fica esperando uma resposta. Também consigo responder pelo celular.
O aplicativo depende do desktop ligado. Para acessar minha workstation fora de casa, uso Tailscaleabre em nova aba. O computador e o celular entram na mesma rede privada, baseada em WireGuard, sem que eu precise abrir uma porta pública.
Na prática, consigo revisar um plano e responder uma pergunta mesmo longe da mesa. Há custos: o Orca ocioso usa aproximadamente 400 a 800 MB de RAM, três agentes em paralelo podem consumir perto de três vezes mais tokens e o mobile deixa de funcionar quando o desktop está desligado.
A IA como P.O.#
A parte central do meu setup é uma sessão do Claude Code que coordena os agentes que programam. Eu a trato como um P.O. operacional: ela organiza as issues, prepara o contexto e acompanha a execução. As decisões de produto continuam comigo.
Arquitetura#
O orquestrador conversa com o Linear por MCP e envia cada tarefa para uma worktree com Claude Code ou Codex CLI. Quando a implementação termina, o agente abre um PR. Subagentes revisam segurança, isolamento de dados, qualidade geral e banco antes da minha validação final.
O fluxo fica assim:
- A issue entra no Linear.
- O orquestrador escreve um briefing e cria a worktree.
- O agente prepara o plano, pergunta quando necessário e implementa após a aprovação.
- A mudança vira PR e passa pelos gates de revisão.
- Eu reviso o resultado e decido o merge.
- O orquestrador atualiza o Linear e encerra a execução.
Quando um agente filho tem uma dúvida operacional, o orquestrador tenta responder primeiro. Apenas decisões de produto ou escolhas que mudam o escopo chegam até mim.
O briefing#
O agente filho não acessa o Linear diretamente. Por isso, o briefing leva a issue completa, os arquivos que merecem atenção, as regras que não podem ser quebradas e os comandos usados para validar o resultado. Também inclui particularidades do ambiente, como a porta do Postgres.
O protocolo pede que o agente pergunte ao orquestrador quando faltar informação. A última instrução é parar depois de abrir o PR. O merge só acontece após minha revisão.
Escolha do agente#
Não uso o mesmo agente para tudo. Nos meus testes, Claude Code com uma skill de UI funcionou melhor para frontend. Para backend e infraestrutura, tive resultados mais consistentes com Codex CLI.
Os briefings e as regras continuam iguais, independentemente do fornecedor. A escolha fica em uma tabela de despacho e pode mudar conforme os resultados dos próximos projetos.
Perguntas e vigias#
Uma das skills obriga o agente a apresentar uma decisão por vez quando o requisito está incompleto. Este é um diálogo real, com os detalhes do projeto removidos:
Agente: decisão 3 de 8. A fila deve excluir o próprio solicitante da lista de aprovadores? (a) sim, sempre (b) não (c) configurável
Orquestrador: (a). Solicitante nunca se autoaprova. Registrando a decisão no briefing.
Em uma manhã, apareceram mais de oito decisões de design nesse formato. O orquestrador resolveu a maioria usando regras já definidas e me chamou apenas nas que afetavam o produto.
Também uso scripts que detectam quando um agente está esperando uma resposta e me avisam. Esses vigias não resolvem a dúvida, mas impedem que uma execução fique parada por horas sem eu perceber.
Revisão em camadas#
A revisão começa antes do código, com o plano. Depois da implementação, subagentes separam a análise por tema: segurança, vazamento de dados, qualidade geral e banco. Em seguida vêm o PR, os testes locais e a minha leitura do diff.
Ter mais agentes não elimina a revisão humana. Eles aumentam a quantidade de checagens antes de o trabalho chegar ao merge.
Um dia de trabalho#
Em uma segunda-feira, mantive quatro tarefas em paralelo: uma interface de aprovações com PR aberto e gates verdes, uma calibração de NLU em execução, uma integração com CRM esperando resposta e a infraestrutura de testes com o plano em aprovação. Entre o dia anterior e aquele momento, três PRs da sprint tinham sido revisados, validados e mergeados.
Durante o planejamento, um dos agentes percebeu que o problema era maior do que a issue descrevia. Em vez de aumentar o escopo por conta própria, ele registrou a lacuna e o trabalho virou uma nova issue no Linear.
Onde o fluxo falha#
Esse sistema já apresentou vários problemas. Um vigia marcou como travado um agente que ainda estava pensando. Em outra execução, enviei para quatro agentes um caminho com uma variável que não tinha sido interpolada. Também recebi um alerta urgente causado apenas por um hook quebrado. Em uma feature, um limiar de confiança muito conservador impedia qualquer disparo e o erro só apareceu no teste manual.
O código de orquestração tem os mesmos tipos de bug que qualquer outro software. Depois de cada caso, registrei a causa e acrescentei uma proteção ou uma instrução mais clara. Ainda assim, o fluxo continua exigindo supervisão.
Também existem tarefas em que não uso agentes:
- Mudanças triviais. Para corrigir um typo, o preparo custa mais do que a edição.
- Código que eu não sei revisar. Se não consigo avaliar o resultado, não faço o merge.
- Segredos sem proteção. Credenciais não entram em um ambiente sem permissões bem definidas.
- Repositório sem testes. Sem feedback automatizado, o agente tem pouca base para corrigir os próprios erros.
- Decisões de arquitetura. Posso delegar pesquisa e implementação, mas a decisão continua humana.
Cinco regras que sigo#
Resumi meu uso diário nestes aliases:
alias regra1='plan-first, sempre plano antes de código'
alias regra2='o merge é SEU, revisão humana não é opcional'
alias regra3='contexto versionado, constituição + memória no repo'
alias regra4='comece com 1 agente, frota vem depois'
alias regra5='meça antes de escalar'Comecei com um único agente e só adicionei paralelismo depois que o fluxo básico ficou previsível. Medir tempo, custo e quantidade de retrabalho ajuda a decidir se uma nova camada realmente compensa.
Como começar#
Para montar algo parecido, eu seguiria esta ordem:
- Instale um harness, como Claude Code ou Codex CLI, e use em uma tarefa real.
- Crie um arquivo no repositório com regras, decisões e ações proibidas.
- Exija plano e aprovação antes da implementação.
- Adicione um MCP que tenha uso claro e uma skill que você repete com frequência.
- Quando um agente já estiver funcionando bem, experimente worktrees e uma IDE como o Orca.
Os três primeiros passos já resolvem boa parte do transporte manual entre chat e editor. O paralelismo pode entrar depois, quando houver testes e critérios de revisão suficientes para acompanhar mais de uma tarefa.
Boa parte deste material veio de uma palestra que dei na LIA, a liga acadêmica de IA da UFSC, em julho de 2026. Os diagramas são do mesmo deck. Se quiser conversar sobre algum detalhe, estou no LinkedInabre em nova aba e no GitHubabre em nova aba.
Referências:
- Orcaabre em nova aba, repositório oficial
- Review independente do Orcaabre em nova aba
- Tailscaleabre em nova aba
- Claude Codeabre em nova aba
- Model Context Protocolabre em nova aba
- git worktreeabre em nova aba
- Codex CLIabre em nova aba
- awesome-claude-code-subagentsabre em nova aba
- skills.shabre em nova aba
Hoje esse fluxo me permite acompanhar várias frentes sem entregar a decisão final aos agentes. Eles implementam e ajudam a revisar; eu continuo responsável pelo produto e pelo merge.