Como Usar Agentes do Claude Code: Configuração, Ferramentas, Permissões e Fluxo de Trabalho com Sandbox

Para usar bem os agentes do Claude Code, trate o Claude Code como um loop de agente, não como uma janela de chat: inicie-o dentro do repositório que você deseja alterar, dê a ele instruções claras do projeto, conecte apenas as ferramentas que ele realmente precisa, mantenha as permissões restritas e execute a execução em um runtime isolado quando o fluxo de trabalho for além de edições locais de baixo risco. Essa é a diferença entre uma sessão de codificação útil e uma cara e bagunçada.

Se sua pergunta principal for mais ampla que o próprio Claude Code, comece com O que são Agentes de Codificação? para a visão arquitetural. Se você está decidindo entre ferramentas primeiro, compare Claude Code vs Cursor. Este guia é mais específico: como usar agentes do Claude Code na prática.

O que as pessoas geralmente querem dizer com “agentes de Claude Code”

A maioria dos desenvolvedores que busca por “agentes de Claude Code” quer dizer uma de duas coisas:

1. O próprio Claude Code atuando como um agente de codificação autônomo.
2. Múltiplos agentes, ferramentas ou subagentes especializados trabalhando dentro de um fluxo de trabalho do Claude Code.

Ambos são válidos. O Claude Code já se comporta como uma ferramenta de codificação agêntica: ele pode inspecionar um repositório, editar arquivos, executar comandos e reagir aos resultados. A Anthropic também documenta blocos de construção relacionados, como integrações de ferramentas MCP, hooks e subagentes, e é por isso que o termo frequentemente aparece no plural.

O modelo prático é simples:

• Claude Code é o fluxo de trabalho principal.
• O modelo lida com o planejamento e as decisões de próximos passos.
• Ferramentas fornecem acesso a arquivos, comandos, navegadores, APIs e sistemas externos.
• Permissões decidem o que o Claude pode fazer sem perguntar.
• Um sandbox oferece um lugar seguro para executar código e ferramentas.

Se você mantiver essas cinco camadas separadas, o Claude Code se torna muito mais fácil de operar de forma confiável.

Passo 1: Instale o Claude Code e inicie no diretório certo

A Anthropic documenta o Claude Code como um CLI instalável. O caminho de instalação padrão é:

npm install -g @anthropic-ai/claude-code
claude

O detalhe importante não é apenas a instalação. Inicie o Claude Code a partir do repositório em que você deseja que ele trabalhe. O Claude Code lê o diretório atual, as instruções locais do projeto e qualquer configuração de ferramenta específica do projeto a partir daí.

Se o repositório for novo, execute:

/init

Isso gera um arquivo inicial CLAUDE.md com instruções específicas do projeto. Use-o para coisas que o Claude deve lembrar em todas as sessões: comandos de teste preferidos, padrões de codificação, limites de arquitetura, expectativas de revisão e arquivos que ele deve tratar com cuidado.

Isso importa mais do que a maioria dos usuários espera. Um agente do Claude Code sem instruções específicas do repositório geralmente não é subdimensionado. Ele é subespecificado.

Passo 2: Dê ao agente uma tarefa que ele possa realmente executar

O Claude Code funciona melhor quando a tarefa inclui um resultado concreto e uma etapa de verificação.

Bons exemplos:

• “Adicione rate limiting em /login, atualize os testes e execute o arquivo de teste afetado.”
• “Refatore o serviço de cobrança para usar o novo cliente e execute os testes unitários desse pacote.”
• “Revise este diff de PR para problemas de segurança e correção.”

Prompts fracos geralmente são vagos exatamente da maneira errada:

• “Melhore este código.”
• “Deixe o aplicativo melhor.”
• “Verifique o projeto.”

Ferramentas de codificação agênticas funcionam melhor quando a linha de chegada é explícita. Se você quer autonomia, defina o sucesso. Se você quer exploração, defina o escopo.

Passo 3: Configure apenas as ferramentas que você precisa

O Claude Code usa o Model Context Protocol para ferramentas externas. Na prática, isso significa que os servidores MCP são a superfície de extensão para navegadores, bancos de dados, rastreadores de problemas, GitHub, executores de código e serviços internos.

O comando de configuração mais comum é:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Isso dá ao Claude ferramentas de automação de navegador. A documentação MCP da Anthropic e o quickstart cobrem o mesmo padrão para outros servidores.

A regra operacional principal é a moderação: não anexe todas as ferramentas que você pode querer um dia. Anexe o menor conjunto de ferramentas que corresponda ao trabalho. Muitas ferramentas aumentam o ruído de inicialização, ampliam a superfície de ação e tornam a seleção de ferramentas menos previsível.

Para a maioria dos trabalhos de repositório, um conjunto inicial sensato é:

• acesso local a arquivos e shell
• uma ferramenta de navegador se o QA web for necessário
• uma ferramenta de issues ou documentação se a tarefa depender de um sistema externo

Todo o resto deve merecer seu lugar.

Passo 4: Use permissões deliberadamente, não como uma reflexão tardia

Uma das maiores diferenças entre um fluxo de trabalho seguro do Claude Code e um imprudente é a disciplina de permissões.

O Claude Code expõe controles de permissão porque a execução de ferramentas é o verdadeiro limite de risco. Ler um arquivo é uma coisa. Executar scripts de instalação, excluir diretórios ou acessar serviços externos é outra.

Use /permissions no início de um projeto, especialmente se a sessão puder:

• escrever em muitos arquivos
• executar comandos de shell
• instalar pacotes
• acessar segredos ou sistemas internos
• chamar ferramentas MCP com efeitos colaterais

A configuração certa depende do trabalho:

• Para depuração exploratória, perguntar antes de executar é geralmente o padrão mais seguro.
• Para trabalho repetitivo e bem definido no repositório, regras de permissão podem reduzir interrupções.
• Para comandos de alto risco ou caminhos sensíveis, regras de negação devem permanecer explícitas.

É aqui que muitas equipes fazem a otimização errada. Elas removem o atrito abrindo permissões demais e depois tentam recuperar o controle apenas com a redação do prompt. Isso é ao contrário. O prompt é orientação. As permissões são a aplicação.

Passo 5: Entenda o loop real do agente

O Claude Code parece poderoso quando você entende o que está acontecendo por baixo dos panos.

O loop geralmente é assim:

1. O Claude lê a tarefa e o contexto do projeto.
2. Ele planeja o próximo passo útil.
3. Ele lê arquivos ou chama ferramentas.
4. Ele edita código ou executa um comando.
5. Ele verifica a saída.
6. Ele revisa o plano com base no que aconteceu.
7. Ele para quando o resultado solicitado está completo.

Esse loop explica por que os fluxos de trabalho de agente são diferentes do uso normal de chatbot. O modelo não está apenas gerando código. Ele está coordenando o estado entre ferramentas, arquivos, saída de comandos e falhas intermediárias.

Para trabalho real em repositórios, as partes mais importantes geralmente não são a primeira resposta. São as etapas de recuperação após a primeira falha de teste, erro de lint ou incompatibilidade de ambiente.

Passo 6: Use subagentes quando a especialização ajudar

O Claude Code agora inclui suporte a subagentes porque um agente de propósito geral nem sempre é a melhor opção para cada tarefa.

Subagentes fazem sentido quando o fluxo de trabalho se beneficia da especialização, por exemplo:

• um agente para implementação
• um agente para revisão de código
• um agente para documentação
• um agente para investigação de testes

Isso não significa que todo projeto precisa de um enxame. Em repositórios pequenos, vários agentes podem adicionar mais sobrecarga do que valor. Mas para equipes com entregas repetitivas, os subagentes são úteis porque permitem codificar instruções e responsabilidades mais específicas.

O princípio operacional é o mesmo que boas equipes de engenharia já usam: separe papéis quando os limites forem claros o suficiente para serem úteis.

Se você não consegue explicar por que um segundo agente existe, provavelmente não precisa dele.

Passo 7: Use hooks para controle e auditabilidade

Hooks são a resposta certa quando você quer que as sessões do Claude Code acionem verificações previsíveis em pontos específicos do fluxo de trabalho.

Exemplos:

• executar formatação após edições de arquivo
• registrar alterações de arquivo após operações de escrita
• bloquear comandos que tocam caminhos protegidos
• enviar eventos para um trilho de auditoria local

Hooks importam porque tornam o fluxo de trabalho menos dependente de o agente lembrar de cada política toda vez. Se um passo deve sempre acontecer após uma categoria de ação, automatize esse limite em vez de esperar que o prompt da sessão seja suficiente.

Isso é especialmente importante quando o Claude Code se torna parte de um processo de equipe repetitivo, em vez de uma ferramenta individual de uso único.

Onde a Novita se encaixa em uma stack de agentes do Claude Code

O Claude Code é a interface do agente. Não é a stack inteira.

Quando uma equipe usa o Claude Code seriamente, duas questões de infraestrutura separadas aparecem:

1. Qual backend de modelo deve lidar com o raciocínio?
2. Onde a execução de ferramentas deve realmente rodar?

Esses são exatamente os lugares onde a Novita se encaixa naturalmente.

Use a API LLM da Novita para flexibilidade de backend

A Novita documenta um endpoint compatível com Anthropic para fluxos de trabalho estilo Claude Code. Isso significa que você pode manter o padrão de interação do Claude Code enquanto direciona o tráfego de modelo para modelos hospedados na Novita em vez de apenas uma rota padrão.

O padrão de ambiente é:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<sua-chave-api-novita>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

Essa configuração é útil quando você quer comparar diferentes modelos de codificação sem reconstruir sua camada de ferramentas.

Ela também cria um caminho mais natural para equipes que querem a ergonomia do Claude Code, mas não uma suposição de modelo único. A interface permanece familiar; o backend se torna testável.

Use o Novita Agent Sandbox para isolamento de execução

A segunda metade do problema é a execução.

Um agente do Claude Code que apenas lê e escreve pequenos arquivos locais é uma coisa. Um agente do Claude Code que executa comandos, instala pacotes, lança navegadores, baixa dependências ou toca sistemas semelhantes a produção é outra.

É aí que um runtime isolado deixa de ser opcional e passa a fazer parte do design.

O Novita Agent Sandbox é posicionado exatamente para essa camada: ambientes isolados para execução de código, trabalho com sistema de arquivos, automação de navegador e fluxos de trabalho de agente de longa duração. Em outras palavras, ele cobre a parte da stack onde os efeitos colaterais acontecem.

O modelo mental limpo é:

• use Claude Code para o fluxo de trabalho do agente
• use Novita LLM API para roteamento de modelo e experimentação
• use Novita Agent Sandbox para limites de execução seguros

Manter raciocínio e execução separados geralmente é a melhor arquitetura de longo prazo.

Uma opção prática de modelo aberto dentro do mesmo fluxo de trabalho

Depois que você tiver o Claude Code funcionando bem, a próxima pergunta geralmente não é “Isso pode usar agentes?” É “Qual backend vale a pena pagar todos os dias?”

É aqui que os modelos de codificação de peso aberto se tornam interessantes de uma forma muito prática. Se sua equipe gosta da interface do Claude Code, mas quer experimentação mais barata ou mais flexibilidade de provedor, um modelo aberto pode ser o próximo benchmark certo.

Um candidato confiável é Qwen3-Coder-480B-A35B-Instruct através da rota compatível com Anthropic da Novita. Você não precisa tratá-lo como uma substituição garantida do Claude em todas as tarefas. Você deve tratá-lo como uma opção séria de modelo de codificação que pertence ao mesmo conjunto de avaliação que alternativas fechadas.

Essa é a mudança natural que muitas equipes fazem:

• manter o fluxo de trabalho do agente
• manter as ferramentas
• manter o modelo de permissões
• mudar o backend e comparar resultados reais de tarefas

Se o trabalho é dominado por navegação de repositório, implementação direta e chamada de ferramentas em vez de raciocínio de nível de fronteira, um modelo aberto pode ser competitivo o suficiente para justificar o teste.

Isso é uma das coisas mais úteis sobre a configuração da Novita: ela permite que você compare essa questão dentro de um fluxo de trabalho familiar do Claude Code em vez de transformar o benchmark em um projeto de migração.

Erros comuns ao usar agentes do Claude Code

A maioria das falhas vem do design do fluxo de trabalho, não da ideia de codificação agêntica em si.

Dar ao agente metas amplas sem uma linha de chegada

Se você quer resultados confiáveis, especifique o entregável e como verificá-lo.

Anexar muitas ferramentas

Mais ferramentas não tornam o Claude automaticamente mais inteligente. Elas geralmente tornam o roteamento mais ruidoso.

Tratar permissões como um incômodo de UX

Permissões são o plano de controle para efeitos colaterais. Elas devem ser ajustadas, não ignoradas.

Executar ações arriscadas diretamente na máquina do desenvolvedor

Se o agente está fazendo automação de navegador, instalação de pacotes ou execução repetitiva de comandos, use um runtime isolado.

Confundir uma demonstração útil com um fluxo de trabalho de produção

Uma demonstração do Claude Code pode parecer boa em cinco minutos. Um fluxo de trabalho de produção precisa de política, auditoria, isolamento de runtime e disciplina de escolha de modelo.

Fluxo de trabalho recomendado para a maioria das equipes

Se você quer um padrão pragmático, use esta ordem:

1. Inicie o Claude Code no repositório de destino.
2. Execute /init e torne o CLAUDE.md útil.
3. Anexe apenas as ferramentas MCP necessárias para a tarefa.
4. Configure /permissions antes de execução ampla.
5. Use um sandbox quando o fluxo de trabalho executar código real ou etapas de navegador.
6. Compare pelo menos um backend alternativo através da Novita antes de padronizar suposições de custo.

Essa sequência mantém o sistema compreensível. Ela também evita que você misture ergonomia de produto, qualidade de modelo, proliferação de ferramentas e segurança de runtime em uma decisão confusa.

FAQ

O Claude Code é um agente?

Sim. O Claude Code é um fluxo de trabalho de codificação agêntica, não uma ferramenta de autocompletar código. Ele pode inspecionar arquivos, editar código, executar comandos e reagir a resultados de ferramentas.

Preciso de MCP para usar agentes do Claude Code?

Não. O Claude Code é útil apenas com acesso local ao repositório. O MCP se torna importante quando você quer ferramentas externas como navegadores, bancos de dados, APIs ou sistemas de issues.

Quando devo usar um sandbox com Claude Code?

Use um quando o fluxo de trabalho executar código, instalar pacotes, lançar navegadores ou realizar ações repetitivas com efeitos colaterais que você não quer executar diretamente no host.

O Claude Code pode usar modelos através da Novita?

A Novita documenta uma configuração compatível com Anthropic para fluxos de trabalho do Claude Code, então você pode manter a interface do Claude Code enquanto roteia as solicitações de modelo para modelos hospedados na Novita.

Devo usar vários subagentes imediatamente?

Geralmente não. Comece com um agente e adicione subagentes apenas quando a especialização for clara o suficiente para reduzir confusão em vez de criá-la.

Artigos Recomendados

• Plugins do Claude Code: Como as Ferramentas MCP Estendem o Claude Code com Capacidades Externas
• Modelos Suportados pelo Claude Code em 2026: Qual Você Deve Usar?
• O que são Agentes de Codificação? Como Eles Funcionam e Como Construir um

Fontes verificadas em 24 de agosto de 2026: Visão geral do Claude Code da Anthropic, Configurações e permissões do Claude Code da Anthropic, Hooks do Claude Code da Anthropic, Subagentes do Claude Code da Anthropic, MCP do Claude Code da Anthropic, Guia do Claude Code da Novita e Visão geral do Sandbox da Novita.