Agentes do Claude Code: um guia prático para fluxos de trabalho autônomos de codificação

Se alguém me perguntasse o que torna o Claude Code diferente do ChatGPT ou do GitHub Copilot, eu não começaria falando do modelo de linguagem. Eu começaria pelo fluxo de trabalho.

Imagine abrir um terminal dentro de um repositório Git e digitar um único prompt:

Add request validation to every FastAPI endpoint,
write tests for the new validation logic, update the documentation, 
and commit everything using a descriptive Git commit message.

Em vez de fazer dezenas de perguntas de esclarecimento, o Claude Code começa a trabalhar. 

Ele busca no seu projeto para entender a estrutura da API, identifica cada endpoint, edita os arquivos necessários, gera testes, corrige quaisquer falhas, atualiza a documentação e cria um commit no Git resumindo as mudanças.

Da sua perspectiva, a sensação é menos de estar batendo papo com uma IA e mais de estar delegando trabalho a um colega competente. 

Essa mudança é o que torna os agentes do Claude Code tão empolgantes.

O recurso que torna isso possível são os subagentes do Claude Code. Em vez de forçar uma única sessão de IA a raciocinar sobre todo um repositório, o Claude Code pode lançar trabalhadores especializados que investigam partes diferentes do projeto, constroem planos de implementação ou modificam código de forma independente antes de prestar contas à sessão principal. 

Em vez de tentar resolver tudo em uma conversa só, o Claude Code pode delegar tarefas a agentes especializados. 

Os três tipos principais de agente são: 

• Explore (explorar), que foca em investigar projetos
• Plan (planejar), que foca em construir planos de implementação, e
• Geral, usado para editar código e executar comandos.

Isso mudou a forma como eu encaro o desenvolvimento. Em vez de perguntar: "A IA consegue escrever esta função?", eu me pego pensando: "Qual é o maior pedaço de trabalho que dá para delegar com segurança?" 

Ao final deste guia, você vai saber como usar bem os agentes do Claude Code, quando cada tipo de subagente faz sentido, como configurar memória persistente do projeto com CLAUDE.md e como montar fluxos autônomos que economizam tempo sem abrir mão do controle. 

Pré-requisitos

Este guia pressupõe que você tem familiaridade com o terminal e sabe navegar por diretórios com comandos básicos de linha de comando como cd, ls ou dir. 

Você não precisa ser expert em Bash, mas deve se sentir à vontade trabalhando no shell.

Você também vai precisar de:

• Node.js instalado na sua máquina
• Uma chave de API da Anthropic
• Um repositório Git para fazer testes
• Noções básicas de Python, JavaScript ou outra linguagem de programação

Se você é totalmente novo no Claude Code, recomendo ler também Claude Code: A Guide With Practical Examples antes de mergulhar nos subagentes.

O que são os agentes do Claude Code?

Os agentes do Claude Code são trabalhadores autônomos que concluem tarefas de desenvolvimento de software em várias etapas usando seu repositório local, terminal e ferramentas de desenvolvimento. 

Diferentemente do ChatGPT ou do Claude Chat, o Claude Code pode inspecionar arquivos, executar comandos Bash, editar código-fonte e verificar o próprio trabalho antes de retornar um resultado.

A maioria dos assistentes de código com IA ainda segue um fluxo conversacional. 

Você faz uma pergunta, recebe uma resposta e decide o próximo passo. 

Isso funciona bem para escrever uma consulta SQL ou explicar um pipeline do scikit-learn, mas começa a falhar quando a tarefa envolve 20 arquivos, exige vários comandos de terminal ou depende de entender um repositório desconhecido.

O Claude Code aborda esses problemas de outro jeito. 

Como ele trabalha diretamente dentro do seu repositório Git, consegue investigar o código antes de tomar decisões. Em vez de pedir para você colar arquivos na janela do chat, ele lê o próprio projeto e reúne o contexto necessário.

Suponha que você peça:

Replace every custom customer ID validator with Pydantic models, 
update the FastAPI endpoints, rewrite the affected pytest tests, 
and summarize the migration.

Um chatbot tradicional provavelmente vai gerar código de exemplo e pedir mais informações. 

O Claude Code pesquisa o repositório, identifica a lógica de validação existente, edita os arquivos relevantes, roda a suíte de testes, corrige quaisquer regressões que introduziu e relata o trabalho concluído.

Essa mudança de "responder perguntas" para "cumprir objetivos" é o que faz a codificação com agentes no Claude Code parecer diferente no dia a dia.

Como funciona o ciclo do agente? 

Todo agente do Claude Code segue o mesmo ciclo de decisão: ler informações, decidir o próximo passo, agir e, então, avaliar o resultado antes de repetir o processo. 

O loop é simples, mas repeti-lo dezenas de vezes permite que o agente se recupere de erros em vez de parar depois de uma única tentativa fracassada.

Imagine pedir ao Claude Code para consertar uma suíte de testes com falhas. O fluxo geralmente parece assim:

Diagrama mostrando como o Claude Code opera enquanto corrige testes com falha

Para mim, esse é o modelo mental mais fácil para entender o Claude Code. 

O agente não tenta resolver o problema inteiro de uma vez. Ele toma uma série de pequenas decisões com base no que aconteceu após a ação anterior.

Um subagente segue exatamente o mesmo loop, mas dentro de um contexto isolado próprio. 

Essa distinção importa porque uma chamada de ferramenta executa uma ação, enquanto um subagente pode gastar dezenas de passos de raciocínio trabalhando rumo a um único objetivo antes de reportar o progresso.

Por que o Claude Code usa subagentes? 

O Claude Code usa subagentes porque repositórios grandes raramente cabem em um único contexto de trabalho. Um monorepo com serviços em Python, aplicações React, migrações SQL e configuração Terraform contém muito mais informação do que um único agente deveria analisar de uma vez. 

Em vez de tratar o repositório como uma tarefa gigantesca, o Claude Code delega investigações focadas a trabalhadores especializados. 

Um agente Explore pode analisar autenticação, outro inspecionar os modelos de banco de dados e um terceiro revisar as rotas da API. O orquestrador combina essas descobertas antes de decidir o próximo passo.

Essa arquitetura tem outra vantagem prática: muitas investigações acontecem em paralelo. 

Em vez de você ler cada diretório manualmente ou esperar um agente inspecionar o repositório inteiro, vários subagentes podem explorar áreas diferentes ao mesmo tempo.

Você verá esse padrão ao longo do tutorial. Agentes Explore reúnem informações, agentes Plan organizam a implementação e agentes gerais fazem o trabalho de desenvolvimento em si.

Se quiser uma introdução mais ampla sobre como sistemas autônomos de IA funcionam além do Claude Code, o artigo da DataCamp LLM Agents Explained: Architecture, Frameworks, and Use Cases traz uma ótima visão conceitual.

Como instalar e configurar o Claude Code? 

Antes de começar a usar os agentes do Claude Code, precisamos de uma instalação funcional. 

Felizmente, iniciar leva apenas alguns minutos.

Instalando o Claude Code

O Claude Code é distribuído como um pacote npm, então você vai precisar do Node.js instalado. Para instruções, recomendo seguir a documentação do npm sobre instalação do Node.js e do npm.

Instale o Claude Code globalmente com:

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

Em seguida, crie uma chave de API da Anthropic no Anthropic Console e adicione-a ao seu ambiente.

No macOS ou Linux:

export ANTHROPIC_API_KEY="your_api_key_here"

No Windows PowerShell:

$env:ANTHROPIC_API_KEY="your_api_key_here"

Para verificar se tudo foi instalado corretamente, execute:

claude --version

Se o Claude Code imprimir a versão instalada, você está pronto.

Neste ponto, também vale confirmar se o Git está disponível, já que muitos fluxos do Claude Code envolvem ler o histórico do repositório, criar commits ou comparar mudanças. 

Se você não tiver Git, siga as instruções de instalação do Git para começar.

Ambos os comandos devem executar com sucesso antes de seguir adiante.

Sua primeira sessão com o Claude Code

Com o Claude Code instalado, navegue até qualquer projeto Git usando cd my-project.

Depois inicie o Claude Code: claude.

Antes de pedir para ele escrever código, reserve alguns minutos para entender como ele explora um repositório. Eu geralmente começo com prompts como:

• "O que este repositório faz?"
• "Explique a arquitetura."
• "Encontre todos os comentários TODO."
• "Quais módulos contêm a lógica de negócio principal?"
• "Como a autenticação foi implementada?"

Essas perguntas não geram novas funcionalidades, mas dão ao Claude Code o mesmo contexto que um colega novo buscaria antes de escrever código. 

Eu percebo que investir 2 ou 3 minutos na exploração costuma render implementações melhores do que pular direto para um pedido de feature.

O próximo passo é configurar memória persistente do projeto com o CLAUDE.md. Na minha experiência, nenhum outro arquivo tem impacto maior na qualidade do trabalho do Claude Code a longo prazo.

Por que o CLAUDE.md é o arquivo mais importante para o Claude Code?

CLAUDE.md é um arquivo de instruções persistentes que informa ao Claude suas preferências e como o seu projeto funciona antes de ele começar a raciocinar sobre uma tarefa. 

Em vez de reexplicar seu stack, convenções de código e fluxo de desenvolvimento toda vez que abrir uma nova sessão, você documenta tudo uma vez e deixa que cada agente futuro construa em cima desse contexto compartilhado.

Quando as pessoas conhecem os agentes do Claude Code pela primeira vez, geralmente focam no prompt. Eu acho que isso inverte as prioridades. 

Um CLAUDE.md bem escrito faz mais pela qualidade do resultado do que lapidar infinitamente a redação do prompt, porque todo agente começa com o mesmo entendimento do seu projeto.

Pense em como você faria o onboarding de um novo engenheiro. 

Você provavelmente não começaria entregando um ticket do Jira. Explicaria o repositório, mostraria como rodar a suíte de testes, destacaria algumas convenções de código e avisaria sobre as partes da base que não devem ser mexidas. 

CLAUDE.md cumpre exatamente esse papel.

O retorno fica ainda mais claro quando você começa a usar fluxos autônomos do Claude Code.

Um agente que precisa trabalhar com independência requer um contexto de projeto confiável. 

Sem isso, o Claude Code perde tempo redescobrindo informações ou fazendo suposições que podem não bater com os padrões do seu time.

O que incluir no seu CLAUDE.md?

Um bom CLAUDE.md não substitui a documentação do projeto nem o seu README.md. Ele reúne as instruções de que o Claude Code mais precisa ao ler código, implementar features e executar ferramentas de desenvolvimento.

Eu costumo organizar em cinco seções: visão geral do projeto, stack tecnológico, convenções de código, comandos comuns e diretórios a evitar. Vou passar rapidamente por cada um.

Visão geral do projeto

Comece com uma breve descrição do que o projeto realmente faz.

Customer analytics platform built with FastAPI.
The application serves machine learning predictions through REST APIs.
Production deployments run through GitHub Actions.

Essas três linhas já dizem ao Claude Code que ele está lidando com FastAPI, GitHub Actions e um app de machine learning, e não um repositório Python genérico.

Stack de tecnologia

Em seguida, literalmente liste as principais bibliotecas e frameworks que definem o projeto.

Python 3.12
FastAPI
Pydantic v2
SQLAlchemy
PostgreSQL
Pytest
Ruff

Sempre incluo números de versão quando fazem diferença. 

A abordagem recomendada para o Pydantic v2 difere do v1, e o Claude Code não deveria ter que adivinhar qual API você usa. 

Isso é ainda mais importante se você estiver usando um pacote mais antigo, para evitar partir de suposições erradas.

Convenções de código

Esta seção registra as regras que você vive repetindo.

Always use type hints.
Prefer dependency injection.
Write tests for every new feature.
Keep business logic separate from API routes.
Reuse existing utility functions before creating new ones.

Note que são regras práticas de engenharia, não preferências de estilo. 

O Claude Code costuma inferir formatação a partir dos arquivos existentes, mas não vai saber automaticamente que seu time espera uso de injeção de dependência em todo endpoint ou que toda feature inclui um teste com pytest.

Comandos comuns

O Claude Code frequentemente valida o próprio trabalho executando comandos de desenvolvimento. Fornecer exatamente os comandos que seu time usa evita tentativa e erro desnecessários. 

Podem ser ações específicas do task ou scripts de CI, por exemplo.

pytest
Run one test file:
pytest tests/test_api.py
Lint:
ruff check .
Format:
ruff format .
Start the development server:
uvicorn app.main:app --reload

Esta seção é especialmente útil em repositórios com scripts customizados, workflows com Docker ou ferramentas como poetry, uv ou tox.

Arquivos e diretórios a evitar

Todo repositório tem arquivos que não devem mudar automaticamente.

Exemplos incluem:

Never edit generated files.
Do not modify Alembic migrations.
Avoid changing Terraform configuration unless requested.
Do not update dependency versions automatically.

Percebo que esta seção evita mais erros do que quase qualquer outra. Uma frase dizendo ao Claude Code para não mexer em código gerado sai muito mais barato do que revisar dezenas de mudanças desnecessárias.

Um exemplo de CLAUDE.md

Aqui vai um exemplo simplificado para um projeto de API em Python. 

Repare como uso formatação em Markdown para deixar mais legível e dar mais contexto ao Claude.

# Project Overview

Customer analytics platform built with FastAPI.

## Technology

- Python 3.12
- FastAPI
- PostgreSQL
- SQLAlchemy
- Pydantic v2
- Pytest
- Ruff

## Coding Standards

- Use type hints everywhere.
- Write tests for new features.
- Prefer dependency injection.
- Keep business logic separate from API routes.

## Common Commands

pytest
ruff check .
ruff format .

## Avoid Editing

generated/
alembic/versions/
terraform/

Não se preocupe em deixar a primeira versão perfeita. 

Meu próprio CLAUDE.md já mudou várias vezes à medida que percebi instruções recorrentes que valiam documentar. Trate-o como código-fonte, não como documentação imutável. 

Se quiser se aprofundar na escrita de arquivos de instrução eficazes, o tutorial da DataCamp Writing the Best CLAUDE.md: A Complete Guide for Claude Code aborda exemplos maiores e padrões mais avançados.

Usar CLAUDE.md no nível do projeto ou do usuário?

O Claude Code suporta dois escopos para instruções persistentes. Entender a diferença ajuda a separar regras do projeto das suas preferências pessoais.

CLAUDE.md no nível do projeto

Um arquivo no nível do projeto fica dentro do repositório.

	my-project/
	│
	├── CLAUDE.md
	├── app/
	├── tests/
	└── pyproject.toml

Tudo neste arquivo vale apenas para aquele repositório. Eu uso para escolhas de tecnologia, comandos de teste, convenções de código, estrutura de diretórios e regras específicas do projeto. 

Como o arquivo vive junto do código-fonte, todo colaborador recebe as mesmas instruções ao clonar o projeto. Pense nele como um manual entregue a cada agente antes de começar.

CLAUDE.md no nível do usuário

O Claude Code também suporta um arquivo de configuração global.

Esse arquivo te acompanha de projeto em projeto. Eu o encaro como meu manual operacional pessoal, não documentação de projeto.

Por exemplo, meu arquivo de usuário pode incluir instruções como:

Explain architectural trade-offs.
Suggest performance improvements when appropriate.
Default to Python examples unless another language is requested.
Keep explanations concise.

Essas preferências fazem sentido independentemente de eu estar trabalhando com FastAPI, React ou PyTorch.

Como os dois arquivos funcionam juntos

Um detalhe que me confundiu no começo é que esses arquivos não são mutuamente exclusivos. 

O CLAUDE.md do usuário é carregado primeiro; depois, o CLAUDE.md do projeto adiciona instruções específicas do repositório.

Eu penso nisso como uma hierarquia. 

O arquivo global define como eu gosto de trabalhar. O arquivo do projeto explica como este repositório funciona. 

Juntos, eles dão a cada agente tanto preferências pessoais quanto contexto do projeto antes de começar a raciocinar.

O Claude Code combina preferências do usuário com instruções específicas do projeto antes de iniciar uma tarefa.

Quais são os três tipos de subagentes do Claude Code?

O Claude Code usa três tipos de subagentes especializados porque tarefas de desenvolvimento diferentes exigem ferramentas diferentes. 

Um agente que está investigando um repositório não precisa de permissão para editar arquivos, enquanto um agente que vai implementar uma feature provavelmente precisa de acesso ao Bash, ao Git e à sua suíte de testes.

Quando comecei a usar o Claude Code, eu recorria sempre ao agente geral porque parecia a opção mais capaz. 

Com o tempo, percebi que eu gastava mais tempo e tokens do que precisava. A maioria dos fluxos fica mais rápida se você explorar primeiro, planejar depois e só então implementar.

Comparando os três subagentes do Claude Code

Os nomes são autoexplicativos, mas cada agente cumpre um papel bem definido em um fluxo maior.

O que é um agente Explore do Claude Code?

Um agente Explore do Claude Code é um investigador somente leitura que busca em um repositório e resume o que encontra sem alterar nenhum arquivo.

É o agente que eu mais uso ao abrir um projeto desconhecido. Em vez de eu mesmo rolar dezenas de módulos Python ou componentes JavaScript, peço ao Explore para explicar como um subsistema funciona e me apontar os arquivos que importam.

Bons casos de uso incluem:

• Encontrar onde a autenticação é implementada
• Traçar uma requisição por vários serviços
• Auditar logging ou tratamento de erros
• Localizar APIs obsoletas
• Resumir um pacote ou diretório
• Identificar lógica de negócio duplicada

Como agentes Explore não podem editar arquivos nem executar shell, eles também são os mais seguros para rodar em paralelo.

Escolhendo o nível de aprofundamento

Agentes Explore suportam diferentes profundidades de investigação.

Se eu só preciso localizar uma função, uso a configuração mais rápida. Se estou me preparando para um refactor em vários pacotes, esperar mais um minuto por uma investigação mais profunda costuma valer a pena.

O que é um agente Plan do Claude Code?

Um agente Plan do Claude Code analisa a mudança solicitada e produz uma estratégia de implementação sem modificar o repositório.

Eu quase nunca pulo essa etapa. Gastar um minuto extra revisando um plano sai muito mais barato do que descobrir, no meio da implementação, que outro subsistema depende do código que você está alterando.

Um plano típico inclui:

• Arquivos que devem mudar
• Ordem de implementação recomendada
• Dependências e pontos de integração
• Estratégia de testes
• Riscos ou suposições

Depois de revisar o plano, você pode refiná-lo ou entregá-lo diretamente a um agente geral.

O tutorial da DataCamp Claude Code Plan Mode: Design Review-First Refactoring Loops explora esse fluxo de revisão antes da implementação em muito mais detalhe.

O que é um agente geral do Claude Code?

Um agente geral pode ler arquivos, editar código-fonte, executar comandos Bash, rodar testes e continuar trabalhando até cumprir o objetivo solicitado.

É o agente que de fato constrói software. Ele tem acesso ao mesmo contexto de repositório que os outros, mas também tem permissão para fazer mudanças e verificar o que fez.

Tarefas típicas incluem:

• Implementar novas features
• Refatorar vários módulos
• Migrar dependências
• Atualizar documentação
• Coordenar mudanças em múltiplos pacotes

Agentes gerais consomem mais tokens porque realizam muito mais trabalho. 

Esse é mais um motivo pelo qual gosto do padrão Explorar → Planejar → Implementar. 

Os agentes mais baratos respondem às perguntas iniciais, deixando o trabalho mais caro de implementação para quando o caminho estiver claro.

Até aqui, cobrimos os elementos que tornam os agentes do Claude Code bem-sucedidos: memória persistente do projeto via CLAUDE.md e subagentes especializados para investigação, planejamento e implementação. 

Agora vamos juntar essas peças construindo fluxos de agentes completos que você pode começar a usar nos seus projetos.

Executando seus primeiros fluxos de agentes do Claude Code

A melhor forma de extrair valor do Claude Code é dar a ele um objetivo, não pedir componentes isolados.

Eu adotei um fluxo simples que funciona bem em projetos Python, repositórios de data science e aplicações web:

1. Explorar o repositório.
2. Criar um plano.
3. Revisar o plano.
4. Implementar as mudanças.
5. Verificar os resultados.

Esse processo não é obrigatório, mas reflete como engenheiros experientes abordam mudanças maiores. 

Gastar um minuto entendendo o repositório geralmente poupa vários minutos corrigindo edições desnecessárias depois. 

Criar um prompt mais completo — até gastar uma hora refinando — pode te poupar horas de trabalho depois.

Fluxo 1: explorar uma base de código desconhecida

Um agente Explore é o melhor ponto de partida quando você herda um repositório novo ou volta a um projeto que não toca há meses. 

Em vez de ler diretórios manualmente, peça ao Claude Code para investigar a arquitetura e resumir o que importa.

Por exemplo:

Use an Explore agent to explain how authentication works. 
Identify the main modules involved, summarize the request flow, 
and highlight any technical debt or TODO comments.

O resultado não será um paredão de código copiado. Em geral, você recebe uma explicação concisa do fluxo de autenticação, dos arquivos envolvidos e das áreas que merecem atenção. 

Eu costumo usar esse resumo como ponto de partida para a próxima tarefa, em vez de escrever um novo prompt do zero.

Fluxo 2: planeje antes de implementar

Depois de entender o repositório, peça a um agente Plan para desenhar a implementação antes de escrever código. 

Esse é um dos hábitos mais fáceis de adotar e já me salvou de vários refactors que iriam na direção errada.

Um prompt pode ser assim:

Create an implementation plan for adding role-based access control.
Identify the files that should change, potential risks,
dependencies, and a recommended implementation order.
Do not modify any code.

Revise o plano antes de avançar. Se tudo parecer razoável, você pode entregar o plano diretamente a um agente geral. 

Caso contrário, é muito mais fácil ajustar um documento de design do que desfazer mudanças em uma dúzia de arquivos.

Uma ótima forma de aproveitar essa etapa é usar outra sessão do Claude Code para revisar o trabalho da primeira. Um prompt simples poderia ser:

This is my current goal: to add role-based access control to this repository. 
Take a look at this existing implementation plan and do an adversarial review.
Once done, create a report that summarizes the strong and weak points of the plan.

Fluxo 3: paralelize a exploração do repositório

Uma das minhas funções favoritas do Claude Code é que a exploração não precisa acontecer de forma sequencial. Se o seu projeto tem vários subsistemas independentes, você pode investigá-los ao mesmo tempo.

Por exemplo, você pode iniciar um agente Explore para inspecionar a camada de API, outro para revisar os modelos de banco e um terceiro para examinar o pipeline de machine learning. 

Enquanto esses agentes trabalham de forma independente, o orquestrador combina os achados em uma resposta única.

Eu não uso agentes paralelos para toda tarefa, mas eles caem como uma luva em monorepos grandes ou aplicações maduras com muitos serviços. Em vez de esperar por uma investigação longa, você entende o repositório muito mais rápido porque várias partes são analisadas simultaneamente.

A melhor forma de fazer isso é usar um agente mais abrangente para orquestrar múltiplos agentes. 

Essa orquestração de agentes é uma ótima maneira de conduzir trabalho em paralelo sem precisar de várias sessões, mantendo tudo em um contexto único. 

Um bom prompt poderia ser:

I want you to look at the following components: 
Inspect the API layer, review the DB models, and examine the ML pipeline. 
Look for weaknesses. 
I want this done in parallel, so spawn subagents using Opus/Sonnet models 
in order to do this work and have each generate a concise report and share out 
one master document that outlines the work needed to be done.

Boas práticas para agentes do Claude Code

A maioria dos problemas com o Claude Code não é causada pelo modelo, e sim por prompts vagos, falta de contexto do projeto ou por pedir que ele resolva um problema que não entende completamente.

Depois de usar o Claude Code com frequência, estes são os hábitos que mais impactaram meus resultados.

Escreva prompts que os agentes consigam executar

O Claude Code tem o melhor desempenho quando objetivo, escopo e critérios de sucesso estão explícitos. 

Em vez de descrever o objetivo final em termos amplos, diga exatamente qual repositório ele deve inspecionar, quais arquivos deve modificar e como você vai saber que a tarefa foi concluída.

Por exemplo:

❌ Vago Melhorar a API.

✅ Específico Atualizar os endpoints de autenticação do FastAPI para usar validação do Pydantic v2, gerar ou atualizar os testes pytest relevantes, executar a suíte de testes e resumir cada arquivo modificado.

O segundo prompt dá ao Claude Code um objetivo claro, limites e uma forma de verificar o sucesso. Isso costuma gerar menos prompts de acompanhamento e menos retrabalho manual.

Gerencie o contexto antes que vire problema

Conversas longas acabam acumulando tanto contexto que o Claude Code gasta tokens lembrando discussões anteriores em vez de raciocinar sobre a tarefa atual.

Quando isso acontecer, use /compact para resumir a conversa mantendo o contexto importante. Melhor compactar cedo do que esperar a performance cair visivelmente.

Um bom CLAUDE.md também ajuda aqui, pois convenções do projeto não precisam ser repetidas a cada sessão. O Claude Code carrega esse contexto automaticamente, liberando mais tempo para o trabalho que você pediu.

Para mais dicas sobre gestão de contexto, TDD e design de prompts, veja Claude Code Best Practices: Planning, Context Transfer, TDD.

Pense no custo de tokens

Nem toda tarefa precisa de um agente geral.

Se você só precisa descobrir onde uma função é definida, um agente Explore costuma ser mais rápido e barato. 

Se estiver revisando uma mudança arquitetural grande, um agente Plan frequentemente dá informação suficiente sem modificar o repositório.

Reserve agentes gerais para tarefas que realmente exigem execução, como editar arquivos, rodar comandos Bash ou executar testes. Ajustar o agente à tarefa mantém o tempo de execução e o uso de tokens sob controle.

Saiba quando não usar agentes

Agentes do Claude Code introduzem alguma sobrecarga por conta de contexto e troca de tokens. 

Eles investigam o repositório, raciocinam sobre a tarefa e verificam o trabalho. Para mudanças muito pequenas, essa sobrecarga pode não valer a pena.

Você provavelmente não precisa de um agente para:

• Renomear uma única variável.
• Corrigir um erro de digitação em um arquivo Markdown.
• Explicar uma mensagem de erro do Python.
• Responder uma dúvida rápida de SQL.

Nessas situações, uma conversa normal com o Claude Code ou até uma edição manual costuma ser mais rápida. Eu normalmente me faço uma pergunta antes de lançar um agente: Vou gastar mais tempo explicando esta tarefa do que fazendo eu mesmo? Se a resposta for sim, eu mantenho simples.

Considerações finais

Os agentes do Claude Code mudam o papel da IA no desenvolvimento de software. Em vez de gerar trechos isolados, eles encaram problemas mais complexos como investigar repositórios, desenhar implementações, modificar código, executar testes e cumprir objetivos em várias etapas com relativamente pouca supervisão.

A maior lição que aprendi é que bons fluxos de trabalho importam mais do que bons prompts. 

Um CLAUDE.md claro, alguns minutos explorando o repositório e um plano de implementação bem pensado geram resultados consistentemente melhores do que pular direto para a geração de código.

À medida que você for usando o Claude Code, provavelmente vai desenvolver seu próprio fluxo. O meu ainda começa quase sempre da mesma forma: primeiro explorar, depois planejar, por último implementar.

É um hábito simples, mas me poupou incontáveis ciclos de revisão e me ajudou a confiar muito mais em fluxos autônomos do que quando comecei a usá-los.

Se quiser aprender mais sobre as ideias por trás de sistemas autônomos, recomendo estes recursos:

• Introduction to AI Agents 
• Introduction to Claude Models 
• Claude Code Hooks: A Practical Guide to Workflow Automation 
• Claude Agent SDK Tutorial: Create Agents Using Claude Sonnet 4.5 
• How to Build Claude Code Plugins 
• Claude Code 2.1: A Guide With Practical Examples 
• Model Context Protocol (MCP): A Guide With Demo Project 
• AI Agents with Hugging Face smolagent