Equipas de Agentes Builder-Validator

Problema: Agentes paralelos no Claude Code são rápidos. Mas sem papéis claros, devolvem resultados inconsistentes e acabas por verificar cada linha tu mesmo. O que queres são agentes que avaliem o trabalho uns dos outros.

À procura das Agent Teams nativas? O Claude Code tem agora uma funcionalidade integrada de Agent Teams para colaboração multi-agente. Este post cobre a abordagem DIY com Task tools, que funciona sem ativar funcionalidades experimentais.

Ganho Rápido: Cola esta cadeia builder-validator na tua próxima tarefa com múltiplos ficheiros. O validator corre em modo de só leitura, logo após o builder terminar:

TaskCreate(subject="Build auth middleware", description="Create JWT validation middleware in src/middleware/auth.ts. Export verifyToken and requireAuth functions.")
TaskCreate(subject="Validate auth middleware", description="Read src/middleware/auth.ts. Verify: exports exist, error handling covers expired/malformed tokens, no hardcoded secrets. Report issues only. Do NOT modify files.")
TaskUpdate(taskId="2", addBlockedBy=["1"])

A Tarefa 2 espera até a Tarefa 1 terminar. O validator lê, nunca escreve. Dois agentes. Um output em que podes confiar.

Por Que os Pares Batem os Agentes Solitários

Os fundamentos de agentes cobrem o que são sub-agentes. A distribuição de tarefas cobre como executá-los em paralelo para ganhar velocidade. As boas práticas de sub-agentes cobrem o routing. Este post cobre algo diferente: dar papéis aos agentes e juntá-los em equipas.

Os agentes solitários têm uma falha simples. Um agente que escreveu o código é a pior escolha para o rever. Mesmos pontos cegos, mesmas suposições, mesmos atalhos. Coloca um validator independente e apanhas o que o builder deixou passar, porque o validator começa do zero.

É pela mesma razão que as equipas humanas não deixam o autor ser o único revisor. Trazes outro par de olhos.

O Padrão Builder-Validator

Builders escrevem código. Validators leem código. Os papéis nunca se sobrepõem.

Prompt do builder - focado na criação:

You are a builder agent. Your job:
 
1. Read the task description carefully
2. Implement the solution in the specified files
3. Run any relevant tests
4. Mark your task complete
 
Rules:
 
- Only modify files listed in your task
- Do not modify test files (validators handle test verification)
- If you hit a blocker, document it in the task description and mark complete

Prompt do validator - focado na verificação:

You are a validator agent. Your job:
 
1. Read all files the builder created or modified
2. Check against the acceptance criteria in the task description
3. Run the test suite
4. Report findings as a new task if issues exist
 
Rules:
 
- Do NOT modify any source files
- Do NOT create new implementation code
- You may only create or update task entries to report issues
- Use Read and Bash (for tests) only - never Edit or Write

A restrição-chave: validators não podem escrever código. Isso obriga-os a expor problemas reais, em vez de corrigir silenciosamente as coisas e saltar a revisão. Quando um validator deteta um problema, cria uma nova tarefa que volta para um builder. Podes reforçar isto ao nível da ferramenta com definições de agente personalizadas e disallowedTools, que remove Edit e Write dos validators por completo.

Cadeias de Dependência para Build-Depois-Valida

O parâmetro addBlockedBy no TaskUpdate é o que cola este padrão. Os validators esperam pelo builder deles sem nenhuma ligação extra:

// Phase 1: Parallel builders
TaskCreate(subject="Build user API routes", description="Create CRUD endpoints in src/api/users.ts...")
TaskCreate(subject="Build user database schema", description="Create migration in src/db/migrations/...")

// Phase 2: Validators blocked by their builders
TaskCreate(subject="Validate API routes", description="Read src/api/users.ts. Verify REST conventions, error handling, input validation...")
TaskCreate(subject="Validate database schema", description="Read migration files. Verify column types, indexes, foreign keys...")

TaskUpdate(taskId="3", addBlockedBy=["1"])
TaskUpdate(taskId="4", addBlockedBy=["2"])

As Tarefas 1 e 2 correm lado a lado porque tocam ficheiros diferentes. As Tarefas 3 e 4 esperam cada uma pelo seu builder. Velocidade paralela na fase de build. Verificações independentes em cada output.

Verificações transversais que precisam que tudo esteja construído primeiro acumulam simplesmente múltiplos bloqueadores:

TaskCreate(subject="Integration validation", description="Verify API routes correctly reference the database schema. Check that all referenced tables and columns exist.")
TaskUpdate(taskId="5", addBlockedBy=["1", "2"])

Um Meta-Prompt que Constrói o Plano Completo

Montar cadeias de tarefas à mão cansa. Um meta-prompt no CLAUDE.md pode transformar um pedido de funcionalidade num plano de equipa completo na hora:

## Team Plan Generation
 
When I say "team plan: [feature]", generate a task structure:
 
For each component:
 
1. TaskCreate a builder task with specific files and acceptance criteria
2. TaskCreate a validator task scoped to read-only verification
3. TaskUpdate to chain validator behind its builder
 
After all component pairs, add one integration validator blocked by ALL builders.
 
Format each task description with:
 
- **Files**: exact paths to create or read
- **Criteria**: measurable acceptance conditions
- **Constraints**: what this agent must NOT do

Agora podes simplesmente dizer: "team plan: adicionar handler de webhook Stripe." O Claude devolve o grafo de dependências completo, emparelha cada componente com o seu validator, e coloca um validator de integração no final. Tu lês o plano, dizes para avançar, os agentes executam.

Este é o padrão orchestrator em ação. A tua sessão principal do Claude coordena. Escreve o plano, liga os bloqueadores e despacha os agentes. Não escreve o código da aplicação ele próprio.

Quando Uma Validação Falha

O ciclo continua quando um validator sinaliza um problema:

O validator cria uma tarefa de correção que diz o que está partido
Um agente builder pega na tarefa de correção
Uma nova tarefa de validação encadeia-se atrás da correção

// Validator found missing error handling
TaskCreate(subject="Fix: add error handling to user API", description="The GET /users/:id endpoint returns 500 on invalid ID format. Add input validation and return 400 for malformed IDs.")
TaskCreate(subject="Re-validate user API error handling", description="Verify GET /users/:id returns 400 for non-UUID strings, 404 for valid UUID not found, 200 for valid existing user.")
TaskUpdate(taskId="7", addBlockedBy=["6"])

Cada ciclo aperta o foco. O primeiro builder trata da funcionalidade completa. Os builders seguintes tratam de um bug de cada vez. O ciclo leva o código até ao correto sem precisares de depurar manualmente os passos intermédios.

Para verificações mais exigentes, hooks podem correr regras automáticas em cada alteração de ficheiro, para que os problemas sejam apanhados antes de o agente validator sequer acordar. Podes ir mais longe integrando a validação diretamente nas definições de agente, tornando a verificação de qualidade parte da identidade do agente.

Começa com Um Par

Não mudes o teu workflow todo de uma vez. Escolhe a próxima funcionalidade que toca dois ou mais ficheiros. Cria uma tarefa builder. Cria uma tarefa validator com addBlockedBy. Vê o validator sinalizar algo que o builder passou a correr.

Depois de veres funcionar, aumenta a escala: builders paralelos com validators encadeados, meta-prompts a escrever o plano, validators de integração a ligar tudo. Constrói o teu setup de agentes em torno de papéis bem definidos. Deixa o sistema de tarefas tratar da ordem. Tu ficas com as decisões.