Anderson LimaAI Developer
10 de abril de 2026
23 min de lectura
4,234 visualizaciones
Um guia prático para sair do hype e construir agents com contexto, guardrails, MCP e orquestração multiagente
Continúa explorando temas similares
Muita gente tenta resolver tudo com um prompt melhor, quando o problema real é a escolha errada da skill. Este guia mostra o que são skills no Claude Code, por que elas importam tanto e como escolher a skill correta para obter resultados mais consistentes, seguros e úteis.
O Claude Opus 4.7 mudou defaults importantes no Claude Code, incluindo effort level, adaptive thinking e padrões de uso de ferramentas. Este guia em português mostra o que mudou, quando cada estratégia funciona, quais são as vantagens e desvantagens e como escrever um CLAUDE.md melhor para fluxos longos e agentic.
Você está digitando as mesmas instruções que já deu centenas de vezes antes: - "Antes de fazer alterações, leia o arquivo primeiro" - "Execute os testes após cada alteração" - "Crie um commit git com mensagem descritiva" - "Certifique-se de seguir o estilo de código do projeto"
Una lista de 47 puntos para encontrar errores, riesgos de seguridad y problemas de rendimiento antes del lanzamiento.
Templates probados en producción, usados por desarrolladores. Ahorra semanas de setup en tu próximo proyecto.
Todo mundo quer "colocar um agent" no produto.
O problema é que a maior parte do mercado ainda chama de agent o que é só um prompt comprido com acesso ao terminal, ao Slack e ao banco. Funciona na demo. Falha no primeiro fluxo ambíguo, no primeiro limite de contexto e no primeiro incidente em produção. A consequência é previsível: times confundem autonomia com permissão, integração com arquitetura e orquestração com maturidade.
Se você quer usar Claude Code com seriedade, precisa começar por uma definição melhor. Um agent não é uma resposta mais esperta. Não é um chatbot com vinte tools. E não é um servidor MCP pendurado em cima de uma LLM.
Segundo a Anthropic, um agent é um modelo que dirige o próprio processo e o uso de ferramentas para concluir uma tarefa. Na prática, isso significa um loop autocontrolado de planejar, agir, observar, ajustar e repetir. Essa definição é importante porque separa o que é automação linear do que é agência real.
Este artigo faz três coisas. Primeiro, define com precisão o que é um agent. Depois, mostra como construir agents customizados para o seu projeto com Claude Code, CLAUDE.md, skills, hooks, MCP, subagents e Agent SDK. Por fim, entra no terreno que quase todo artigo evita: gestão de múltiplos agents, custos de coordenação e padrões de orquestração que realmente funcionam.
Minha tese é simples: o melhor agent quase nunca nasce de uma arquitetura grandiosa; ele nasce de um trabalho específico, restrições explícitas e um loop de verificação que aguenta produção.
O jeito mais rápido de estragar um projeto de agent é misturar três conceitos diferentes:
| Conceito | Como funciona | Quando usar |
|---|---|---|
| Chatbot | Responde e espera a próxima instrução | Q&A, suporte simples, busca pontual |
| Workflow | Segue uma sequência fixa de passos | Processos previsíveis, integrações estáveis |
| Agent | Decide a ordem dos passos e o uso das ferramentas para atingir um objetivo | Tarefas abertas, pesquisa, coding, investigação, coordenação |
Um chatbot conversa. Um workflow executa. Um agent decide.
Essa diferença parece semântica até o dia em que você precisa, por exemplo, investigar um bug intermitente em produção. Um workflow quebra porque o caminho não estava previsto. Um chatbot descreve possibilidades. Um agent útil faz outra coisa: ele lê logs, consulta arquivos, compara commits, muda a hipótese, pede contexto adicional quando necessário e volta com uma conclusão verificável.
Na página Trustworthy agents in practice, a Anthropic descreve quatro componentes que formam um agent de verdade:
Essa decomposição é excelente porque desmonta dois mitos comuns.
O primeiro mito é achar que o modelo sozinho é o agent. Não é. Sem harness, tools e environment, você só tem inteligência sem alavanca operacional.
O segundo mito é achar que MCP é o agent. Também não é. MCP é um protocolo para conectar hosts, clientes e servidores, expondo primitivas como tools, resources e prompts. Ele resolve integração. Quem resolve comportamento é o conjunto inteiro.
Se você nao consegue explicar o trabalho do agent sem mencionar a ferramenta primeiro, você ainda nao projetou o agent.
Quase todos os fracassos que vejo têm a mesma origem: o time começa pela superfície e não pelo trabalho.
Eles escolhem o stack antes do job to be done. Ligam cinco MCPs antes de definir qual decisão o agent precisa tomar. Criam um "agente geral de engenharia" antes de entender quais tarefas realmente se repetem. E dão permissões amplas para compensar a falta de especificidade.
O resultado aparece em quatro sintomas.
Um único agent tenta revisar PRs, responder dúvidas de arquitetura, abrir ticket no Jira, analisar incidentes e escrever código. Parece eficiente. Na prática, vira um ponto único de confusão.
Quanto mais amplo o escopo, maior a chance de contexto irrelevante competir com contexto crítico. Um agent muito genérico também fica mais caro, mais difícil de depurar e mais perigoso de operar.
Times apaixonados por MCP costumam medir maturidade pelo número de integrações conectadas. Isso é um erro de categoria. Integração sem modelo operacional não cria autonomia; só amplia a superfície de erro.
A própria documentação de Claude Code recomenda preferir CLIs como gh, aws, gcloud e sentry-cli quando elas já resolvem o problema de forma eficiente, e usar MCP quando o ganho de contexto externo realmente compensa. Em outras palavras: nem toda integração precisa virar protocolo.
Se quiser aprofundar essa tensão entre CLI e MCP, vale ler também A Ilusão do MCP.
Na página How Claude Code works, a Anthropic é direta: o loop agentic mistura três fases, gather context, take action e verify results. Essa terceira fase é onde muito projeto morre.
Sem testes, diffs, screenshots, logs ou checks explícitos, o agent não fecha o ciclo. Ele apenas produz saídas plausíveis. Em produção, plausibilidade sem verificação é outra palavra para incidente.
Múltiplos agents parecem sofisticados. Frequentemente são apenas caros.
Subagents, agent teams e orquestradores externos aumentam throughput quando o trabalho é paralelizável e quando cada worker tem fronteira clara. Fora disso, eles adicionam latência, custo de coordenação e risco de duplicação de esforço.
O erro nao é usar múltiplos agents. O erro é usá-los para esconder um problema de escopo mal definido.
O melhor jeito de entender Claude Code é vê-lo como um harness agentic pronto para produção local. Na documentação oficial, a Anthropic diz que Claude Code é o ambiente que fornece tools, context management e execution environment para transformar um modelo em um coding agent capaz.
Isso importa porque o produto já oferece quase tudo que um time sério precisa para sair do zero sem reescrever o motor inteiro:
CLAUDE.md e memórias persistentes;skills;hooks;MCP;subagents;agent teams, em modo experimental;Agent SDK, quando você quer transformar esse comportamento em software embarcado no seu produto.O ponto central é este: você nao precisa começar pelo SDK para construir um agent útil. A ordem certa costuma ser outra.
| Necessidade | Extensão certa em Claude Code | Por quê |
|---|---|---|
| Padrões, contexto do repo, contratos do time | CLAUDE.md | Mantém o agent alinhado ao projeto |
| Instruções reutilizáveis para tarefas recorrentes | skills | Encapsula playbooks e heurísticas |
| Automação e guardrails antes ou depois de tools | hooks | Impede ações perigosas e injeta contexto |
| Acesso a sistemas externos | MCP | Traz dados, tools e prompts de fora |
| Especialização de tarefas | subagents | Isola contexto e cria workers focados |
| Colaboração paralela com comunicação direta | agent teams | Permite coordenação peer-to-peer |
| Produto, serviço ou fluxo embarcado | Agent SDK | Usa o mesmo harness como biblioteca |
Essa tabela, sozinha, evita semanas de arquitetura errada.
Se você começar pelo topo, vai pagar custo antes de capturar valor. O caminho mais saudável é subir em camadas.
Não comece escrevendo "você é um agente senior expert world class". Isso não define nada que importe.
Comece com uma frase no formato job to be done:
"Quando um PR altera autenticação, eu quero revisar riscos reais e lacunas de teste antes do merge."
ou
"Quando existe um erro novo em produção, eu quero correlacionar stack trace, release, diff e hipótese de causa raiz sem tocar em produção."
Essa formulação ajuda porque define:
Sem isso, todo o resto vira decoração.
O primeiro arquivo de um agent maduro raramente é um subagent. É o CLAUDE.md.
Ele funciona como o acordo operacional do repositório. É onde você informa coisas que o modelo não deve redescobrir a cada sessão: convenções, comandos de validação, restrições, linguagem, expectativas de revisão, arquitetura e limites sensíveis.
Exemplo:
# Working Agreement
- Para mudanças com mais de um arquivo, comece em modo de plano.
- Nunca execute comandos contra produção.
- Toda correção de bug exige teste que falha antes e passa depois.
- Mudanças em `src/auth/**` devem rodar `pnpm test auth`.
- Se houver ambiguidade de produto, pare e peça decisão humana.
- Em revisões, priorize risco, regressão comportamental e falta de teste.
Esse arquivo tem um efeito poderoso: ele reduz improviso. E agent bom é, acima de tudo, um sistema que improvisa menos do que parece.
Na documentação de Claude Code, uma skill é um diretório com um SKILL.md que contém frontmatter e instruções. O name vira slash command, e a description ajuda o Claude a carregar a skill automaticamente quando o pedido bate com a intenção descrita.
Isso é ouro para times que repetem o mesmo tipo de trabalho.
Exemplo de uma skill de revisão para o seu projeto:
---
name: repo-pr-review
description: Revisa PRs neste repositório com foco em regressão, contratos de API, segurança e testes ausentes.
---
Ao revisar mudanças neste repositório:
1. Liste primeiro bugs, riscos e regressões.
2. Verifique se contratos públicos mudaram.
3. Confirme impacto em autenticação, billing e observabilidade.
4. Marque explicitamente o que não foi testado.
5. Só depois resuma.
Skills são melhores do que prompts colados no chat por três razões.
Agora sim entra o que a maioria chama de "agent customizado".
Na documentação oficial, subagents são assistentes especializados com system prompt próprio, tools específicas, permissões independentes e contexto isolado. Isso é importante porque subagents reduzem poluição de contexto. Em vez de despejar pesquisa, logs e arquivos no mesmo fio principal, você delega a um worker e recebe um resumo.
Exemplo de subagent para revisão de mudanças:
---
name: pr-reviewer
description: Revisa alterações de código, identifica risco real de regressão e aponta lacunas de teste antes do merge.
tools: Read, Glob, Grep, Bash
model: sonnet
memory: project
skills:
- repo-pr-review
color: cyan
---
Você é um revisor técnico especializado neste repositório.
Seu trabalho é:
1. Ler o diff e localizar os arquivos mais sensíveis.
2. Priorizar bugs, regressões comportamentais e impactos em contrato.
3. Conferir se testes relevantes existem e se cobrem os cenários de borda.
4. Responder em português, com referências objetivas a arquivos e risco.
5. Nunca aprovar mudanças; apenas levantar achados e incertezas.
Esse exemplo ilustra um ponto sutil, mas crucial. Um subagent não precisa ser "inteligente" no sentido genérico. Ele precisa ser previsível. Quanto menos ambição abstrata e mais foco operacional, melhor.
Se skills moldam raciocínio, hooks moldam comportamento operacional.
Na documentação de Claude Code, hooks podem rodar antes ou depois do uso de tools. O caso mais valioso em produção é PreToolUse, porque ele permite bloquear ações perigosas antes de elas acontecerem.
Exemplo de configuração para barrar comandos em produção:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "./scripts/block-production-commands.sh"
}
]
}
]
}
}
E o script:
#!/usr/bin/env bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qiE 'kubectl .*prod|terraform apply|psql .*prod|aws .*prod'; then
echo "Blocked: production commands require explicit human approval." >&2
exit 2
fi
exit 0
O detalhe importante está no exit 2: a documentação mostra que esse código bloqueia a execução da tool. É assim que você para de torcer para o agent agir com bom senso e passa a impor política real.
MCP merece uma regra própria: use quando a conexão com sistemas externos aumenta claramente a qualidade da decisão.
Pelo protocolo oficial, a arquitetura é host -> client -> server. O host, que no nosso caso pode ser o Claude Code, gerencia clientes; cada cliente mantém uma sessão isolada com um servidor; e os servidores expõem resources, tools e prompts. O desenho foi feito para manter isolamento entre servidores e fronteiras claras de segurança.
Na prática, eu recomendo pensar assim:
CLI local já resolve, comece por ela;MCP;Exemplos reais da própria documentação:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:password@db.internal:5432/analytics"
Esses três exemplos mostram uma boa combinação para um agent de engenharia:
Sentry para investigação de incidentes;GitHub para revisão, issues e PRs;Mas existe um ponto que muita gente omite. Na documentação de Claude Code, a Anthropic alerta que servidores MCP de terceiros podem introduzir riscos de segurança, inclusive prompt injection via conteúdo não confiável. Ou seja: MCP aumenta poder, mas também aumenta superfície de ataque.
Permissão não é detalhe. É arquitetura.
Em um projeto maduro, você quase sempre quer combinar:
Na página Trustworthy agents in practice, a Anthropic explica justamente por que Plan Mode existe: quando a tarefa tem muitas ações encadeadas, pedir aprovação passo a passo vira ruído; aprovar a estratégia inteira de uma vez preserva controle humano onde ele realmente importa.
Se você pedir "faça a task", vai receber uma execução plausível.
Se você pedir "faça a task, rode pnpm test, valide o screenshot da tela de checkout, confirme que não houve regressão em auth e me diga o que não conseguiu verificar", você obriga o agent a fechar o ciclo.
Esse é um dos melhores conselhos da documentação oficial: dê ao Claude uma forma de verificar o próprio trabalho.
A diferença entre um agent impressionante e um agent confiável está aqui.
Vamos sair da teoria e montar um caso que faz sentido em produção.
Imagine um time de SaaS com stack Next.js, Node.js, Postgres, Sentry e GitHub. Toda semana acontece a mesma dor: um erro novo aparece em produção, alguém abre cinco abas, troca contexto por quarenta minutos e só então começa a formar hipótese.
O objetivo do agent é simples:
Quando um erro novo surge em produção, eu quero montar uma hipótese inicial de causa raiz, correlacionando
Sentry, diff recente, logs locais e banco somente leitura, sem executar nenhuma ação destrutiva.
.claude/
agents/
incident-investigator.md
skills/
incident-playbook/SKILL.md
settings.json
CLAUDE.md
scripts/
block-production-commands.sh
---
name: incident-playbook
description: Investiga incidentes de produção com foco em timeline, blast radius, hipótese de causa raiz e próximos passos verificáveis.
---
Durante uma investigação:
1. Comece pela evidência, não pela opinião.
2. Identifique primeiro quando o erro começou e o que mudou próximo dali.
3. Delimite blast radius por endpoint, tenant, versão ou feature flag.
4. Gere no máximo três hipóteses, ordenadas por evidência.
5. Toda hipótese precisa de próximo passo verificável.
6. Nunca recomende ação destrutiva sem validação humana.
---
name: incident-investigator
description: Investiga erros de produção usando Sentry, GitHub, leitura de código e banco read-only para propor hipótese inicial de causa raiz.
tools: Read, Glob, Grep, Bash
model: sonnet
memory: project
skills:
- incident-playbook
mcpServers:
- sentry
- github
- db
---
Você é um investigador técnico.
Objetivo:
Entender rapidamente a provável causa raiz de um incidente sem executar alterações em produção.
Restrições:
1. Não escreva no banco.
2. Não faça deploy.
3. Não altere código.
4. Trabalhe com evidência e incerteza explícita.
Saída esperada:
- Resumo executivo do incidente
- Evidências principais
- Hipóteses ordenadas
- Próximos passos verificáveis
- Risco de impacto adicional
Sentry.GitHub.Perceba o desenho. Não existe "inteligência mágica". Existe uma sequência disciplinada:
É assim que agents deixam de ser brinquedo.
Essa é a pergunta que separa times pragmáticos de times fascinados por arquitetura.
Use subagents quando você precisa de especialização e isolamento de contexto.
Exemplos:
O fluxo é simples: o agent principal delega, o subagent trabalha no próprio contexto e volta com um resumo. Isso é barato, previsível e costuma ser suficiente para a maioria dos times.
Agent teams entram quando você quer colaboração paralela com comunicação direta entre agents. Na documentação experimental, a Anthropic descreve teams como um grupo de instâncias do Claude Code com task list compartilhada, messaging entre teammates e gerenciamento centralizado pelo host.
Esse modelo é mais poderoso, mas também mais caro. A própria documentação alerta para custo adicional de tokens e recomenda:
Sonnet para teammates;Em resumo: subagents são excelentes para "pesquise isso e volte". Agent teams fazem sentido quando os workers precisam trocar estado, validar hipóteses cruzadas ou coordenar um plano mais longo.
Se você quer embutir esse comportamento no seu produto, num serviço interno ou numa automação repetível fora da UI do Claude Code, aí entra o Agent SDK.
A própria Anthropic define o Agent SDK como a forma de construir agents de produção usando o mesmo harness do Claude Code como biblioteca, em Python ou TypeScript. Você ganha o loop agentic, as tools e a gestão de contexto sem precisar reimplementar tudo.
Meu critério prático é este:
Claude Code para experimentar, aprender e operar no fluxo de engenharia;subagents para especialização local;agent teams para colaboração paralela de alto valor;Agent SDK quando o comportamento precisa virar software executável fora do terminal.Se você precisa de múltiplos agents, não invente um organograma antes do problema. Comece por padrões simples.
Um agent principal recebe o objetivo e aciona especialistas.
Exemplo:
architect-reviewer para impacto estrutural;test-auditor para lacunas de cobertura;docs-checker para consistência de documentação.Esse é o melhor padrão para PRs grandes.
Um worker pesquisa, outro altera, outro verifica.
Esse padrão funciona bem para:
Ele força separação de responsabilidades e evita que o mesmo raciocínio justificando a mudança seja o único a validá-la.
Um agent central coordena:
sentry-analyst;git-history-investigator;db-reader.Esse padrão é excelente em incidentes porque divide o problema por fonte de evidência, não por tecnologia.
Se você produz documentação, ADRs ou conteúdo técnico, esse padrão rende muito.
Um agent escreve. Outro tenta quebrar a lógica, apontar ambiguidade, exagero e ausência de fonte. Para artigo, documentação e arquitetura, esse arranjo aumenta muito a qualidade final.
É fácil escrever teoria sobre agents. Mais difícil é mostrar casos públicos em que agentes já geram resultado observável.
Em 9 de março de 2026, a Anthropic anunciou o Code Review para Claude Code, descrito como um sistema de revisão baseado em agent teams, inspirado no fluxo interno da própria empresa. No post oficial, a empresa afirma que roda esse review em quase todo PR e compartilha um dado forte: antes, 16% dos PRs recebiam comentários substanciais; depois, esse número foi para 54%.
Esse caso ensina duas coisas.
Primeiro: multiagente funciona melhor quando o output esperado é revisão profunda, não execução cega.
Segundo: mesmo ali, a Anthropic mantém o humano como decisor final. O sistema não aprova PRs sozinho. Ele aumenta cobertura e profundidade.
No case público da Graphite, a empresa reporta:
Não é exatamente Claude Code, mas é a prova operacional de que agents especializados em revisão funcionam quando têm fronteira clara, objetivo preciso e integração forte com o fluxo do desenvolvedor.
Na página da Ramp com Claude, a empresa descreve uso intensivo em engenharia, com mais de 1 milhão de linhas de código sugeridas por IA em 30 dias e redução de 80% no tempo de investigação de incidentes.
O que interessa aqui não é o número isolado. É o padrão: o ganho aparece quando IA entra em tarefas com alto custo de contexto, como investigação, revisão e aceleração de implementação, e não quando é tratada como substituta genérica de decisão.
No case público da Mintlify, a empresa relata que Claude ajuda a resolver consultas de documentação e acelera o trabalho interno de engenharia. Esse tipo de caso reforça uma verdade pouco glamourosa: um dos melhores lugares para usar agent é onde existe texto, estrutura e custo alto de navegação de contexto.
Documentação, runbooks, decisões técnicas e incidentes são férteis porque o problema não é só gerar resposta; é encontrar, correlacionar e sintetizar.
A pergunta certa não é "quantos agents eu consigo orquestrar?". A pergunta certa é "qual custo de coordenação faz sentido para este trabalho?".
Aqui vai um conjunto de regras que eu usaria em produção.
MCP um servidor por vez.Se você ignorar essas regras, a complexidade volta em três formas:
Vale repetir porque esse é o ponto que mais distorce discussões hoje.
MCP é importante. Eu usaria sem hesitar para Sentry, GitHub, bancos read-only, documentação privada e sistemas internos. Mas MCP não substitui:
Times que começam conectando tudo tendem a terminar com um catálogo de ferramentas e nenhum agent realmente confiável.
Times que começam pelo trabalho e sobem a escada de customização chegam mais longe com menos arquitetura.
Antes de considerar seu agent pronto, responda sim para estas perguntas:
CLAUDE.md define restrições, comandos e critérios de qualidade?skill para o trabalho recorrente?hooks bloqueando ações perigosas?MCP é mínimo e justificado?Se a maioria for "não", o problema não é o modelo. O problema é design.
O mercado vai continuar chamando quase tudo de agent porque a palavra vende. Mas engenharia séria não pode operar no vocabulário do marketing.
Um agent de verdade é um sistema de decisão com ferramentas, contexto, ambiente, restrições e verificação. Claude Code é poderoso justamente porque deixa essas camadas visíveis e componíveis. Você pode começar simples, capturar valor rápido e subir em direção a skills, hooks, MCP, subagents, agent teams e Agent SDK sem reescrever a fundação a cada passo.
Se eu tivesse que resumir este artigo em uma linha, seria esta:
Nao construa um agent para parecer avançado. Construa um agent para tornar uma decisão repetida mais rápida, mais clara e mais segura.
Esse é o tipo de agent que sobrevive à primeira semana. E, com sorte, ao primeiro ano.