Subagentes em paralelo no Codex e Claude Code: prompts e configuração

A impressão comum de que "o Claude Code trabalha em paralelo sozinho, mas o Codex não faz isso a menos que você peça" é verdadeira, com ressalvas. O app, a CLI e a extensão para IDE do Codex iniciam trabalhadores em paralelo (subagentes) quando você pede, ou quando o AGENTS.md ou uma skill mandam dividir o trabalho entre subagentes. Já o Claude Code também delega por conta própria, com base no conteúdo do seu pedido e na descrição de cada subagente.

Este artigo compara como fazer as duas ferramentas trabalharem em paralelo, com base na documentação oficial da OpenAI e da Anthropic (consultada em 26 de outubro de 2026), nesta ordem: gatilhos, como escrever as instruções, configuração, comandos e custo. Em todas as seções as duas ferramentas aparecem na mesma ordem e com as mesmas cores: Codex → Claude Code. No final, resumo as lições que este site aprendeu rodando subagentes em paralelo com o Claude Code.

1. O que dispara o trabalho em paralelo e o que acontece se você não disser nada

Um subagente é um trabalhador separado que assume parte do trabalho da conversa principal. Cada um faz pesquisas ou roda testes no próprio contexto e devolve à conversa principal apenas um resumo dos resultados. Rodá-los em paralelo reduz a espera e impede que a conversa principal se encha de logs intermediários. As duas ferramentas compartilham essa ideia.

O que muda é quem dá a partida. Veja quatro situações.

Fontes: OpenAI "Subagents"; Anthropic "Create custom subagents". Consultado em 26 de outubro de 2026.

Segundo a documentação oficial do Codex, as versões locais do Codex (app, CLI, extensão para IDE) delegam "quando solicitadas diretamente ou quando instruções relevantes do AGENTS.md ou de uma skill pedem delegação". O recurso não está desligado: o sistema de subagentes vem ativado por padrão nas versões atuais. Iniciar ou não fica a cargo das suas instruções. No ChatGPT Work (web), a maioria dos níveis de inteligência exige um pedido explícito, e só quando você escolhe Ultra (o Ultra é limitado a contas elegíveis e modelos compatíveis) ele pode delegar por conta própria quando trabalhar em paralelo melhoraria substancialmente a velocidade ou a qualidade.

A descrição oficial do Claude Code é que ele "delega automaticamente com base na tarefa do seu pedido, na description da definição do subagente e no contexto atual". Para subagentes que você quer ver usados de forma mais proativa, a recomendação é colocar frases como "use proactively" na descrição. Subagentes que herdam a conversa como está (forks) também são iniciados pelo Claude a critério dele, por padrão.

Um detalhe: o changelog do Codex inclui uma mudança que permite a quem incorpora o Codex nos próprios produtos (clientes de app-server) escolher a delegação entre "desativada, somente pedidos explícitos ou proativa" (Codex CLI 0.142.0, 22 de junho de 2026). Para quem usa o app, a CLI e a IDE, o comportamento é o da tabela acima.

2. Como as duas funcionam, lado a lado

Aqui estão como se escrevem as definições de subagentes, quantos podem rodar ao mesmo tempo, como os diretórios de trabalho são separados e mais. Quando só a documentação oficial de um dos lados trata de algo, aparece a marcação "Não documentado".

Fontes: OpenAI "Subagents", "Configuration Reference", "Worktrees"; Anthropic "Create custom subagents", "Run parallel sessions with worktrees". Consultado em 26 de outubro de 2026.

Há duas grandes diferenças. A primeira é se dá para impedir um subagente de gravar. O Codex usa as permissões do pai sem mudanças, então dizer a um subagente "não edite" é só um pedido. O Claude Code pode retirar completamente de um subagente as ferramentas de edição (Write, Edit). Para bloquear também a gravação pelo shell, remova o Bash também. A segunda é uma cópia de trabalho por subagente: o Claude Code pode criar um git worktree (uma cópia de trabalho separada do mesmo repositório) para cada subagente, enquanto no Codex os worktrees são por chat.

O Claude Code tem outras formas de trabalhar em paralelo além dos subagentes (a visão de agentes, que roda sessões separadas em uma única tela, e as equipes de agentes, em que os trabalhadores se comunicam entre si). As diferenças estão em "Subagentes vs equipes de agentes no Claude Code" e "A visão de agentes do Claude Code".

3. Como escrever as instruções, com prompts prontos para usar

A documentação oficial do Codex recomenda que um bom prompt diga como dividir o trabalho, se é preciso esperar todos os agentes antes de continuar e o que deve ser devolvido. Pela nossa experiência rodando subagentes em paralelo neste site, acrescentar mais dois itens reduz os acidentes.

1. Como dividir o trabalhoPor tema (segurança, testes, manutenibilidade), por local (diretório, módulo) etc. Divida de forma que dois subagentes não olhem a mesma coisa
2. O que podem mexer"Somente leitura" ou "você só pode editar este diretório". Nunca deixe dois subagentes mexerem no mesmo arquivo
3. Se é preciso esperar todosCombinar só quando todos os resultados chegarem, ou permitir seguir adiante no meio do caminho
4. O que devolverFormato e tamanho ("menos de 10 linhas com nomes de arquivo" etc.). Respostas longas enchem rápido o contexto principal
5. O que não fazerFazer commit, fazer push, subagentes iniciando mais subagentes etc. Se ninguém disser o que é proibido, os subagentes vão fazer com a melhor das intenções

Pesquisas e revisões somente leitura (comece por aqui)

Revise esta branch em comparação com a main. Inicie três subagentes em paralelo:
um para problemas de segurança, um para testes faltando e um para manutenibilidade.
Nenhum deles deve editar arquivos.
Espere os três terminarem e então resuma por tema, com nomes de arquivo e números de linha.

Pesquise em paralelo os módulos de autenticação, banco de dados e API usando subagentes separados.
Todos os subagentes devem apenas ler, sem alterar nenhum arquivo.
Peça que cada um devolva "arquivos de entrada, fluxo principal de processamento, pontos de atenção" em menos de 10 linhas,
e combine tudo em um só depois que todos os resultados chegarem.

Dividir trabalho que edita arquivos

A documentação oficial das duas trata com cautela o trabalho em paralelo com muitas gravações. Dê a cada subagente a própria área que ele pode editar e, no Claude Code, separe também as cópias de trabalho.

Descubra por que salvar na página de configurações falha e corrija.
Peça ao browser_debugger para reproduzir no navegador e registrar os passos,
e ao code_mapper para localizar o código responsável (esses dois não devem editar nada).
Quando a causa for conhecida, peça ao ui_fixer a menor correção possível. Não mexa em arquivos não relacionados.

/batch migre o JavaScript em src/ para TypeScript

Para não ter que dizer toda vez

Se pedir trabalho em paralelo toda vez no Codex é um incômodo, escreva regras de delegação no AGENTS.md do projeto. A documentação oficial diz que ele delega quando há instruções relevantes no AGENTS.md ou em uma skill. Ela não diz qual redação dispara isso com segurança, então, depois de escrever as regras, confira uma vez se os subagentes iniciam com os seus pedidos de costume.

## Uso de subagentes
- Para pesquisas que abranjam três ou mais diretórios, inicie um subagente por diretório e pesquise em paralelo
- Não deixe os subagentes editarem arquivos. Faça toda a edição na thread principal
- Espere todos os resultados chegarem e então relate só os pontos principais

No Claude Code, se você quer que um subagente específico seja mais usado, escreva na description dele quando usá-lo, além de "use proactively" (veja na próxima seção um exemplo de definição). Ao contrário, se ele delega demais, adicionar Agent a permissions.deny o impede de iniciar subagentes.

4. Configuração e arquivos de definição de subagentes

Codex config.toml e .codex/agents/

As configurações gerais ficam em [agents] no config.toml (pessoal: ~/.codex/config.toml, projeto: .codex/config.toml).

# .codex/config.toml
[agents]
max_concurrent_threads_per_session = 4     # Máximo de threads de subagentes abertas ao mesmo tempo (sem contar a thread principal)
default_subagent_model = "gpt-6-luna"      # Modelo padrão para subagentes
default_subagent_reasoning_effort = "high" # Esforço de raciocínio padrão para subagentes

Fonte: OpenAI "Configuration Reference". Consultado em 26 de outubro de 2026. O "multi agent v2" que aparece com frequência nos resultados de busca é a versão atual desse sistema; segundo o changelog, ele se tornou estável no Codex CLI 0.145.0 (21 de julho de 2026) (changelog). Nas versões atuais ele vem ativado sem que você precise escrever multi_agent = true.

Agentes personalizados ficam em .codex/agents/, um arquivo TOML por agente. O nome do agente vem de name, não do nome do arquivo.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Revisor focado em correção, segurança e testes faltando"
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Não edite arquivos.
Priorize correção, segurança, regressões de comportamento e testes faltando.
Faça comentários apenas de estilo somente quando eles esconderem um bug real.
"""

Adaptado do exemplo oficial. Os nomes de modelo vêm do exemplo oficial; os modelos disponíveis variam conforme a conta e o workspace. A orientação oficial é gpt-6.1-sol para agentes que fazem muitos julgamentos e gpt-6-luna para agentes leves com escopo bem delimitado. Configurações como sandbox_mode, approval_policy e mcp_servers são substituídas pelas do pai mesmo que você as escreva no arquivo do agente.

Claude Code .claude/agents/ e settings.json

Os subagentes ficam em .claude/agents/ em Markdown. Você também pode simplesmente pedir ao Claude para "criar um subagente que faça X" e deixar que ele escreva o arquivo.

---
name: test-runner
description: Runs the test suite and reports only failing tests with their errors. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Rode os testes e devolva apenas os nomes dos testes que falharam e o essencial dos erros.
Não corrija código. Não devolva a lista de testes que passaram.

Como tools não inclui Write nem Edit, segundo a documentação oficial este subagente não pode editar nem gravar arquivos. Porém, o Bash é mantido para que ele possa rodar os testes, o que deixa margem para gravar via comandos de shell. O "Não corrija código" no corpo serve de lembrete para isso. model aceita sonnet, opus, haiku, fable, um ID de modelo ou inherit (o mesmo da conversa principal). Como escolher o modelo por subagente está em "Como rodar os subagentes do Claude Code em outro modelo".

O limite de concorrência e a profundidade de aninhamento são definidos com variáveis de ambiente, que você pode colocar em env no settings.json.

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

Fontes: Anthropic "Create custom subagents", "Orchestrate teams of Claude Code sessions". Consultado em 26 de outubro de 2026.

5. Referência de comandos

Estes são os comandos para acompanhar subagentes em execução, separar cópias de trabalho, ramificar uma conversa e assim por diante. Alguns têm o mesmo nome, mas fazem coisas diferentes, então atenção.

Fontes: OpenAI "Command line options, Slash commands", "Subagents"; Anthropic "Commands", "Run agents in parallel", "Create custom subagents" (testar várias abordagens com forks). Consultado em 26 de outubro de 2026.

O que confunde é o /agents, porque os nomes coincidem. No Codex, /agents é a lista de chats no servidor (a central de comando). No Claude Code, /agents indica onde ficam as definições de subagentes, e a lista de sessões é claude agents (iniciado pelo shell).

6. Tarefas que combinam com trabalho em paralelo e tarefas que não

A documentação oficial das duas diz quase a mesma coisa: comece pelo trabalho somente leitura e tenha cuidado com o trabalho com muitas gravações.

Fontes: OpenAI "Subagents" (Why subagent workflows help); Anthropic "Create custom subagents" (Choose between subagents and main conversation) e "agent teams" (Avoid file conflicts). Consultado em 26 de outubro de 2026.

7. Impacto no custo (limites de uso)

Trabalhar em paralelo é mais rápido, mas consome mais do seu uso, porque cada subagente faz as próprias chamadas ao modelo e usa as próprias ferramentas.

Fontes: OpenAI "Subagents", "Changelog"; Anthropic "Manage costs effectively", "Create custom subagents". Consultado em 26 de outubro de 2026.

Outra coisa fácil de passar despercebida é que as respostas dos subagentes também vão parar no contexto principal. A documentação do Claude Code alerta que rodar muitos subagentes que devolvem resultados detalhados pode consumir bastante do contexto principal. Definir um formato de resposta como "menos de 10 linhas" também ajuda no custo. A economia de tokens no Claude Code em geral está em "Dicas para economizar tokens no Claude Code".

8. Lições da prática (exemplos deste site)

Este site (AI Arte) funciona entregando a tradução e as verificações de artigos a subagentes do Claude Code em paralelo. A pesquisa e o rascunho deste artigo também foram escritos por um dos subagentes enviados pela sessão principal. Abaixo estão coisas que realmente aconteceram e como evitá-las. Todos são registros do Claude Code; nenhum foi reproduzido no Codex. Ainda assim, conflitos no mesmo arquivo e relatos imprecisos sobre o que está fora do escopo de um subagente merecem atenção também no Codex, já que o mecanismo é parecido.

1. Julho de 2026Defina quantos rodam ao mesmo tempo de acordo com os seus limites

   O que aconteceu

   Rodar seis ou mais ao mesmo tempo fez os subagentes falharem por limites de taxa

   Como evitar

   Limite a 5 ao mesmo tempo e rode trabalhos maiores em lotes de 5, um após o outro. Defina um limite adequado aos seus limites, abaixo do limite padrão do Claude Code (20)

2. 22 de setembro de 2026Não deixe subagentes iniciarem mais subagentes

   O que aconteceu

   Um subagente encarregado de um trabalho em 10 idiomas iniciou por conta própria 5 subagentes de tradução. Somados aos 5 do pai, eram 10 rodando ao mesmo tempo, o limite de uso foi atingido e todos pararam no meio

   Como evitar

   Em "o que não fazer" nas instruções, escreva "Não inicie subagentes. O pai distribui o trabalho." O Claude Code permite por padrão que subagentes iniciem subagentes (até 3 níveis), então você também pode impedir o aninhamento com CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1

3. 22 de agosto de 2026Nunca deixe dois subagentes mexerem no mesmo arquivo

   O que aconteceu

   Uma frase que o pai tinha acrescentado ao final de um capítulo de curso foi apagada por outro subagente por "não estar nas instruções", depois acrescentada de novo, repetidas vezes

   Como evitar

   Atribua a cada subagente os arquivos em que ele pode mexer. Para o que o pai vai acrescentar em lote depois, mencione também nas instruções dos subagentes ou acrescente depois que todos terminarem

4. 22 de setembro de 2026Separe também onde ficam os arquivos temporários

   O que aconteceu

   Um script temporário que um subagente colocou direto na pasta temporária foi sobrescrito por um arquivo de mesmo nome de outro subagente. Subagentes iniciados a partir da mesma conversa enxergam a mesma pasta temporária

   Como evitar

   Nas instruções, atribua a cada subagente a própria subpasta

5. 5 de setembro de 2026Não faça commit de tudo de uma vez enquanto subagentes estão rodando

   O que aconteceu

   Com 5 rodando, uma alteração não relacionada foi commitada com git add -A (todas as alterações), arrastando para um commit sem relação 100 arquivos que os subagentes tinham terminado

   Como evitar

   Faça commit especificando os arquivos. Diga também aos subagentes que operações que juntam todas as alterações ou revertem alterações são proibidas

6. 22 de agosto de 2026Meça de novo o que os subagentes relatam fora do próprio escopo

   O que aconteceu

   Dois subagentes relataram "24 itens falham na verificação" e "28", mas a contagem real era 16. Eles tinham chutado o estado de arquivos em que não mexeram

   Como evitar

   O pai confere contagens e alvos rodando ele mesmo as verificações. O que um subagente encontra dentro do próprio escopo é bem preciso, então nisso dá para confiar

Extraído dos registros de operação deste site (de julho a setembro de 2026). Só foram incluídos números que constam nesses registros.

Juntando essas lições, as instruções que você distribui ficam assim. Os subagentes não conhecem o resto da conversa, então escreva de forma que as instruções sozinhas bastem para terminar o trabalho.

[Tarefa] Pesquisar o artigo 273 e escrever o rascunho em ja
[O que não fazer]
- operações git (add, commit, checkout, restore, stash, push)
- Não inicie subagentes (o pai distribui o trabalho)
- Não edite outros artigos
- Coloque arquivos temporários em pasta-temporaria/a273/
[Como pesquisar] A partir do texto original da documentação oficial (registre URLs e datas de consulta)
[O que devolver] Arquivos criados, título, o que não pôde ser verificado

O esqueleto (resumido) das instruções que o subagente que escreveu este artigo recebeu, mais duas das lições acima (não iniciar subagentes, onde colocar arquivos temporários). O mesmo formato serve para instruções a subagentes tanto no Codex quanto no Claude Code.

Resumo

Para as diferenças gerais entre as duas ferramentas (preços, limites, onde rodam), veja "Claude Code vs Codex: qual escolher?", e para configurações que deixam os subagentes mais perto do somente leitura, veja "Como usar o Codex e o Claude Code em modo somente leitura".

Perguntas frequentes

P. Quantos subagentes do Codex podem rodar ao mesmo tempo?

R. Você define o limite com agents.max_concurrent_threads_per_session no config.toml (a thread principal não conta). Se você omitir, o Codex decide, e esse valor padrão não é publicado. Os exemplos oficiais de configuração usam 6 ou 8. No Claude Code o padrão é 20 ao mesmo tempo, alterável com CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Em qualquer uma das duas, quanto mais você roda, mais rápido os limites de uso se esgotam.

P. Posso usar um modelo mais barato só para os subagentes?

R. Sim. No Codex, defina com default_subagent_model em [agents], ou com model e model_reasoning_effort no arquivo do agente. Se não for especificado, o modelo do pai é herdado. No Claude Code, defina model na definição do subagente (haiku etc.) ou use a variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL.

P. Preciso escrever "multi_agent = true" na configuração?

R. Não no Codex atual. Na referência de configuração, features.multi_agent é estável e ativado por padrão, e agents.enabled também tem padrão true. Segundo o changelog, o multi-agent V2 chegou como um sistema opcional (opt-in) e se tornou estável no Codex CLI 0.145.0 (21 de julho de 2026). Os passos para "ativar" dos guias antigos agora produzem o mesmo estado que não escrever nada. Para desligar, escreva enabled = false em [agents].

P. Como impeço o Claude Code de iniciar subagentes sozinho?

R. Para bloquear subagentes por completo, adicione Agent a permissions.deny nas suas configurações de permissão. Para impedir só os subagentes que herdam a conversa (forks), use Agent(fork) ou a variável de ambiente CLAUDE_CODE_FORK_SUBAGENT=0. Se as equipes de agentes estiverem ativadas, um subagente chamado pelo nome pode iniciar como membro da equipe, então deixe as equipes de agentes desativadas se você não as usa.