🚀 Avançado & cross-ambiente

Uma frota é um conjunto nomeado de subagentes com papéis distintos que o orquestrador pode escalar horizontalmente: um agente por tarefa, N tarefas em paralelo.

Sem o conceito de frota, você fica limitado a pipelines lineares. Com ele, o volume de trabalho cresce sem aumentar a complexidade do prompt principal.

Frota = conjunto + papel + paralelismo; orquestrador gerencia, não executa; cada membro reporta ao centro.

O orquestrador relança subagentes até que não haja mais itens para processar. O loop termina quando a fila está vazia, não depois de N tentativas fixas.

Tarefas de pesquisa, auditoria de código e análise de logs nunca têm tamanho previsível. O loop-until-dry garante completude sem hard-cap arbitrário.

Condição de parada = fila vazia; guarda de segurança = limite de iterações; relatório de progresso entre rodadas.

Um subagente separado recebe o resultado do agente principal e tenta refutá-lo ativamente — procura erros, lacunas, contradições — sem acesso ao raciocínio original.

LLMs tendem a confirmar o que geraram. O verificador adversarial quebra esse viés de confirmação sem precisar de revisão humana em cada iteração.

Isolamento de contexto; papel explícito de "refutador"; saída binária: aprovado / lista de falhas.

Um agente crítico compara o escopo inicial com a entrega final e lista o que ficou incompleto ou não foi abordado. É diferente do verificador adversarial: aqui o foco é cobertura, não correção.

Projetos grandes perdem partes inteiras de escopo silenciosamente. O completeness critic atua como checklist automatizado e fecha o ciclo.

Escopo como contrato; diferença cobertura × correção; saída: lista de gaps para relançar ou reportar.

O padrão de três estágios para pesquisa em escala: um finder coleta evidências, um verifier checa cada uma, um synthesizer produz o relatório final com fontes rastreadas.

Separa preocupações — busca, verificação e síntese em agentes dedicados — tornando cada etapa substituível e o resultado auditável.

Estágios desacoplados; handoff via artefato (arquivo ou JSON); rastreabilidade de fonte.

Um template mínimo de orquestrador que delega a N subagentes, coleta resultados e decide se relança ou encerra — o esqueleto que você copia e adapta.

Construir um harness do zero toda vez é trabalho repetido. O esqueleto expõe os pontos de extensão sem amarrar a lógica de domínio.

Ponto de entrada; lista de agentes; loop de coleta; condição de parada; saída estruturada.

Subagente é um padrão — contexto isolado, papel definido, relatório de volta — que existe em qualquer runtime que suporte chamadas de agente, não apenas no Claude Code.

Libera você de depender de um único vendor. A habilidade de desenhar sistemas multiagente vale em qualquer ferramenta que você use.

Padrão vs. implementação; portabilidade de conceito; mapeamento de primitivos entre runtimes.

O Codex CLI da OpenAI usa arquivos `.md` em `.codex/agents/` com a mesma filosofia: persona + ferramentas + disallowed-tools. A estrutura é análoga ao `.claude/agents/`.

Equipes usam múltiplas ferramentas. Saber mapear seu agente Claude para o Codex significa reutilizar a lógica sem reescrever do zero.

`.codex/agents/` ↔ `.claude/agents/`; campos equivalentes; diferenças de sintaxe e limitações.

Polyskill é o padrão de escrever uma única fonte de skill que se adapta ao runtime detectado — Claude Code, Codex ou outro — sem fork de arquivo.

Manter dois arquivos paralelos diverge inevitavelmente. O polyskill mantém uma verdade única e resolve a diferença na camada de adaptação.

Uma fonte, N saídas; seções condicionais; camada de adaptação vs. lógica de domínio.

Mapeamento lado a lado das ferramentas principais entre runtimes: Bash/Read/Write/Edit do Claude Code e seus correspondentes no Codex e outros ambientes.

Tradução explícita evita surpresas. Saber que "Bash" vira "shell" e "Edit" vira "patch" acelera a portabilidade e reduz bugs de adaptação.

Primitivos comuns (ler, escrever, executar); ferramentas sem equivalente direto; strategy para lacunas.

Uma skill portável usa linguagem de domínio no corpo — nunca nomes de ferramentas específicas — e delega a resolução de "qual ferramenta usar" para a seção de adaptação.

Skills com `Bash:` hardcoded falham silenciosamente em runtimes que não têm Bash. A portabilidade começa na escolha das palavras.

Abstração de ferramenta; seção "Tool mapping"; testes de portabilidade entre runtimes.

Walkthrough de um agente `code-reviewer` que roda no Claude Code e no Codex CLI sem modificação, mostrando onde a adaptação acontece e o que é idêntico.

Ver o exemplo concreto fixa o padrão. É a diferença entre entender o conceito e saber onde mexer quando algo quebra na portabilidade.

Seções invariantes vs. seções de adaptação; diff comentado; checklist de teste cross-runtime.

Cada papel de agente (raciocínio, execução, verificação, sumarização) tem requisitos diferentes de custo, velocidade e profundidade. Usar o mesmo modelo para tudo é desperdício ou risco.

A diferença de custo entre Opus e Haiku pode ser 50×. Numa frota de 20 agentes, a escolha errada de modelo é cara e lenta sem motivo.

Papel = requisitos; modelo = recurso; otimização por papel, não por projeto.

Opus = raciocínio complexo, planejamento, decisões de alto risco. Sonnet = execução equilibrada, código, análise. Haiku = triagem, sumarização, tarefas repetitivas de alto volume.

A tabela Modelo × Papel é a espinha de qualquer frota bem dimensionada. Sem ela, você testa no escuro e paga demais ou recebe qualidade abaixo do esperado.

Raciocínio profundo × throughput; custo por token; latência de resposta; limites de contexto por modelo.

GPT-4 pode ocupar papéis de execução onde o time já tem créditos ou integrações existentes. Codex (GPT-4-turbo fine-tuned para código) tem vantagem em geração de código em contextos específicos.

Frotas heterogêneas são a realidade em empresas. Saber onde cada modelo tem vantagem comparativa evita brigas de time e otimiza o portfólio de fornecedores.

Vantagem comparativa; lock-in vs. flexibilidade; API abstraction layer para trocar modelos sem reescrever agentes.

Orquestrador = Opus (planeja). Workers de execução = Sonnet (código, análise). Triagem e sumarização = Haiku. Verificação final = Opus ou Sonnet dependendo do risco.

O exemplo concreto transforma o princípio em decisão. Você sai com um template de alocação de modelos que adapta para qualquer projeto.

Template de alocação; critério de upgrade (quando usar modelo mais caro); critério de downgrade (quando é seguro usar mais barato).

Sinais que indicam trocar de provedor por papel: indisponibilidade recorrente, custo acima do benchmark, limitação de ferramentas, requisito de latência não atendida.

A decisão de trocar é frequentemente emocional ou política. Ter critérios objetivos por papel torna a decisão técnica e defensável.

SLO por papel; custo de migração; abstraction layer; teste A/B de modelos.

Exercício de mapear os papéis do seu sistema atual — ou planejado — e eleger o modelo mais adequado para cada um, com justificativa de custo e risco.

A matriz é o documento de design da frota. Ela comunica intenção, facilita onboarding e serve como referência na hora de otimizar.

Papel, modelo escolhido, justificativa, custo estimado, modelo alternativo de fallback.

Um arquivo `.md` de agente de fonte desconhecida pode conter instruções maliciosas embutidas no texto que o LLM executa como comandos ao processar o contexto.

A superfície de ataque cresceu com os catálogos públicos. O risco é real: um agente importado pode exfiltrar dados, modificar arquivos ou criar backdoors.

Confiança zero em fontes externas; auditar antes de executar; checklist de revisão de `.md`.

Prompt injection é a inserção de instruções para o LLM dentro de dados que o agente vai ler — comentários de código, conteúdo de arquivos, resultados de APIs — fazendo-o desviar do comportamento esperado.

O agente que lê código de um repositório ou resposta de uma API está potencialmente sendo instruído por esse conteúdo. Ignorar isso é a maior vulnerabilidade em sistemas multiagente.

Dados vs. instruções; contaminação de contexto; detecção de padrões suspeitos; sandboxing de entrada.

Um agente com `disallowed-tools: [Bash, Edit, Write]` que só pode ler — nunca executar, nunca modificar, nunca enviar dados para fora. O isolamento é declarado no próprio `.md`.

A verificação de conteúdo suspeito (um `.md` de terceiro, um arquivo de configuração) precisa ser feita por um agente que não pode causar dano mesmo se comprometido.

`disallowed-tools`; princípio do menor privilégio; separação entre ler e agir; relatório estruturado sem side effects.

Definir explicitamente quais ferramentas cada agente pode usar, revisando periodicamente se as permissões ainda correspondem ao papel atual — removendo o que não é mais necessário.

Permissões acumulam silenciosamente. Um agente de documentação que ganhou acesso ao Bash "por conveniência" é um risco que não aparece nos logs até ser tarde.

Mínimo privilégio; auditoria periódica; permissões explícitas vs. default; risco de scope creep.

MCPs expõem ferramentas externas para o agente. Um MCP comprometido ou malicioso pode exfiltrar dados, executar comandos remotos ou escalar privilégios sem que o agente perceba.

O MCP é o ponto de integração mais poderoso — e mais perigoso. A superfície de ataque cresce com cada MCP adicionado sem revisão de segurança.

Confiança zero em MCPs externos; revisão de código do servidor MCP; escopo mínimo de ferramentas expostas; logs de chamadas.

Um checklist de 8 pontos para revisar qualquer `.md` antes de colocar em produção: origem, permissões declaradas, instruções ocultas, acesso a rede, escopo de ferramentas, exfiltração, backdoors de bypass e revisão por segundo par de olhos.

Um processo repetível é a única forma de auditar com consistência. O checklist vira o gate de aprovação antes de qualquer `.md` externo entrar no repo.

Gate de aprovação; revisão manual obrigatória; quarentena antes de produção; versão mínima viável de processo de segurança.

Repositórios públicos como `awesome-claude-code-subagents` reúnem centenas de agentes prontos — security-auditor, test-runner, doc-writer, db-expert — mantidos pela comunidade.

Criar do zero custa tempo e introduz erros que outras pessoas já resolveram. Conhecer o ecossistema é o primeiro passo para acelerar sua biblioteca.

Catálogos curados vs. não-curados; critérios de qualidade; reputação do mantenedor; licença.

Começar com um agente testado pela comunidade e adaptar é sistematicamente mais rápido e mais confiável do que criar do zero, mesmo que o resultado final seja quase idêntico.

O NIH (not invented here) é caro em tempo e qualidade. O princípio do reuso muda o ponto de partida de "criar" para "encontrar + adaptar".

Ponto de partida inteligente; adaptação vs. reescrita; custo de manutenção comparado.

Quatro passos: baixar o `.md` de origem confiável, auditar com o checklist de segurança (M4.4), adaptar nome/persona/ferramentas ao seu contexto, colocar em `.claude/agents/` e testar.

O fluxo estruturado evita o atalho perigoso de baixar e usar sem auditar. A etapa de auditoria não é opcional mesmo em fontes confiáveis.

Quarentena; gate de auditoria; adaptação mínima vs. completa; teste de smoke após importação.

Walkthrough de adaptação de um `security-reviewer` genérico para o contexto de um projeto Python específico: ajuste de persona, contexto de projeto, ferramentas e exemplos inline.

A adaptação é onde a maioria erra — ou não adapta nada (agente genérico demais) ou reescreve tudo (perde os benefícios do reuso). O exemplo mostra o equilíbrio.

O que adaptar (persona, contexto, exemplos) vs. o que manter (lógica de decisão, formato de saída, safety).

Agentes importados podem receber updates no repositório de origem. Você precisa decidir: sincronizar com o original, manter fork local ou congelar a versão. Cada escolha tem trade-offs.

A gestão do ciclo de vida do agente importado é ignorada na fase de adoção e vira dívida técnica depois. Decidir a estratégia no início poupa retrabalho.

Fork vs. upstream sync; changelog tracking; versão mínima testada; política de update.

Quando e como publicar seus agentes adaptados de volta — anonimizando contexto de projeto, adicionando README, escolhendo licença e submetendo PR para catálogos curados.

A qualidade dos catálogos depende de contribuições. Publicar força você a generalizar bem o agente, o que frequentemente melhora a versão interna também.

Anonimização de dados sensíveis; README mínimo; critérios de qualidade do catálogo; licença compatível.

Um conjunto pessoal de agentes reutilizáveis organizados em `.claude/agents/` — security-auditor, test-runner, doc-writer, db-expert, code-reviewer — que você mantém e evolui ao longo do tempo.

A biblioteca é o ativo que cresce com você. Cada projeto bem executado adiciona um agente ao acervo; com o tempo, você começa novos projetos já com especialistas prontos.

Acervo pessoal; versionamento da biblioteca; README por agente; categorias (segurança, teste, docs, infra, dados).

Os 5 agentes que cobrem 80% das necessidades na maioria dos projetos de software: security-reviewer (read-only), test-runner, doc-writer, code-reviewer e db-migration-checker.

Ter um pacote inicial definido elimina a paralisia de decisão. Você começa com um conjunto coeso e expande conforme necessidade real, não antecipação.

Cobertura de 80%; conjunto mínimo coeso; critério de adição (necessidade real demonstrada); não antecipar.

Templates de `.md` com estrutura padrão (nome, persona, descrição, ferramentas, disallowed-tools, exemplos) que você preenche em minutos para qualquer novo papel de agente.

Um template bem feito garante que você não esquece campos críticos (disallowed-tools, exemplos de uso) e mantém consistência entre todos os agentes da biblioteca.

Template mínimo vs. template completo; campos obrigatórios vs. opcionais; consistência como meta.

Um gate de 10 pontos antes de colocar qualquer agente em uso real: permissões revisadas, disallowed-tools explícito, exemplos testados, persona clara, sem instruções ambíguas, auditoria de segurança.

Agentes que não passam por checklist antes de produção acumulam comportamentos inesperados. O checklist é o equivalente do code review para `.md`.

Gate de produção; revisão de par; smoke test; critério de "pronto para usar".

O exercício de conclusão do curso: mapear os papéis do seu trabalho real, eleger modelos para cada um, criar 3 agentes da biblioteca pessoal e documentar a frota desenhada.

O aprendizado se consolida na aplicação. O projeto final fecha o ciclo: do modelo mental (T1) à frota em produção (T4).

Aplicação ao contexto real; 3 agentes mínimos; documentação da frota; critério de verificação — "como sei que acertei".

Síntese das quatro trilhas: T1 (modelo mental) → T2 (criar o `.md`) → T3 (orquestrar e economizar) → T4 (escalar, proteger e reutilizar). Uma visão panorâmica do que você aprendeu.

O recap consolida o mapa mental completo e mostra a progressão de fundamentos a sistema avançado — o que facilita revisar, ensinar ou adaptar para novos contextos.

Progressão T1→T4; conceitos-âncora de cada trilha; próximos passos; onde aprofundar.