Fluxo de Trabalho das Equipas de Agentes

Problema: As Equipas de Agentes estão ativas. Já correste a tua primeira equipa. A criação funciona. Mas o output é uma pilha de peças semi-integradas que acabas por coser tu próprio. O fosso entre "equipas de agentes a correr" e "equipas de agentes a lançar código de produção" é um processo, não uma flag de funcionalidade.

Vitória Rápida: Um fluxo de trabalho que torna as equipas de agentes fiáveis corre em duas fases. O planeamento elimina suposições e bloqueia os contratos entre domínios. A execução cria agentes em vagas e entrega a cada vaga os contratos que precisa para que o trabalho paralelo se encaixe de forma limpa. O fluxo completo está abaixo.

Este é o guia complementar ao guia de visão geral das Equipas de Agentes. Se ainda não ativaste a funcionalidade ou correste uma primeira equipa, começa por lá. Para controlos e configuração, ver Controlos Avançados. Para modelos copy-paste, ver Casos de Uso.

Conseguir criar sessões Claude paralelas que comunicam entre si é uma capacidade. Os fluxos de trabalho agênticos precisam de mais do que uma capacidade. Criar agentes sem um processo é como entregar as chaves de uma obra a cinco empreiteiros sem plantas: toda a gente constrói, nada encaixa.

Dois modos de falha aparecem sempre que não há um fluxo de trabalho:

1. Deriva de suposições. Cada agente escolhe as suas próprias formas de dados, nomenclatura, formatos de erro e casos extremos. O backend devolve { notif_type: "comment" } e o frontend lê { type: "COMMENT" }. Os testes unitários passam dos dois lados. A integração explode.

2. Falta de validação. Cada agente reporta sucesso, por isso o líder marca as tarefas como feitas. Ninguém testou o fluxo completo. A app parte na primeira vez que clicas nela e os erros enterrados surgem à superfície.

Um pipeline resolve ambos:

1. Brain dump dos teus requisitos (não estruturado, bagunçado, tudo bem)
2. Pesquisa e Q&A onde Claude investiga o teu código e faz perguntas de clarificação
3. Plano estruturado com membros da equipa, cadeias de dependências, e critérios de aceitação
4. Contexto novo onde inicias uma sessão nova apenas com o plano
5. Análise da cadeia de contratos onde o líder deriva interfaces do grafo de dependências do plano
6. Execução em vagas onde os agentes constroem em paralelo contra contratos injetados
7. Ciclo de validação onde o líder corre verificações de ponta a ponta contra os critérios de aceitação

Cada passo existe porque saltar esse passo produz uma falha específica. O resto deste artigo percorre cada um deles.

Passo 1: Brain Dump

Não polishes o input. Escreve o que queres em linguagem simples. Inclui tudo o que te vem à cabeça, mesmo quando está bagunçado, meio formado, ou se contradiz. Objetivo: esvaziar a tua cabeça para a página.

Isto não é uma especificação. É matéria-prima. O objetivo de todo o brain dump é capturar intenção e contexto que morre no momento em que tentas forçar uma especificação formal a partir da tua cabeça.

Um brain dump funciona também como verificação de âmbito. Se não consegues esboçar o que queres em alguns parágrafos, a funcionalidade é demasiado grande para uma sessão de equipa de agentes. Divide-a primeiro.

Passo 2: Pesquisa e Q&A

Este é o passo que a maioria das pessoas salta, e é o que mais importa. O objetivo: reduzir suposições antes de qualquer código ser escrito.

A maioria das falhas de equipas de agentes não vem de código mau. Vem de desalinhamento. O agente entrega algo que não é o que querias porque adivinhou errado. Correção: faz Claude ler o teu código e fazer-te perguntas antes de planear qualquer coisa. O planeamento estruturado de equipa substitui o hábito ad-hoc de "entrar em modo de plano".

Não 2 ou 3 perguntas. Pelo menos 10. Cada pergunta extra que Claude faz é uma suposição a menos incorporada no plano.

Claude vai voltar com perguntas como:

• A página de faturação deve ficar sob o layout do dashboard ou ser independente?
• Que pacotes de tokens e preços queres?
• Devemos usar o checkout alojado do ChargeB ou incorporado na app?
• O que deve acontecer na interface de chat quando um utilizador tem zero tokens?
• Já tens uma conta ChargeB e um endpoint de webhook configurado?

Cada pergunta é um potencial desvio na implementação. Um agente que adivinha "checkout incorporado" e começa a construir vai deitar tudo fora quando lhe disseres que querias alojado. Dez minutos de Q&A elimina horas de retrabalho.

A ferramenta AskUserQuestion no Claude Code torna isto rápido. A maioria das respostas são de escolha múltipla. Clica onde a escolha do Claude está certa. Escreve uma resposta personalizada onde precisas de precisão.

Para abordagens mais estruturadas à fase de planeamento, ver estratégias de planeamento automático.

Passo 3: Transformar num Plano Estruturado

Com o Q&A encerrado, incorpora tudo num plano estruturado. Esse plano torna-se o único artefacto que conduz toda a execução da equipa. Tem de conter:

• Descrição e objetivo da tarefa para a equipa saber como fica o sucesso
• Ficheiros relevantes para os agentes saberem o que existe e o que criar
• Membros da equipa com funções nomeadas, tipos de agente e responsabilidades únicas
• Tarefas passo a passo com cadeias de dependências (campos Depends On) e limites de posse de ficheiros
• Critérios de aceitação que são específicos e mensuráveis
• Comandos de validação que podem ser corridos para verificar o trabalho

Esta é a estrutura que faz a orquestração de equipas funcionar:

O plano faz três trabalhos ao mesmo tempo: traça linhas de posse de ficheiros (sem conflitos), codifica uma cadeia de dependências (para a execução saber o que construir primeiro), e escreve critérios de aceitação (para a validação ter um alvo concreto).

Olha para os campos Depends On. Não são documentação. Formam a cadeia de contratos que a fase de execução usa para escolher quais agentes criar primeiro e quais interfaces extrair entre vagas.

Passo 4: Começa de Novo Com o Plano

Este parece errado e ainda importa. Abre uma sessão Claude Code nova com apenas o plano carregado. Não continues na mesma janela de contexto onde fizeste o brain dump e Q&A.

Porquê? As conversas de planeamento consomem contexto. Estão cheias de perguntas exploratórias, ideias abandonadas e trocas que agora são irrelevantes. O plano é a versão destilada. Já contém o que a equipa precisa. A conversa de planeamento é peso morto a ocupar espaço no build.

Isso também significa que os planos são reutilizáveis. Uma sessão que falha a meio reinicia a partir do mesmo ficheiro de plano. Nenhum trabalho de planeamento é refeito.

Passo 5: Análise da Cadeia de Contratos

Antes de qualquer agente ser criado, o líder percorre o grafo de dependências do plano e extrai a cadeia de contratos. Este é o passo que torna as equipas de agentes fiáveis para builds de produção.

Uma cadeia de contratos agrupa tarefas em vagas pelas suas dependências, depois nomeia os outputs que cada vaga a completar produz e que a vaga seguinte precisa:

Este é o insight principal: nenhum agente começa trabalho até que os seus contratos existam. O agente de base de dados corre primeiro. Quando termina, envia uma mensagem ao líder com as definições reais de schema, tipos de tabela e relações. Esses outputs SÃO o contrato. O líder depois cola esses schemas concretos diretamente nos prompts de criação dos agentes de API e frontend, para que ambos construam contra interfaces reais em vez de inventar as suas próprias.

É por isso que agentes paralelos acabam com código que realmente se integra: não estão a adivinhar formas de dados independentemente. Estão todos a escrever contra o mesmo contrato, e esse contrato veio de trabalho que já foi lançado.

O Que É Injetado como Contrato

Os contratos não são especificações abstratas. São os outputs reais do trabalho a montante:

• Base de dados completa -> contrato de schema: definições exatas de tabelas, tipos de colunas, chaves estrangeiras, tipos TypeScript
• API completa -> contrato de API: rotas de endpoints, formas de pedido/resposta, códigos de estado, requisitos de auth
• Tipos partilhados criados -> contrato de tipos: interfaces, enums, constantes que múltiplos agentes referenciam

Cada agente a jusante recebe os contratos correspondentes colados no seu prompt de criação. Não "vai ler o que o agente de base de dados fez." O conteúdo em bruto. Isso elimina o modo de falha onde um agente lê ficheiros desatualizados ou interpreta mal o output de outro agente. Os padrões de subagentes deixam cada agente a adivinhar no seu próprio canto. Um fluxo de trabalho agêntico adequado liga cada agente a uma interface verificada.

Passo 6: Execução em Vagas

Com a cadeia de contratos definida, o líder cria agentes em vagas.

Vaga 1 (Fundação): O agente de base de dados vai primeiro. Trata do trabalho fundacional: schemas, tipos partilhados, configuração. O líder espera pela conclusão e recebe o contrato.

Vaga 2+ (Paralela): Assim que o contrato de schema chega, os agentes de API e frontend são criados em conjunto. Cada um recebe o contrato de schema no seu prompt, ao lado da atribuição de tarefa e linhas de posse de ficheiros.

Os prompts de criação de colegas seguem esta estrutura:

As peças fundamentais: limites de posse de ficheiros (nenhum dois agentes tocam nos mesmos ficheiros), contratos a montante (conteúdo real, não referências), e obrigações de contrato a jusante (o que este agente tem de produzir para outros).

Ativa o modo delegado para o líder coordenar em vez de escrever código ele próprio. Durante a execução, o trabalho do líder é observar a lista de tarefas, resolver discrepâncias de contratos e encorajar agentes que começam a derivar.

Codebases Existentes

A maior parte do trabalho real acontece dentro de um código existente. As equipas de agentes em codebases existentes precisam de consistência de convenções. Três agentes a editar o mesmo projeto ao mesmo tempo ainda precisam de seguir os padrões que já lá estão.

Correção: documenta as convenções do teu projeto no CLAUDE.md (nomenclatura, tratamento de erros, layout de ficheiros, abordagem de testes). As equipas de agentes leem o CLAUDE.md como contexto de runtime partilhado, por isso cada colega começa alinhado desde a linha um. Salta isto e um agente envia respostas de API em camelCase enquanto outro envia em snake_case porque cada um escolheu uma convenção por conta própria.

Passo 7: Validação Pós-Build

Os colegas a terminar as suas tarefas não é "feito". Builds paralelos produzem componentes que passam por si só mas racharm nas costuras. A validação apanha essas falhas.

Os critérios de aceitação e os comandos de validação do plano conduzem este passo. O líder (ou um agente dedicado de engenheiro de qualidade) percorre cada critério um por um:

O Problema dos Falsos Positivos

O cenário pós-build mais assustador: cada agente marca as suas tarefas como completas e reporta sucesso, mas há erros enterrados. Acontece porque os agentes são incentivados a fechar tarefas e às vezes aprovam o seu próprio trabalho.

Contraria-o pedindo evidências, não confirmação. Nunca perguntes "tudo funcionou?" Pede outputs específicos:

Exigir evidências força o líder a verificar realmente em vez de fazer correspondência de padrões por intuição. Mesma ideia que revisão de código: lês o diff, não perguntas ao autor se funcionou.

O Ciclo de Correção e Re-teste

Quando a validação encontra um problema, o ciclo é simples:

1. Líder identifica a discrepância (por exemplo, o handler de webhook devolve código de estado errado)
2. Líder envia mensagem ao colega responsável ou cria um agente de correção direcionado
3. A correção é aplicada
4. Líder re-corre as verificações de validação afetadas

A maioria das execuções converge em 1 ou 2 iterações se os contratos foram configurados corretamente. Sem contratos, o ciclo de correção e re-teste espirala porque cada correção desvenda outra discrepância de suposição. Essa espiral é exatamente o motivo pelo qual a cadeia de contratos existe.

Para ciclos de correção estruturados construídos em cadeias de dependências, o padrão construtor-validador formaliza isto como dependências de tarefas onde os validadores correm automaticamente depois dos construtores completarem.

Os passos 1-3 (planeamento) levam 15 a 30 minutos de trabalho interativo. Os passos 4-7 (execução) correm maioritariamente sem supervisão uma vez que a primeira vaga sai.

A proporção é o ponto: 30% do teu tempo em planeamento e contratos cancela os 70% de retrabalho que de outra forma consumirias a limpar falhas de integração de um build paralelo mal planeado.

Todos os sete passos podem ser feitos à mão com prompts crus. Mas as partes repetitivas (formatação de planos, derivação de cadeia de contratos, execução de vagas, sequenciamento de validação) são mecânicas o suficiente para serem embrulhadas em comandos reutilizáveis.

Os conceitos aqui (redução de suposições através de Q&A, cadeias de contratos entre vagas, validação baseada em evidências) aplicam-se independentemente de os correres com comandos, prompts crus, ou uma camada de orquestração personalizada.

Escolhe uma funcionalidade que cruza pelo menos duas camadas (frontend + backend, ou API + base de dados):

1. Brain dump do que queres
2. Faz Claude fazer-te 10 perguntas de clarificação
3. Constrói um plano estruturado com membros da equipa e cadeias de dependências
4. Começa de novo e deixa o líder derivar a cadeia de contratos
5. Observa os agentes a construir em vagas contra contratos partilhados
6. Valida os pontos de integração com evidências, não confirmação

A primeira execução demora mais porque estás a construir a memória muscular. Na terceira funcionalidade, o fluxo de trabalho torna-se segunda natureza e o compounding começa: os planos tornam-se modelos reutilizáveis, os contratos tornam-se interfaces padronizadas, e os critérios de validação acumulam-se numa linha de base de qualidade de todo o projeto.