Boas Práticas para Equipas de Agentes

Problema: A tua equipa de agentes Claude Code arranca e imediatamente começa a queimar tokens sem produzir output utilizável. Os colegas sobrescrevem os ficheiros uns dos outros. O líder arrega as mangas em vez de coordenar. As tarefas ficam em "em progresso" para sempre. Estes problemas têm solução, e os padrões abaixo foram forjados a partir de relatórios da comunidade e meses de iteração real desde que a funcionalidade foi lançada.

Vitória Rápida: Ativa o modo delegado (Shift+Tab) e dá a cada colega limites explícitos de ficheiros no prompt de criação. Esses dois ajustes eliminam as falhas de equipa mais comuns.

Nota: Este é um guia complementar ao guia de visão geral das Equipas de Agentes. Vai lá primeiro se ainda não configuraste uma equipa. Para os ajustes e configurações, ver Controlos Avançados.

Dá Contexto Suficiente aos Colegas

Carrega detalhe específico da tarefa no prompt de criação. O contexto do projeto (CLAUDE.md, servidores MCP, skills) chega automaticamente, mas o histórico de conversa do líder não viaja com o colega. Aponta para ficheiros específicos, critérios de aceitação e restrições. Um prompt de criação preciso reduz drasticamente as trocas de mensagens.

Um prompt vago como "revê o módulo de auth" faz o colega procurar pelo código, perceber o que importa e adivinhar prioridades. Essa exploração consome tokens e tempo. Um prompt específico remove a ambiguidade:

A forma é simples: o quê fazer, onde fazer, no que focar, e como deve ficar o entregável. Os colegas que conhecem o seu âmbito à partida terminam mais rápido e entregam trabalho melhor. Se vens de padrões de subagentes, a regra é idêntica, mas as apostas são mais altas. Cada colega é agora uma janela de contexto completa.

Dimensiona as Tarefas para os Colegas

Demasiado pequenas e o custo de coordenação come o ganho. Demasiado grandes e os colegas trabalham sem pausas, arriscando esforço perdido. O ponto ideal é uma unidade autocontida com um entregável limpo: uma função, um ficheiro de teste, um documento de revisão.

Aponta para 5-6 tarefas por colega. Isso mantém toda a gente em movimento e permite ao líder redistribuir trabalho quando alguém está parado. Se o líder não está a fatiar o trabalho com suficiente granularidade, diz-lhe para partir as peças em mais pequenas. Um colega com uma tarefa gigante não tem ponto de controlo natural. Um colega com 5-6 tarefas focadas reporta após cada uma, dando-te espaço para guiar.

Evita Conflitos de Ficheiros

Dois colegas a editar o mesmo ficheiro significa sobrescritas silenciosas. Esta é a regra mais importante para trabalho de implementação. Divide as tarefas de modo a que cada colega possua um conjunto distinto de ficheiros. Especifica limites de diretório no prompt de criação.

Se o repositório não se divide naturalmente em diretórios independentes, cria a divisão na tua decomposição. Em vez de "refatora a camada de API" entre três colegas, atribui "refatora os endpoints de utilizador em src/api/users/" a um e "refatora os endpoints de faturação em src/api/billing/" a outro. A posse explícita previne as sobrescritas silenciosas que destroem sessões inteiras de colegas.

Para projetos onde ficheiros partilhados são inevitáveis, marca-os como "coordenar antes de editar" no teu CLAUDE.md e deixa o líder sequenciar o acesso através da lista de tarefas.

Usa o Modo Delegado

Ativa o modo delegado (Shift+Tab) no momento em que uma equipa começa. Sem ele, o líder às vezes agarra tarefas destinadas a colegas, baralhan do a responsabilidade. O modo delegado restringe o líder a ferramentas apenas de coordenação, por isso fica na orquestração em vez de implementação. Para o guia completo e opções de configuração, ver o guia do modo delegado.

Começa com Tarefas de Pesquisa

Novo em equipas de agentes? Começa com tarefas que têm limites claros e sem escrita de código: revisões de PR, pesquisa de bibliotecas, investigação de bugs, ou auditorias de módulos contra uma checklist específica. Estas mostram o ganho da exploração paralela sem os problemas de coordenação da implementação paralela.

As tarefas de pesquisa também são mais forgiventes. Quando um colega vai por um caminho improdutivo, perdes tokens, não código. Os erros de implementação são mais difíceis de desfazer, especialmente quando múltiplos colegas empilharam alterações uns sobre os outros.

Quando a dinâmica da equipa parecer natural, avança para tarefas de implementação. Os mesmos padrões aplicam-se, mas as apostas sobem e os limites de posse de ficheiros importam muito mais.

Monitoriza Ativamente

Usa Ctrl+T para espreitar o progresso e redirecionar abordagens que não estão a funcionar. Deixar uma equipa a correr sem supervisão demasiado tempo acumula o risco de esforço desperdiçado, especialmente se um colega ficar preso num beco sem saída.

Trata as equipas de agentes como um fluxo de trabalho supervisionado. Tu és o gestor de projeto. O líder coordena, mas tu fazes as decisões estratégicas: quando redirecionar, quando criar um substituto, e quando desligar um colega parado. Pensa nisso como gerir uma equipa distribuída de subcontratados. Check-ins regulares detetam problemas antes de se agravarem.

O Tamanho da Equipa Importa

Na prática, 3-5 colegas é o ponto ideal real. Mais colegas significa mais custo de coordenação, mais gasto em tokens, e mais chances de fios cruzados. O contexto do líder enche-se mais rápido a seguir 8 colegas do que 3. O custo de comunicação escala com o tamanho da equipa, porque cada transmissão aterra na janela de cada colega.

Se a tarefa realmente exige mais de 5 trabalhadores em paralelo, divide-a em fases. Corre uma equipa de 3 colegas para a fase um, limpa, depois corre outra equipa de 3 colegas para a fase dois. Fases sequenciais com equipas menores produzem resultados mais limpos do que uma equipa gigante a lutar com tudo de uma vez.

Comportamento do Modo de Plano

O modo de plano dentro das equipas de agentes tem dois comportamentos importantes que não são óbvios na documentação.

O modo de plano é reavaliado em cada volta, não apenas uma vez. Quando um colega corre em modo de plano, fica lá durante toda a sua vida. Cada ação que toma é filtrada pela restrição apenas de leitura. Isso torna o modo de plano ótimo para funções de design e modelagem inicial de tarefas, mas mau para execução.

O modo de um colega é fixo no momento da criação. Uma vez lançado, não podes mudar um colega de plano para padrão. Se precisas de uma transição de planeamento para execução, cria um colega novo em modo padrão e passa o plano. Não tentes "mudar" um colega existente para fora do modo de plano.

Isso molda o design da equipa. Usa colegas em modo de plano para funções de arquitetura e revisão onde uma perspetiva apenas de leitura é o objetivo. Usa colegas em modo padrão para qualquer função que precise de escrever código ou modificar ficheiros. Para um fluxo de planear-depois-implementar, usa a funcionalidade de aprovação de planos. Isso permite que um colega em modo padrão planeie primeiro e construa após aprovação.

Regras Claras Produzem Relatórios Claros

Com regras sólidas no CLAUDE.md, os colegas reportam exatamente o que fizeram sem o líder intervir. Um colega a terminar uma tarefa de limpeza contra um CLAUDE.md bem escrito retorna algo como: "Removi 27 console.log em 3 ficheiros. Mantive todos os 12 console.error e 2 console.warn em component-page.js. Verifiquei zero console.log restantes nos meus ficheiros atribuídos."

Sem intervenção do líder. Regras claras dentro, relatórios claros fora.

Este padrão surge naturalmente quando o teu CLAUDE.md lista critérios de verificação específicos. Em vez de "limpa o logging," o colega já sabe que "verificado" significa correr grep para instâncias restantes e confirmar que o logging de nível de erro sobreviveu. Para mais sobre como moldar o CLAUDE.md para equipas, ver CLAUDE.md mastery e a secção de otimização do CLAUDE.md em Controlos Avançados.

Resolução de Problemas

Problemas comuns e as suas soluções, retirados de relatórios da comunidade e notas de versão:

Se o teu problema não está nesta lista, verifica qual versão do Claude Code estás a correr. Muitos pontos de dor iniciais foram resolvidos nas versões v2.1.33 a v2.1.45.

Limitações Atuais

As Equipas de Agentes são experimentais. Estas restrições valem a pena conhecer antes de te comprometeres a um fluxo de trabalho baseado em equipas:

• Sem retoma de sessão: Os colegas in-process não são restaurados ao usar /resume ou /rewind. Após retomar, o líder pode tentar enviar mensagens a colegas que já não existem. Diz-lhe para criar substitutos.
• O estado de tarefa pode atrasar: Os colegas às vezes esquecem de marcar tarefas como concluídas, bloqueando trabalho dependente. Verifica manualmente se algo parece parado.
• Encerramento lento: Os colegas terminam o seu pedido atual ou chamada de ferramenta antes de encerrar. Isso pode demorar se um colega está a meio da implementação.
• Uma equipa por sessão: Um líder gere uma equipa de cada vez. Limpa a equipa atual antes de começar outra.
• Sem equipas aninhadas: Os colegas não podem criar as suas próprias equipas. Apenas o líder gere a hierarquia da equipa.
• Líder fixo: A sessão que cria a equipa fica como líder durante toda a sua vida. Não podes promover um colega ou transferir a liderança.
• Permissões definidas na criação: Todos os colegas começam com as definições de permissão do líder. Podes alterar modos individuais após a criação, mas não no momento da criação.
• Painéis divididos requerem tmux ou iTerm2: O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal, ou Ghostty.

Ser direto sobre estas arestas importa. As Equipas de Agentes são uma funcionalidade poderosa com costuras visíveis. Os developers que aprendem os contornos agora são os que estarão prontos quando a Anthropic os polir.

Correções Recentes

Desde o lançamento inicial das Equipas de Agentes em v2.1.32, a Anthropic lançou várias correções importantes. Se experimentaste equipas de agentes cedo e te queimaste, verifica se o teu problema foi resolvido:

v2.1.33:

• Adicionados hooks TeammateIdle e TaskCompleted para aplicação de gates de qualidade
• Adicionado Task(agent_type) restrições de criação para controlar quais tipos de subagente podem ser criados
• Adicionado campo memory persistente para agentes com âmbitos de utilizador, projeto e local
• Corrigidas sessões de colega tmux para enviar e receber mensagens corretamente
• Corrigidos avisos de modo de plano em contextos de equipa

v2.1.34:

• Corrigido crash quando a definição de equipas de agentes mudava entre renders

v2.1.41:

• Corrigido identificador de modelo errado para colegas no Bedrock/Vertex/Foundry
• Adicionado atributo speed a eventos OTel para observabilidade do modo rápido

v2.1.45:

• Corrigidos colegas a falhar no Bedrock/Vertex/Foundry ao propagar variáveis de ambiente do provider de API para sessões tmux
• Corrigidas skills invocadas por subagentes a aparecer incorretamente na sessão principal após compactação

A ter problemas? Atualiza Claude Code para a versão mais recente. A equipa lança correções a um ritmo rápido e as equipas de agentes estão em desenvolvimento ativo.

Guias Relacionados

Este guia é o manual operacional. Para o resto da imagem:

• Visão geral das Equipas de Agentes para os fundamentos e arquitetura da funcionalidade
• Controlos Avançados para modos de exibição, modo delegado, hooks e gestão de custo em tokens
• Casos de Uso e Modelos de Prompt para prompts copy-paste em 10+ cenários do mundo real
• Fluxo de Trabalho de Ponta a Ponta para o pipeline completo de 7 passos do brain dump ao código de produção validado
• Boas práticas de sub-agentes para quando uma equipa completa é exagero e subagentes focados são a escolha certa