Claude Code: práticas recomendadas para codificação agêntica
(anthropic.com)- Claude Code é uma ferramenta de codificação agêntica baseada em CLI, que pode ser aplicada com flexibilidade a vários ambientes e linguagens de desenvolvimento
- Configuração do
CLAUDE.md, gerenciamento da lista de ferramentas permitidas e criação de comandos personalizados permitem maximizar a usabilidade do Claude - Aplicar estratégias por fluxo de trabalho (exploração-planejamento-implementação-commit, desenvolvimento orientado a testes, iteração visual etc.) é eficaz
- Com modo headless e configuração com múltiplos Claude, também é possível automatizar e trabalhar em paralelo
- É possível fazer uso avançado ao integrar o Claude com várias ferramentas de desenvolvimento, como Git, GitHub e Jupyter
Visão geral do Claude Code
- Claude Code é uma ferramenta para codificação agêntica (codificação automatizada baseada em linha de comando)
- Foi projetado para que desenvolvedores e pesquisadores internos da Anthropic integrem o Claude à programação de forma mais natural
- Graças à interface de baixo nível e ao design independente de dependências, ele não fica preso a uma forma específica de desenvolvimento,
- e os desenvolvedores podem configurar e usar o Claude do jeito que melhor lhes convier
- Como resultado, consolidou-se como uma ferramenta de codificação extremamente poderosa, flexível e segura
- Como ponto negativo, há uma curva de aprendizado alta para usuários iniciantes,
- o que exige um processo de criação das próprias melhores práticas
- Este artigo apresenta, com base na experiência de equipes internas e engenheiros externos que realmente usaram o Claude Code,
- padrões gerais eficazes em várias linguagens, bases de código e ambientes
- O conteúdo apresentado deve ser visto não como resposta definitiva, mas como ponto de partida, e recomenda-se experimentar e aprimorar conforme a necessidade de cada um
# 1. Personalização da configuração
Claude Code é um assistente de codificação agêntica que coleta contexto automaticamente para montar prompts
Essa coleta de contexto consome tempo e tokens, mas pode ser otimizada ajustando o ambiente
a. Criar o arquivo CLAUDE.md
CLAUDE.md é um arquivo especial que o Claude inclui automaticamente no contexto ao iniciar uma conversa
Esse arquivo é ideal para documentar os seguintes itens:
- comandos bash usados com frequência
- arquivos principais e funções utilitárias
- diretrizes de estilo de código
- como executar testes
- forma de trabalhar no repositório (ex.: nomenclatura de branches, merge vs. rebase)
- como configurar o ambiente de desenvolvimento (ex.: uso de
pyenv, compiladores compatíveis) - comportamentos excepcionais ou avisos do projeto
- outras informações que o Claude deve lembrar
O arquivo CLAUDE.md não tem restrições de formato, e recomenda-se escrevê-lo de forma concisa e fácil de ler
Exemplo:
# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')
# Workflow
- Be sure to typecheck when you’re done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance
Localização do arquivo CLAUDE.md
O Claude procura o CLAUDE.md nos seguintes locais e o inclui no contexto:
- raiz do repositório ou diretório em que o
claudefoi executado- se for salvo como
CLAUDE.mde versionado no Git, pode ser compartilhado entre sessões e entre equipes (recomendado) - para configurações pessoais, é possível salvá-lo como
CLAUDE.local.mde adicioná-lo ao.gitignore
- se for salvo como
- diretórios acima do diretório de execução
- útil em estruturas monorepo (ex.: pode-se usar tanto
root/CLAUDE.mdquantoroot/foo/CLAUDE.md)
- útil em estruturas monorepo (ex.: pode-se usar tanto
- subdiretórios do diretório de execução
- incluído automaticamente no contexto ao trabalhar com arquivos dentro desse diretório
- diretório home (
~/.claude/CLAUDE.md)- aplicação global em todas as sessões
Ao executar o comando /init, o Claude cria automaticamente o arquivo CLAUDE.md
b. Ajustar o arquivo CLAUDE.md
Como o CLAUDE.md é usado como parte do prompt do Claude, ele deve ser refinado e otimizado iterativamente, como um prompt
Um erro comum é colocar conteúdo demais sem verificar o efeito
- É importante identificar por meio de experimentação que tipo de conteúdo melhora o desempenho das respostas do modelo
- É possível adicionar conteúdo manualmente ou pressionar a tecla
#e instruir o Claude para que o conteúdo seja refletido automaticamente noCLAUDE.md - Muitos engenheiros documentam comandos, guias de estilo etc. em tempo real e incluem as alterações do
CLAUDE.mdno commit para compartilhar com a equipe
Na Anthropic, o prompt improver é usado para refinar o CLAUDE.md,
com adição de expressões de ênfase como “IMPORTANT” e “YOU MUST” para aumentar a precisão das respostas
c. Gerenciar a lista de ferramentas permitidas do Claude
Por padrão, Claude Code solicita aprovação do usuário para tarefas que podem alterar o sistema (gravação de arquivos, execução de comandos bash, uso de ferramentas MCP etc.)
Esse é um design conservador voltado à segurança, e ferramentas consideradas seguras pelo usuário podem ser pré-aprovadas por meio de uma lista de permissões (allowlist)
Como configurar ferramentas permitidas
- Durante a sessão, quando o prompt aparecer, selecione "Always allow"
- Adicione/remova ferramentas com o comando
/allowed-tools
Exemplo:Edit→ permitir edição de arquivosBash(git commit:*)→ permitir commits no Gitmcp__puppeteer__puppeteer_navigate→ permitir navegação no servidor MCP do Puppeteer
- Edite manualmente
.claude/settings.jsonou~/.claude.json- para compartilhar com a equipe, recomenda-se usar o primeiro e versioná-lo no Git
- Use o flag de CLI
--allowedToolspor sessão
d. Instalar o CLI gh ao usar GitHub
O Claude pode usar o CLI gh, o que permite automatizar tarefas do GitHub, como criar issues, abrir PRs e ler comentários
Mesmo sem instalar o gh, é possível substituí-lo usando a API do GitHub ou um servidor MCP
# 2. Dar mais ferramentas ao Claude
Como o Claude pode acessar o ambiente de shell do usuário, ele também pode usar diretamente scripts e funções criados pelo próprio usuário
Além disso, é possível integrá-lo a ferramentas externas mais complexas via MCP ou API REST
a. Usar com ferramentas Bash
Claude Code herda o ambiente bash do usuário e, por isso, pode acessar ferramentas utilitárias já instaladas
- ferramentas Unix comuns ou o CLI
ghjá são conhecidos pelo Claude - mas ferramentas bash personalizadas criadas pelo usuário precisam ser informadas separadamente
Para que o Claude reconheça ferramentas personalizadas, faça o seguinte:
- informe explicitamente o nome da ferramenta e exemplos de uso ao Claude
- diga para ele verificar como usar a ferramenta com a opção
--help - documente as ferramentas usadas com frequência no
CLAUDE.md
b. Usar com MCP
Claude Code atua ao mesmo tempo como servidor MCP e cliente MCP
Como cliente, pode se conectar a vários servidores MCP e usar diferentes ferramentas
As ferramentas de servidores MCP podem ser conectadas ao Claude de três formas:
- definindo-as na configuração do projeto (disponíveis apenas naquele diretório)
- usando a configuração global, para todos os projetos
- versionando um arquivo
.mcp.jsonpara que todos os desenvolvedores que colaboram possam usar imediatamente as ferramentas- ex.: ao registrar servidores Puppeteer e Sentry no
.mcp.json, toda a equipe pode usá-los
- ex.: ao registrar servidores Puppeteer e Sentry no
Para depurar problemas de configuração durante o uso de MCP, é útil executar o Claude com a flag --mcp-debug
c. Comandos slash personalizados
Para fluxos de trabalho repetitivos (debug, análise de logs etc.),
é possível salvar templates de prompt como arquivos Markdown na pasta .claude/commands
- Ao digitar
/no Claude, esse comando aparece no menu de autocompletar - É possível fazer commit no git e compartilhar com a equipe
Passagem de parâmetros: $ARGUMENTS
Ao incluir $ARGUMENTS em um comando de barra, é possível inserir automaticamente os parâmetros passados na execução do comando
Exemplo: análise e correção automática de issue do GitHub
Please analyze and fix the GitHub issue: $ARGUMENTS.
Follow these steps:
1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR
Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.
Ao salvar o conteúdo acima em .claude/commands/fix-github-issue.md, ele pode ser usado com o comando /project:fix-github-issue
Ex.: /project:fix-github-issue 1234 → Claude tenta corrigir automaticamente a issue #1234
Se os comandos de configuração pessoal forem salvos na pasta ~/.claude/commands, eles poderão ser usados em todas as sessões
# 3. Aproveitando fluxos de trabalho comuns
O Claude Code não impõe um fluxo de trabalho específico e oferece total flexibilidade ao usuário
Com base nessa flexibilidade, a comunidade de usuários desenvolveu diversos padrões de uso que se estabeleceram com sucesso
a. Explorar → planejar → implementar → commitar
-
Peça ao Claude para ler arquivos, imagens e URLs relevantes
- Ex.: “Leia o arquivo que processa logs”, “Leia
logging.py” - Mas deixe claro para ele não programar ainda
- Nesta etapa, usar subagentes (subagents) é muito eficaz, especialmente em problemas mais complexos
- Ex.: “Leia o arquivo que processa logs”, “Leia
-
Peça ao Claude para elaborar um plano para resolver o problema
- Ao usar palavras-chave como “think”, “think hard” e “ultrathink”, ele recebe mais orçamento computacional
- Se o plano for bom, organize-o em um documento ou crie uma issue no GitHub para ter um ponto de referência ao qual voltar
-
Depois, peça ao Claude para implementar o código conforme o plano
- Durante a implementação, também é possível pedir explicitamente que ele valide por conta própria se o resultado faz sentido
-
Por fim, instrua a fazer commit do resultado e criar um PR
- Se necessário, também peça atualização de README ou CHANGELOG
📌 Nesse fluxo, se você pular as etapas 1 e 2, o Claude vai começar a programar imediatamente; por isso, a etapa de planejamento é importante, especialmente em problemas complexos
b. Escrever testes → commitar → escrever código → repetir → commitar (desenvolvimento guiado por testes)
Esse é um método usado com frequência dentro da Anthropic e é adequado para trabalhos com testes unitários, de integração e e2e
-
Peça ao Claude para escrever testes com base nos critérios de entrada/saída
- Deixe claro que é desenvolvimento guiado por testes → oriente-o a escrever apenas os testes, sem implementar a funcionalidade
-
Peça que ele verifique se os testes falham
- Instrua a apenas executar os testes, sem implementar nada
-
Se os testes estiverem satisfatórios, faça commit
-
Peça ao Claude para escrever código que passe nos testes
- Deixe explícito que os testes não devem ser alterados
- Em geral, ele acaba passando nos testes após várias execuções iterativas
- Também é eficaz usar subagentes para verificar se houve overfitting
-
Quando todos os testes passarem, instrua a fazer commit do código
✅ O Claude funciona melhor quando existe um alvo claro (por exemplo, casos de teste, imagens etc.)
c. Escrever código → fornecer screenshot do resultado → melhorar iterativamente
- Monte um ambiente capaz de fornecer screenshots do navegador automaticamente (ex.: Puppeteer MCP, simulador iOS etc.)
- Forneça um mockup visual (colar imagem, passar caminho etc.)
- Peça ao Claude para implementar o design → mostrar screenshot do resultado → comparar de novo e instruir melhorias
- Se ficar satisfatório, faça commit
💡 Assim como pessoas, o Claude também melhora muito após 2 ou 3 iterações → por isso, o loop de feedback visual é importante
d. Modo Safe YOLO
- Com a opção
--dangerously-skip-permissions, todas as solicitações de aprovação são ignoradas - O Claude executa o trabalho de forma totalmente automática sem aprovação do usuário
⚠️ Há risco de perda de dados, danos ao sistema e prompt injection → recomenda-se executar apenas em contêineres isolados da internet
→ Como implementação de exemplo, recomenda-se usar Docker Dev Container
e. Perguntas e respostas sobre a codebase
- Ao se adaptar a um novo projeto, é possível fazer perguntas ao Claude como se estivesse perguntando a um engenheiro colega
- O Claude explora a codebase e encontra as respostas por conta própria
Exemplos de perguntas:
- Como o logging funciona?
- Como crio um novo endpoint de API?
- Qual é o papel do
async movena linha 134 defoo.rs? - Quais edge cases o
CustomerOnboardingFlowImpltrata? - Por que chama
bar()em vez defoo()? - Qual código Java é semelhante à linha 334 de
baz.py?
📌 É possível explorar apenas com perguntas em linguagem natural, sem prompt separado
→ Na Anthropic, esse método é usado como ferramenta principal de onboarding
f. Integração com Git
O Claude executa bem a automação de tarefas Git como:
- Busca no histórico do Git:
- Ex.: "Quais mudanças entraram na v1.2.3?", "Quem criou esse recurso?", "Por que essa API tem essa estrutura?"
- Escrita de mensagens de commit:
- Geradas automaticamente com base nas mudanças e no contexto ao redor
- Tarefas avançadas de Git:
- Reverter arquivos, resolver conflitos de rebase, comparar e mesclar patches etc.
g. Integração com GitHub
O Claude Code pode automatizar bastante as tarefas relacionadas ao GitHub:
- Criação de Pull Request:
- Reconhece a palavra-chave
pre gera automaticamente uma mensagem de commit com base nas mudanças
- Reconhece a palavra-chave
- Correção de comentários de code review:
- Basta dizer "corrija os comentários no PR" para ele corrigir e fazer push
- Correção de falhas de build e erros de lint
- Triagem e organização de issues:
- Peça ao Claude algo como “passe pelas issues abertas e organize tudo”
💡 Não é necessário decorar comandos gh para executar tarefas automatizadas no GitHub
h. Trabalho com Jupyter Notebook
- O Claude pode ler e escrever arquivos
.ipynb, além de interpretar saídas com imagens incluídas - No VS Code, recomenda-se usar o Claude Code e o arquivo do notebook abertos lado a lado
Recursos adicionais:
- Antes de compartilhar com outras pessoas, é possível pedir para organizar o notebook e melhorar o visual
- Pedidos como “deixe mais apresentável” e “melhore a visualização” funcionam bem para otimizar a visualização voltada a humanos
# 4. Otimização do fluxo de trabalho
As sugestões abaixo são métodos de otimização aplicáveis em comum a todos os fluxos de trabalho
a. Escreva instruções específicas
No Claude Code, quanto mais específicas forem as instruções na primeira tentativa, maior a taxa de sucesso
Se o pedido for claro desde o início, a necessidade de ajustes no meio do caminho diminui
Comparação de exemplos
- ❌
add tests for foo.py→ amplo demais
✅Para foo.py, escreva um novo caso de teste que cubra o cenário de usuário deslogado. Não use mocks - ❌
why does ExecutionFactory have such a weird api?→ ambíguo
✅Rastreie o histórico do git de ExecutionFactory e resuma por que a API foi estruturada da forma atual - ❌
add a calendar widget→ direção de implementação pouco clara
✅Analise como os widgets existentes na homepage foram implementados (por exemplo, HotDogWidget.php), identifique o padrão de separação entre código e interface e depois implemente, da mesma forma, um novo widget de calendário em que o usuário possa selecionar o mês e navegar entre páginas de ano. Bibliotecas externas só são permitidas se já forem usadas no projeto atual
O Claude consegue inferir a intenção, mas não consegue ler pensamentos → clareza é fundamental
b. Fornecer imagens
O Claude é excelente em processar imagens e diagramas
Você pode fornecer imagens das seguintes formas:
- No macOS,
cmd+ctrl+shift+4→ captura de tela para a área de transferência → colar comctrl+v(não funciona em ambiente remoto) - Arrastar e soltar o arquivo de imagem
- Informar o caminho do arquivo de imagem
É muito útil para UI/visualização de dados, como implementação de mockups de design e análise de gráficos visuais
Mesmo quando não há elementos visuais, também ajuda deixar claro se a qualidade visual do resultado é importante
c. Especificar os arquivos com que trabalhar
Se você disser ao Claude claramente quais arquivos ele deve consultar ou modificar, a precisão do trabalho melhora
- É possível inserir rapidamente caminhos de arquivos/pastas com autocompletar usando a tecla Tab
d. Fornecer URLs ao Claude
Se você der uma URL ao Claude, ele pode ler diretamente a documentação ou a página web
- Ex.: link da documentação da API, página do design system etc.
- Para acessos repetidos ao mesmo domínio, você pode adicionar o domínio à whitelist com o comando
/allowed-tools, evitando aprovações repetidas
e. Ajustar a direção rápido e com frequência (redirecionamento de rota)
Você pode automatizar o trabalho pressionando Shift + Tab para entrar no modo de aprovação automática (auto-accept mode),
mas, em geral, colaborar ativamente com o Claude e ajustar a direção leva a resultados melhores
4 ferramentas úteis de ajuste:
- Peça um plano primeiro: antes de implementar, faça com que ele monte um plano e só prossiga após sua confirmação
- Interrompa imediatamente com a tecla Escape: a qualquer momento é possível interromper o raciocínio, edição de arquivos etc.
- Pressione Escape duas vezes para editar o prompt anterior: você pode modificar o comando anterior e mudar para uma nova direção
- Peça para reverter as alterações: solicite ao Claude que faça rollback do que foi modificado para tentar outra abordagem
Às vezes o Claude resolve tudo perfeitamente de primeira, mas usar essas ferramentas permite obter resultados mais rápidos e precisos
f. Inicializar o contexto com o comando /clear
Se a sessão ficar longa, a janela de contexto (context window) do Claude pode se encher de informações desnecessárias e perder desempenho
→ recomenda-se criar o hábito de reinicializar o contexto com /clear a cada unidade de trabalho
g. Usar checklist e scratchpad
Em tarefas complexas (ex.: migração de código, correção em massa de erros de lint etc.),
usar um arquivo Markdown ou uma issue do GitHub como checklist melhora a eficiência
Ex.: corrigir erros de lint
- Peça ao Claude para executar o comando de lint → organizar os erros em uma checklist em Markdown
- Vá tratando cada item, confirme e marque como concluído → depois siga para o próximo
Com essa abordagem, é possível acompanhar o progresso e controlar a qualidade ao mesmo tempo
h. Passar dados ao Claude
Há várias formas de passar dados ao Claude:
- Copiar/colar (a forma mais comum)
- Entrada por pipe (ex.:
cat foo.txt | claude)- Adequado para logs, CSV e textos grandes
- Mandar buscar diretamente via comando bash, ferramenta MCP ou comando de barra
- Pedir para ler um arquivo ou URL (incluindo imagens)
No trabalho real, é comum usar uma combinação desses métodos
Ex.: enviar logs por pipe e pedir ao Claude que use uma ferramenta MCP para buscar contexto adicional
# 5. Automatizar infraestrutura com o modo headless
O Claude Code oferece modo headless para ambientes não interativos (CI, hooks de pre-commit, scripts de build, automações etc.)
- Execute o modo headless com um prompt usando a flag
-p - Com a opção
--output-format stream-json, é possível usar saída JSON em streaming
⚠️ O modo headless não persiste entre sessões e precisa ser executado manualmente a cada vez
a. Classificação automática de issues com Claude
O modo headless é adequado para gatilhos de automação baseados em eventos do GitHub
Ex.: analisar automaticamente quando uma nova issue é criada e classificá-la com labels
- Na prática, esse recurso também é usado no repositório público do Claude Code para adicionar labels automaticamente a novas issues
b. Usar o Claude como linter
O Claude pode automatizar uma revisão de código subjetiva que ferramentas tradicionais de lint têm dificuldade de detectar
Ex.:
- erros de digitação
- comentários desatualizados
- nomes de função/variável que induzem ao erro
- fluxo de código pouco intuitivo etc.
Com isso, é possível melhorar a qualidade do código além do que ferramentas de análise estática conseguem
# 6. Subir de nível com workflows de múltiplos Claudes
Indo além do uso de um único Claude, executar várias instâncias do Claude em paralelo é uma forma de uso extremamente poderosa
Assim como vários engenheiros colaborando, a estratégia de dividir o trabalho entre Claudes pode melhorar tanto a eficiência quanto a qualidade
a. Um Claude escreve código, outro Claude revisa
O padrão mais simples e eficaz:
- Claude 1: escreve o código
/clearou executar o Claude 2 em outro terminal → revisar o código produzido- Executar o Claude 3 ou usar
/clearnovamente → ler o código e a revisão, e aplicar as correções
Ou então,
- Claude 1: escreve os testes
- Claude 2: escreve o código que faz os testes passarem
❗ Também é possível fazer com que as instâncias do Claude compartilhem scratchpads separados entre si,
ou definir papéis distintos, como “este Claude só grava no arquivo A, aquele Claude só lê o B”
📌 Muitas vezes, dividir o trabalho produz resultados melhores do que usar um único Claude
b. Fazer vários checkouts do repositório
Em vez de esperar o Claude terminar o trabalho, é possível criar vários diretórios de checkout do Git e trabalhar em paralelo
- Criar 3 ou 4 checkouts do git em pastas separadas
- Abrir cada pasta em uma aba diferente do terminal
- Atribuir tarefas diferentes a cada instância do Claude
- Alternar entre as abas para verificar o progresso e aprovar/rejeitar
c. Usar Git worktree
git worktree é um recurso do Git para fazer checkout de vários branches do mesmo repositório em diretórios diferentes
→ ideal para processar várias tarefas independentes em paralelo
Ex.:
- Um Claude refatora o sistema de autenticação
- Outro Claude cria, separadamente, um componente de visualização de dados
- Sem interferência entre eles → paralelismo maximizado
Como usar
- Criar um worktree:
git worktree add ../project-feature-a feature-a - Executar o Claude:
cd ../project-feature-a && claude - Repetir quantas vezes forem necessárias
Dicas
- Mantenha consistência nos nomes dos worktrees
- Use um worktree por aba do terminal
- Se você usa iTerm2 (Mac), é recomendável configurar notificações
- Separe também a IDE conforme cada worktree
- Ao concluir o trabalho, faça a limpeza:
git worktree remove ../project-feature-a
d. Modo headless + estrutura de automação personalizada
O modo headless (claude -p) permite integrar programaticamente o Claude Code ao workflow
Combinando isso com as próprias ferramentas do Claude e system prompts, é possível aplicar os dois padrões a seguir
1. Fanning out: distribuir tarefas de migração/análise em larga escala
Exemplo:
- Peça ao Claude para escrever um script de geração de lista de tarefas
→ Ex.: gerar uma lista de 2.000 arquivos para migrar de React para Vue - Execute cada tarefa com
claude -p
→ Ex.:
claude -p "migrate foo.py from React to Vue. When done, return OK or FAIL." --allowedTools Edit Bash(git commit:*) - Refine o prompt várias vezes para otimizar o desempenho
2. Pipelining: integração de pipeline de dados/processamento
- Conecte diretamente a saída do Claude ao próximo comando:
claude -p "<your prompt>" --json | your_command - Graças à estrutura de saída em JSON do Claude, ela é fácil de usar em processamento automatizado
Dicas de depuração
- Durante os testes, use
--verbosepara verificar o fluxo de execução do Claude - Em operação real, recomenda-se desativar o verbose para manter a saída limpa
2 comentários
Quanto isso deve custar, mais ou menos?
Comentários do Hacker News
O recurso "ultrathink" é interessante
Surpreende que não haja uma seção sobre "controle de custos"
Ao usar bastante o Cursor, às vezes o modelo altera código que não foi solicitado
Testou o Claude Code, mas migrou para o Gemini AI por causa do custo
Para usar o Claude Code de forma eficaz, é preciso gastar bastante
Opinião pessoal sobre o custo-benefício do Claude Sonnet e do Gemini
É interessante usar vários checkouts
git worktreespela primeira vez, e é uma forma de gerenciar vários checkouts com eficiênciaCuriosidade sobre alternativas ao Claude Code da Gemini e ao Codex da OpenAI
Trabalha principalmente no neovim, mas abre o Cursor para escrever código boilerplate
Tem medo do custo e por isso não consegue usar