Padrões de Agentes

Problema: Sub-agentes funcionam, mas continuas a recorrer à mesma forma sempre. Umas chamadas paralelas, dedos cruzados, cola manual no que vier de volta. Há uma forma melhor de organizar o trabalho com agentes, e a forma que escolhes decide se o output aguenta ou desmorona.

Seis padrões de orquestração aparecem repetidamente no trabalho real com Claude Code. Cada um serve um tipo diferente de tarefa. Escolhe mal e os tokens vazam, os ficheiros colidem ou as respostas derivam. Escolhe bem e um conjunto de agentes pode mastigar trabalho difícil com quase nenhuma supervisão.

Seletor de Padrões

Se só precisas de uma regra de seleção rápida, usa esta:

O erro é tratar os padrões como ideologia. São formas de carga de trabalho. Escolhe o que corresponde ao problema de coordenação à tua frente.

Lê esta página quando a questão aberta é a forma de orquestração. Se ainda estás a decidir entre subagentes, slash commands, definições de agente e regras de repositório, começa com Agent Fundamentals. Se a tua carga de trabalho precisa de várias sessões Claude a colaborar diretamente através de uma lista de tarefas e caixa de correio partilhadas, avança para Claude Code Agent Teams.

O Padrão Orchestrator

Um fio central gere tudo e distribui trabalho a especialistas. Nunca toca no código ele próprio. O seu trabalho todo é planear, delegar, rever e fazer routing.

Quando usar: Funcionalidades que cruzam frontend, backend e base de dados. Qualquer coisa onde alguém precisa de ter o quadro completo na cabeça.

Como funciona no Claude Code: O chat principal torna-se o maestro. Lê a especificação, elabora um plano e depois cria especialistas através da ferramenta Task. Os resultados voltam, são revistos e o próximo passo é decidido na hora.

You are the orchestrator. For this feature request, create a plan that:
1. Breaks the work into domain-specific tasks
2. Identifies dependencies between tasks
3. Dispatches each task to a sub-agent with explicit file scope
4. Reviews outputs before marking complete

Do NOT write implementation code yourself. Coordinate only.

O CLAUDE.md é o lugar natural para esta ligação. As regras de routing vivem nesse ficheiro e o maestro trata-as como um contrato. Numa configuração sólida, todo o grafo de dependências de tarefas é calculado primeiro, antes de qualquer sub-agente escrever uma linha.

Quando NÃO usar: Tarefas pequenas que um único agente pode terminar numa passagem. Adicionar um utilitário, corrigir um typo. A burocracia da orquestração é mais cara do que qualquer valor que traz.

O Padrão Fan-Out / Fan-In

Muitos agentes saem em paralelo. Todos reportam de volta. Um fio reúne os resultados numa única resposta.

Quando usar: Pesquisas abrangentes. Análise multi-ficheiro. Qualquer coisa onde cada agente trabalha nos seus próprios inputs sem sobreposição. Revisões de código em módulos independentes. Recolher informação de diferentes cantos de uma codebase antes de tomar qualquer decisão.

Como funciona no Claude Code: Lança sub-agentes paralelos emitindo várias chamadas à ferramenta Task na mesma mensagem. Cada um abre os seus próprios ficheiros ou persegue a sua própria preocupação. Quando todos os agentes regressam, o fio central junta as peças.

Complete these 4 tasks using parallel sub-agents:

1. Read src/api/ and list all endpoints missing input validation
2. Read src/auth/ and identify any hardcoded secrets or weak patterns
3. Read src/db/ and check for missing indexes on frequently queried columns
4. Read src/utils/ and flag any functions with no error handling

After all agents report back, synthesize findings into a prioritized action list.

A fase fan-out é rápida porque os agentes não partilham estado. A fase fan-in é onde está o valor: o orchestrator apanha ligações entre descobertas que nenhum agente solitário conseguiria ver. Um caminho de auth fraco mais uma lacuna na validação de input podem somar-se a uma exploração ativa, mesmo que nenhum relatório mostre isso sozinho.

Quando NÃO usar: Qualquer tarefa onde vários agentes precisam de editar ficheiros sobrepostos. Escritas concorrentes em código partilhado levam diretamente a conflitos de merge. Quando o trabalho não é genuinamente independente, uma cadeia sequencial é a escolha certa.

O Padrão de Cadeia de Validação

Um agente builder escreve o código. Um agente validator diferente inspeciona-o. Os papéis nunca se misturam.

Quando usar: Alterações de produção. Trabalho sensível à segurança. Qualquer lugar onde uma resposta errada custa dinheiro real. Usa este padrão quando enviar um bug simplesmente não é opção.

Como funciona no Claude Code: Duas tarefas ligadas por uma dependência. O builder entrega o código primeiro. Quando isso está feito, o validator abre o diff, corre os testes e apresenta o relatório, sem tocar num único ficheiro.

TaskCreate(
  subject="Build payment webhook handler",
  description="Create Stripe webhook handler in src/api/webhooks/stripe.ts.
  Handle checkout.session.completed, payment_intent.failed events.
  Verify webhook signatures. Include error handling."
)

TaskCreate(
  subject="Validate payment webhook handler",
  description="Read src/api/webhooks/stripe.ts. Verify:
  - Webhook signature verification exists
  - Both event types handled with proper responses
  - Error handling covers malformed payloads
  - No hardcoded secrets
  Report issues only. Do NOT modify any files."
)

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

A ligação addBlockedBy é o que mantém o validator honesto. Espera até o builder terminar e entra a frio. Sem suposições partilhadas. Sem pontos cegos herdados. Por isso a verificação apanha coisas de verdade.

Se o validator detetar um problema, abre uma tarefa de correção encaminhada para um builder. Depois, um novo validator enfileira-se atrás dessa correção. O ciclo aperta até o output estar correto.

Quando NÃO usar: Prototipagem descartável onde velocidade supera correção. Um validator dedicado aproximadamente dobra o compute por tarefa. Quando o código é rascunho, um agente leva-te lá mais depressa, com menos tokens.

O Padrão de Routing Especializado

Encaminha cada tarefa para o especialista de domínio que conhece o trabalho. Trabalho de frontend vai para o especialista de frontend. Migrações vão para o especialista de base de dados. Cada agente tem as suas próprias convenções, instruções e limites de ferramentas.

Quando usar: Repositórios grandes com vários domínios claros. Equipas com convenções estabelecidas por camada. Qualquer lugar onde instruções genéricas continuam a dar outputs inconsistentes na codebase.

Como funciona no Claude Code: Cria agentes especialistas em .claude/agents/, ou fixa regras de routing no teu CLAUDE.md. O orchestrator inspeciona a tarefa, identifica o domínio e entrega-a ao especialista certo.

<!-- In CLAUDE.md -->

## Agent Routing Table

| Task Domain | Route To            | File Scope           |
| ----------- | ------------------- | -------------------- |
| React/UI    | frontend-specialist | src/components/      |
| API routes  | backend-engineer    | src/api/, src/lib/   |
| Database    | database-specialist | src/db/, migrations/ |
| Security    | security-auditor    | Any (read-only)      |
| Tests       | quality-engineer    | tests/, **tests**/   |

Cada especialista definido em .claude/agents/ herda o teu CLAUDE.md automaticamente. Os padrões de código vêm incluídos. O ficheiro do próprio agente adiciona o resto: escolhas de framework, regras de nomenclatura, tratamento de erros moldado para aquela camada.

O crescimento é barato. Novo domínio significa um novo ficheiro de agente e uma nova linha na tabela de routing. Nada é reescrito. O guia de agentes personalizados explica como definir especialistas com YAML frontmatter.

Quando NÃO usar: Codebases pequenas onde um único agente já tem contexto suficiente sobre tudo. O overhead do routing não compensa quando há apenas um destino.

O Padrão de Refinamento Progressivo

Começa com um rascunho solto. Passa-o por várias rondas de edição. Cada ronda foca-se num único eixo de qualidade.

Quando usar: Trabalho de conteúdo, arquitetura emaranhada, qualquer tarefa onde acertar à primeira é irreal. Funciona bem em posts de blog, schemas de API ou ficheiros de configuração que precisam de satisfazer várias restrições ao mesmo tempo.

Como funciona no Claude Code: Coloca agentes em sequência onde cada um lê o output anterior e aperfeiçoa um aspeto.

Phase 1 - Draft: "Generate the initial API schema for a task management
system. Include all entities, relationships, and basic validation rules."

Phase 2 - Security review: "Review this schema. Add authentication
requirements, permission checks, and input sanitization rules.
Don't change the core structure."

Phase 3 - Performance review: "Review the schema for performance.
Add indexes, identify N+1 query risks, suggest denormalization
where read performance matters."

Phase 4 - Final validation: "Verify the schema is consistent.
Check that all referenced entities exist, foreign keys are valid,
and naming conventions are uniform."

Cada fase tem olhos estreitos. O agente de rascunho preocupa-se com completude. Segurança adiciona proteções. Performance afina. Validação verifica coerência. Nenhum agente é pedido para equilibrar todas as preocupações ao mesmo tempo.

Espelha como os developers reais trabalham. O código nunca chega à produção pronto na primeira passagem. Rascunhas, corriges a correção, afinas a performance, polishes. Este padrão entrega cada passagem a um agente moldado para ela.

Quando NÃO usar: Qualquer tarefa que tem de ficar pronta numa única passagem, onde a melhoria em camadas não está disponível. Também inútil em trabalho simples onde o primeiro rascunho já passa a fasquia.

O Padrão Watchdog

Um agente em background fica à espera de uma condição. Quando esta se verifica, o watchdog reporta ou age. Corre ao lado do teu trabalho principal, sem interferir.

Quando usar: Sessões longas onde a deriva se instala. Vigiar a saúde do contexto, detetar regressões durante um refactor, ou monitorar builds que ficam a vermelho enquanto a tua atenção está noutro sítio.

Como funciona no Claude Code: Envia um watchdog para background com Ctrl+B e volta ao que estavas a fazer. O agente verifica o seu gatilho numa cadência. Quando algo dispara, os resultados aparecem diretamente na tua lista de tarefas.

Background task: Monitor the test suite while I refactor the auth module.
Every time I complete a change, run the test suite for src/auth/.
If any test fails, immediately create a task with:
- Which test failed
- The assertion error
- Which file I likely broke based on the test name

Um bom exemplo vive no hook de recuperação de contexto. É um watchdog ligado à própria infraestrutura, acompanhando o uso do contexto e disparando recuperação no momento em que a janela começa a encher. Os hooks de saúde de agente e progresso funcionam da mesma forma.

Os watchdogs rendem mais quando combinados com workflows assíncronos, onde agentes em background correm por conta própria e mostram resultados à tua frente quando estiveres pronto.

Quando NÃO usar: Sessões curtas onde o custo de observar é maior do que o valor do que está a ser observado. Uma tarefa de dois minutos mais um watchdog a fazer polling a cada trinta segundos não compensa.

Combinar Padrões

Projetos reais quase nunca ficam dentro de um único padrão. Uma funcionalidade não trivial muitas vezes fica ligada assim:

1. Orchestrator lê a especificação e elabora o plano
2. Routing especializado entrega tarefas a especialistas de domínio
3. Fan-out corre as peças independentes em paralelo
4. Cadeias de validação avaliam o trabalho de cada especialista
5. Refinamento progressivo polis o resultado merged
6. Watchdog mantém olho no conjunto de testes durante todo o tempo

A habilidade não é memorizar a lista. É ler a tarefa à tua frente e combiná-la com a forma certa. Usa o padrão mais simples que consegue carregar a carga. Adiciona mais estrutura apenas quando esse falha.

Três Combinações que Funcionam Bem

1. Orchestrator + routing especializado

Melhor para:

• funcionalidades full-stack
• refactors entre camadas
• alterações que precisam de um cérebro coordenador

Por que funciona: o orchestrator guarda o plano, enquanto o routing mantém cada tarefa de implementação nas mãos certas.

2. Fan-out + cadeia de validação

Melhor para:

• auditorias abrangentes
• sweeps de segurança ou qualidade
• workflows com muita revisão

Por que funciona: agentes independentes recolhem descobertas em paralelo, depois um validator separado apanha conclusões fracas antes de qualquer coisa ser aprovada.

3. Refinamento progressivo + watchdog

Melhor para:

• workflows de conteúdo longos
• rascunhos de arquitetura
• qualquer coisa onde a qualidade sobe ao longo de várias passagens

Por que funciona: uma cadeia melhora o artefacto, enquanto o watchdog mantém olho no estado do sistema circundante, testes ou regressões.

Próximos passos:

• Agent Fundamentals, para como sub-agentes e slash commands se encaixam
• Sub-Agent Best Practices, para chamadas de routing paralelas versus sequenciais
• Team Orchestration, para o ciclo completo de builder e validator
• Task Distribution, para manter o trabalho multi-agente organizado
• Custom Agents, para escrever as tuas próprias definições de especialistas