CLAUDE.md: o arquivo que deixa o Claude Code mais esperto

Resposta curta: Um arquivo CLAUDE.md é como um manual de instruções pessoal para o seu projeto. Você escreve nele como quer que o Claude Code trabalhe nas suas pastas. Isso deixa a ajuda mais rápida e certa, porque o Claude já começa sabendo das suas regras.

Já aconteceu de você pedir para alguém te ajudar em um projeto, mas essa pessoa faz tudo do jeito dela e você precisa ficar corrigindo? É chato, né? Com o Claude Code, uma ferramenta de IA para programação, isso pode acontecer também. Você pede para ele criar um botão, mas ele usa cores que não combinam com o seu site ou escreve o código de um jeito que você não gosta.

A solução para isso é um pequeno arquivo de texto chamado CLAUDE.md. É como se você sentasse com o Claude antes de começar o trabalho e dissesse: "Olha, nas minhas coisas, a gente faz assim...". Com esse arquivo no lugar certo, o Claude Code fica muito mais "esperto" para o que você precisa. Vamos entender como?

Índice

1. O que é o CLAUDE.md, na prática?
2. Por que eu preciso disso se o Claude já é inteligente?
3. Onde colocar e como fazer o meu primeiro CLAUDE.md
4. O que botar dentro do arquivo? Ideias para começar
5. CLAUDE.md x Skills: qual a diferença?
6. Dicas finais para você começar a usar hoje
7. Recomendamos testar estas 3 skills primeiro
8. Perguntas frequentes
9. Leia também

O que é o CLAUDE.md, na prática?

Imagine que você tem uma caixa de ferramentas (sua pasta de projetos no computador). O CLAUDE.md é um post-it bem organizado colado na tampa dessa caixa.

Nesse post-it, você anota coisas importantes para quem for usar as ferramentas:

• "As chaves de fenda ficam do lado esquerdo."
• "Sempre limpe a ferramenta antes de guardar."
• "Para parafusos pequenos, use a chave número 2."

No mundo digital, esse "post-it" é um arquivo de texto com nome CLAUDE.md. Quando você abre o Claude Code dentro da pasta do seu projeto, ele procura por esse arquivo. Se encontrar, lê todas as suas instruções antes de começar a trabalhar. É como dar um mapa das suas preferências para ele.

Analogia: Se o Claude Code fosse um novo estagiário, o CLAUDE.md seria o manual de boas-vindas da sua empresa, feito por você.

Por que eu preciso disso se o Claude já é inteligente?

O Claude é muito inteligente sim, mas ele não é adivinho. Sem instruções, ele age de um jeito "genérico", usando as melhores práticas que ele conhece do mundo todo.

Vamos pensar em um exemplo do dia a dia. Você pede um café. Sem mais informações, o barista te dá um café padrão. Mas se você disser "um café com duas colheres de açúcar e um pouco de leite quente, por favor", você recebe exatamente o que quer. O CLAUDE.md é onde você coloca suas "duas colheres de açúcar" para o projeto.

Aqui estão os benefícios claros:

• Consistência: Todo código novo que o Claude criar vai seguir as mesmas regras de formatação, nomes de arquivos e estrutura.
• Eficiência: Você não precisa repetir a mesma explicação toda vez que pedir algo. "Lembre-se de usar aspas simples" vira uma regra escrita.
• Contexto: Você pode explicar coisas específicas do seu projeto que não estão óbvias no código. Por exemplo: "Este projeto é para o cliente X, que prefere botões azuis."

Onde colocar e como fazer o meu primeiro CLAUDE.md

Fazer isso é mais fácil do que parece. Você não precisa de programas especiais.

1. Abra a pasta do seu projeto. É a pasta principal onde ficam todos os arquivos do seu site, aplicativo ou script.
2. Crie um novo arquivo de texto. Você pode usar o Bloco de Notas (Windows), o TextEdit (macOS, em formato de texto puro) ou qualquer editor de código simples.
3. Nomeie o arquivo exatamente como CLAUDE.md. O nome precisa ser em letras maiúsculas, com o ponto e a extensão .md. A extensão .md significa "Markdown", que é um jeito simples de formatar texto.
4. Salve o arquivo direto na pasta raiz do seu projeto. Não dentro de uma subpasta. É na porta de entrada.
5. Escreva suas instruções dentro do arquivo. Pode começar com algo simples, como "Por favor, use o idioma português nas respostas.".
6. Pronto! Da próxima vez que você abrir o Claude Code nessa pasta, ele vai ler o seu arquivo.

O que é uma "pasta raiz"? É a pasta principal, a mais externa do seu projeto. Se seu projeto fosse uma casa, a pasta raiz seria o endereço dela. Dentro dela ficam a sala (a pasta src), a cozinha (a pasta assets), etc.

O que botar dentro do arquivo? Ideias para começar

Não sabe o que escrever? Comece com o que te incomoda ou o que você mais repete. Aqui vão algumas ideias organizadas em tópicos.

Regras Gerais do Projeto:

- Sempre escreva os comentários no código em português.
- O nome deste projeto é "Site da Padaria Doce Pão". Use este nome nas mensagens.
- Para dúvidas, priorize soluções simples em vez de soluções complexas e novas.

Preferências de Código:

- Use aspas simples (') para strings em JavaScript, não aspas duplas (").
- A indentação (os espaços no começo da linha) deve ser de 2 espaços, não 4.
- Nomes de arquivos devem ser em letras minúsculas, separadas por hífens (ex: meu-arquivo.css).

Estrutura de Pastas (Opcional):

Uma breve explicação do que cada pasta faz:
- /src: Aqui fica o código principal do site.
- /assets: Aqui ficam as imagens e ícones.
- /docs: Aqui ficam os manuais e documentação.

Lembre-se: você pode ir editando e melhorando esse arquivo com o tempo. Ele é vivo!

CLAUDE.md x Skills: qual a diferença?

Essa dúvida é comum. Ambos ensinam coisas ao Claude, mas de jeitos diferentes.

Pense no CLAUDE.md como as regras da sua casa. São instruções gerais para quem vai trabalhar ali dentro: "Tire os sapatos na entrada", "A luz da cozinha é o interruptor da direita". Ele é estático, um arquivo de texto.

Já uma Skill é como contratar um especialista para uma tarefa específica. É um pequeno pacote que ensina ao Claude como fazer algo muito concreto, como conectar-se a uma planilha online ou traduzir textos de uma forma especial. As Skills são programas um pouquinho mais complexos.

Resumindo:

• CLAUDE.md: Para regras e contexto do seu projeto específico. (Ex: "No meu projeto, faça assim.").
• Skill: Para adicionar habilidades novas ao Claude. (Ex: "Aprenda a buscar dados no Google Sheets.").

Você pode (e deve) usar os dois juntos! Um define o ambiente do projeto, o outro traz ferramentas poderosas para trabalhar nele. Para saber mais sobre como expandir o Claude, confira nosso post sobre Agente de IA: o que é, como funciona e como criar o seu (sem programar).

Dicas finais para você começar a usar hoje

• Comece simples. Só o fato de ter um arquivo CLAUDE.md com uma ou duas linhas já é um grande avanço.
• Ele é seu. Não existe um modelo perfeito. Escreva o que for útil para o seu trabalho.
• Use em todos os projetos principais. Crie o hábito de fazer um CLAUDE.md para cada projeto novo.
• Atualize com o tempo. Encontrou um novo padrão que gostou? Adicione ao arquivo.
• Não é mágica. O Claude vai tentar seguir, mas pode cometer erros. Serve como um guia, não uma lei absoluta.

O mais importante é não complicar. Esse arquivo existe para te ajudar, não para ser mais uma tarefa difícil.

Recomendamos testar estas 3 skills primeiro

Que tal dar superpoderes ao Claude? Skills são pacotinhos que ensinam ele a fazer tarefas específicas. Para um leigo, é como instalar um novo aplicativo no celular: ele ganha uma função nova.

1. skill-creator-anthropics: Esta skill é incrível para começar. Ela ensina o próprio Claude Code a criar outras skills. É como dar as ferramentas para ele construir suas próprias ferramentas, seguindo o que você precisa.
2. frontend-design-anthropics: Foca em criar a parte visual de sites e aplicativos (cores, botões, layout). Se você quer protótipos ou melhorias no visual de uma página, essa skill ajuda o Claude a pensar como um designer.
3. webapp-testing-anthropics: Ensina o Claude a testar pequenas aplicações web. Ele pode simular cliques e interações para ver se tudo funciona como deveria, ajudando a pegar erros antes de você.

Para encontrar mais skills, você pode buscar skills no repositório oficial.

Perguntas frequentes

Preciso ser programador para usar o CLAUDE.md? Não! Qualquer pessoa que use o Claude Code para organizar projetos (mesmo que seja para escrever textos, planejar coisas ou analisar dados) pode se beneficiar. Basta saber escrever instruções claras.

Posso ter mais de um arquivo CLAUDE.md? Sim, você pode ter um na pasta principal do projeto (que vale para tudo) e outros em subpastas específicas. O Claude vai ler primeiro o da pasta principal e depois o da subpasta onde você está trabalhando, combinando as regras.

E se eu mudar de ideia sobre uma regra? É muito simples: basta abrir o arquivo CLAUDE.md no editor de texto, apagar ou modificar a linha e salvar. Na próxima vez que usar o Claude Code naquela pasta, ele já vai seguir a nova regra.

O Claude obedece 100% ao que está no arquivo? Ele faz o melhor possível para seguir todas as instruções. Mas como qualquer assistente, pode eventualmente cometer um deslize, principalmente se houver instruções conflitantes. O arquivo serve como um guia forte de preferências.

Funciona no Claude da web (claude.ai) também? Não. O arquivo CLAUDE.md é um recurso específico do Claude Code, o aplicativo que você instala no computador para programação. No site claude.ai, a funcionalidade similar são os "Conectores" do MCP. Para entender esse padrão, leia O que é MCP (Model Context Protocol): explicado de um jeito fácil.

Leia também

• Claude Code: o que é, como baixar, instalar e quanto custa (guia 2026) – O guia completo para começar do zero.
• Claude Code é grátis? Preços e planos – Entenda como funcionam os limites de uso.
• O que são tokens em IA (e por que eles acabam tão rápido) – A "moeda de conversa" das IAs explicada.
• Como editar vídeo com Claude e agentes de IA
• Claude vs ChatGPT vs Gemini: qual usar

---

Fontes

• Claude Code: instalação e requisitos (consultado em 16/10/2026)
• Claude Code: visão geral (consultado em 16/10/2026)
• Planos e preços do Claude (consultado em 16/10/2026)