Aula 11O arquivo CLAUDE.md: as regras da casa

🖥️ Versão Desktop. Nesta versão do curso, você usa o Claude Code no app Claude Desktop, na aba Code. Quase tudo é feito por janelas e botões. Quando uma aula pedir para digitar um comando, ela mostra exatamente o que digitar. Nesta aula, você não digita nenhum comando: tudo é pedido na caixa de mensagem, e o app mostra cada mudança para você aceitar. A parte opcional do fim cita alguns comandos do terminal, para quem já programa.

Objetivos

Ao final desta aula você vai saber:

• O que é o CLAUDE.md, o arquivo com as regras da casa da sua página
• Criar as regras da casa pedindo ao Claude, ler o que ele propõe e guardar uma versão
• Conferir, numa conversa nova, que o Claude segue as regras sem você contar
• Mudar uma regra pedindo em português
• A diferença entre as regras da casa e a memória automática, as anotações do próprio Claude
• Por que as regras da casa orientam, mas não trancam, e o que nunca entra nelas

Toda conversa nova com o Claude começa do zero: ele não lembra do que vocês combinaram na anterior. Na Aula 07, você contornou isso com o decisoes.md, pedindo "leia o decisoes.md" a cada conversa nova. Nesta aula, você escreve as regras da casa, num arquivo que o Claude lê sozinho, sem você pedir.

Para esta aula: a pasta da sua página (a confeitaria, ou a da sua ideia), com as versões guardadas desde a Aula 06. O decisoes.md da Aula 07 ajuda, mas não é obrigatório. Não precisa de GitHub.

O que é o CLAUDE.md

O CLAUDE.md é um arquivo de texto na pasta da sua página, que o Claude lê no começo de toda conversa. O que está escrito nele, você não precisa repetir.

📝 Markdown: o .md no fim do nome quer dizer Markdown, um texto simples com algumas marcas, como # no começo de uma linha para fazer um título e - para fazer uma lista. Você não precisa escrever nenhuma marca: o Claude escreve, e você lê como um texto comum.

Crie as regras da casa

Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha. Escreva na caixa de mensagem:

Crie um CLAUDE.md com as regras da casa desta página: o texto é em
português do Brasil; as cores são os tons de rosa de hoje; o modo escuro,
o filtro do cardápio e o formulário de encomenda têm de continuar
funcionando; a página precisa ficar fácil de ler no celular; não instale
nada sem me perguntar; e, antes de rodar um comando, explique em
português simples o que ele faz.

Tem o decisoes.md da Aula 07? Acrescente ao pedido: "e use as cores e os textos combinados no decisoes.md".

O app mostra o diff do arquivo novo: leia o que ele propõe e aceite. Depois, peça "guarde uma versão com o CLAUDE.md" e aprove os comandos do Git, como na Aula 06.

O arquivo novo fica na pasta da página, ao lado do index.html, e lembra uma lista de combinados. O seu vai ter outras palavras, mas a ideia é esta:

# Regras da casa da confeitaria

- O texto da página é em português do Brasil.
- As cores são os tons de rosa de hoje, como estão no decisoes.md.
- O modo escuro, o filtro do cardápio e o formulário de encomenda têm de continuar funcionando.
- A página precisa ficar fácil de ler no celular.
- Não instale nada sem perguntar antes.
- Antes de rodar um comando, explique em português simples o que ele faz.

Para ler o arquivo depois, clique no caminho CLAUDE.md na conversa: ele abre no painel de arquivos. O que você digitar ali é salvo sozinho, então, para mudar uma regra, prefira pedir ao Claude.

Confira numa conversa nova

O teste de verdade é numa conversa em que o Claude não ouviu nada do que vocês combinaram. Clique em + New, que começa uma conversa nova (Aula 07), confira na linha abaixo da caixa de mensagem a pasta da página e o Manual, e pergunte:

Quais são as regras desta página?

Ele responde com as regras da casa, sem você contar. Agora, um pedido que esbarra numa delas:

Instale uma biblioteca de animações na página.

Ele tem de perguntar antes de instalar. Esse é o critério de pronto: numa conversa nova, o Claude diz as regras da página sem você contar e pergunta antes de instalar. Responda "não precisa, deixe a página como está". Se, em vez de perguntar, ele já pedir licença para mudar um arquivo ou rodar um comando, recuse: daqui a pouco você vê por que isso pode acontecer.

💡 O app e o terminal leem os mesmos arquivos CLAUDE.md. Se um dia você usar os dois na mesma pasta, as regras da casa valem nos dois.

Mude uma regra

As regras mudam junto com a confeitaria. Para acrescentar uma, peça:

Acrescente ao CLAUDE.md que a confeitaria fecha às segundas.

O app mostra o diff da mudança no arquivo: leia e aceite, como qualquer mudança. Depois, peça "guarde uma versão com a regra nova". Da próxima conversa em diante, a regra vale sem você repetir.

Para tirar uma regra, é igual: "tire do CLAUDE.md a regra sobre...".

A memória automática

Além das regras da casa, que você pede e aprova, o Claude guarda anotações dele mesmo: a memória automática (auto memory). Quando você pede para ele lembrar de alguma coisa, é para lá que vai. Experimente:

Lembre que eu prefiro fotos com fundo claro.

Ele guarda a anotação e avisa na conversa. Se pedir licença para gravar numa pasta do Claude, fora da pasta da página, pode aceitar: é lá que fica a memória automática. As duas memórias são lidas no começo de toda conversa, mas são bem diferentes:

No app, para ver o que ele anotou, pergunte:

O que você guardou na memória sobre este projeto?

As anotações são arquivos de texto comuns, numa pasta do Claude neste computador. Se a resposta citar o caminho de um deles e você quiser ver a pasta, clique com o botão direito no caminho e escolha Show in Finder (mostrar no Finder, no Mac) ou Show in Explorer (no Windows).

💡 Qual das duas usar? O que vale para a página, e que você quer ler e mudar, vai para as regras da casa: peça "acrescente ao CLAUDE.md". Um gosto seu, que só serve neste computador, pode ficar na memória automática. Quer que uma anotação vire regra? Peça: "passe para o CLAUDE.md a anotação sobre as fotos".

Orienta, não tranca

O Claude lê as regras da casa e tenta segui-las, mas não há garantia: numa conversa longa, ou com uma regra vaga, ele pode deixar uma passar. Por isso, o que precisa ser garantido não fica só no CLAUDE.md. Vai numa regra de permissão: a deny que impede o Claude de ler o .env (Aula 05) e a ask que faz ele perguntar antes de enviar para o GitHub (Aula 10). Na Aula 15, você conhece as ações automáticas, que rodam sempre, sem depender de o Claude lembrar.

E o Manual continua valendo: cada mudança e cada comando ainda passam por você. As regras da casa não mudam isso.

Curto e sem segredo

O CLAUDE.md é lido em toda conversa e ocupa espaço na memória de trabalho (Aula 07). Por isso:

• Curto: só o que vale em toda conversa. O que é de uma tarefa só fica na conversa dela.
• Claro: regras que dá para conferir, como "não instale nada sem perguntar", funcionam melhor que pedidos vagos, como "capriche".
• Sem segredo: nada de senha, telefone ou dado de cliente. A senha fica no .env, trancada pela regra deny. E, no projeto final (Aula 19), a pasta vai para um repositório público no GitHub, que qualquer pessoa lê, com o CLAUDE.md dentro.

Para ir além (opcional): o CLAUDE.md em projetos de código

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra o CLAUDE.md como um projeto de software costuma usar: gerar um arquivo inicial, os quatro lugares onde ele pode ficar, as regras por pasta, os @ que importam arquivos, o tamanho, a instrução de compactação, o AGENTS.md e a memória automática por dentro. Se você nunca programou, pule direto para o Na prática: tudo o que ele pede já foi explicado acima.

📁 O ~ e as pastas com ponto: ~ é a sua pasta pessoal, a que tem o seu nome de usuário. Uma pasta com ponto no começo do nome, como .claude, fica escondida no Mac e no Linux até você pedir para mostrar (Aula 00). Então ~/.claude/CLAUDE.md quer dizer: na sua pasta pessoal, dentro da pasta escondida .claude, o arquivo CLAUDE.md.

Comece pedindo um arquivo inicial

Num projeto de código, peça ao Claude para analisar o projeto e gerar um CLAUDE.md inicial, com os comandos de build e de testes e as convenções que ele encontrar:

Crie um CLAUDE.md com instruções para este projeto.

Revise o resultado no diff (Aula 09). Se já existir um CLAUDE.md, peça para ele sugerir melhorias em vez de sobrescrever. Depois, corte o que ele descobriria sozinho lendo o código e acrescente o que ele erra. No terminal, o comando /init faz esse mesmo trabalho.

Um CLAUDE.md típico de um projeto de código:

# Projeto

Este é um app Next.js 15 usando App Router, Tailwind e Drizzle ORM.

# Comandos
- Servidor de desenvolvimento: `pnpm dev`
- Rodar testes: `pnpm test`
- Lint: `pnpm lint`

# Estilo de código
- Use indentação de 2 espaços
- Prefira exports nomeados
- Todas as rotas de API ficam em app/api/
- Use server actions em vez de rotas de API sempre que possível

Os quatro lugares, que se somam

O Claude lê todos, do mais amplo ao mais específico, e nenhum apaga o outro. Se dois se contradizem, ele pode seguir qualquer um, então revise de vez em quando. Um CLAUDE.md dentro de uma subpasta carrega quando o Claude mexe em arquivos daquela pasta. O app usa os mesmos arquivos que o terminal, inclusive o CLAUDE.local.md.

Regras por pasta, em .claude/rules/

Em projetos grandes, as instruções podem ser divididas em arquivos dentro de .claude/rules/, um tema por arquivo, como testes.md. Uma regra com o campo paths no cabeçalho só entra no contexto quando o Claude trabalha em arquivos que batem com aquele caminho (ex.: src/api/**/*.ts). As regras pessoais, para todos os projetos, ficam em ~/.claude/rules/.

Aponte documentos, não importe tudo

Um @caminho dentro do CLAUDE.md importa o arquivo: ele é carregado inteiro no começo de toda conversa, então não economiza nada. Um arquivo importado pode importar outros, até quatro níveis. Importe só o que vale sempre; para documentos longos, escreva o caminho sem @ e diga quando ler:

# Documentação
- Comandos disponíveis: @package.json
- Regras da API: leia `docs/api.md` antes de mexer em app/api/

Na primeira vez que um projeto importa um arquivo de fora da pasta dele, o Claude Code pede a sua aprovação.

Mantenha enxuto

Mire em menos de 200 linhas por arquivo: arquivos longos gastam contexto e são seguidos com menos fidelidade. De vez em quando, peça uma faxina: "Revise meu CLAUDE.md e aponte o que você descobriria sozinho lendo o código e as instruções desatualizadas ou contraditórias."

O que sobrevive à compactação

O CLAUDE.md da raiz do projeto é relido do disco depois do /compact. Uma instrução dada só na conversa pode se perder na compactação; se ela tem de durar, vai para o arquivo. Para dizer o que preservar ao compactar (Aula 07), acrescente uma seção ao CLAUDE.md:

# Compact instructions

Ao compactar, preserve sempre a lista de arquivos que você mudou e as cores e os textos combinados.

Se você editar o CLAUDE.md à mão no meio de uma conversa, digite /compact ou comece uma conversa nova, com + New, para o Claude reler o arquivo.

Já usa outro agente de código?

Se o repositório tem um AGENTS.md e nenhum CLAUDE.md, o Claude Code lê o AGENTS.md (desde a versão 2.1.277). Com os dois, ele lê só o CLAUDE.md, a não ser que o CLAUDE.md importe o AGENTS.md com @AGENTS.md.

A memória automática por dentro

As anotações são arquivos Markdown comuns, que você pode ler, editar ou apagar. Ela vem ligada nas sessões Local e não vai para outro computador nem para as sessões Cloud.

• Para desligar a memória automática, peça ao Claude para pôr "autoMemoryEnabled": false num arquivo de configurações: no .claude/settings.local.json do projeto, para valer só nele, ou no ~/.claude/settings.json, para todos.
• No terminal, o /memory lista os arquivos de regras, liga e desliga a memória automática e abre a pasta das anotações, e o /context mostra, em Memory files, quais arquivos foram carregados.

Na prática

Use a pasta da sua página (a confeitaria, ou a da sua ideia).

1. Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha.
2. Escreva o pedido das regras da casa, do jeito que está lá em cima, com o complemento do decisoes.md, se você tiver. O app mostra o diff do arquivo novo: leia o que ele propõe e aceite.
3. Peça "guarde uma versão com o CLAUDE.md" e aprove os comandos do Git.
4. Clique em + New, confira a pasta e o Manual e pergunte: "quais são as regras desta página?".
5. Peça "instale uma biblioteca de animações na página". Está pronto quando ele perguntar antes de instalar. Responda "não precisa, deixe a página como está".
6. Peça "acrescente ao CLAUDE.md que a confeitaria fecha às segundas", aceite o diff e peça "guarde uma versão com a regra nova".
7. Peça "lembre que eu prefiro fotos com fundo claro". Depois, pergunte: "o que você guardou na memória sobre este projeto?".

Resumo

• O CLAUDE.md guarda as regras da casa: é um arquivo de texto na pasta da página, que o Claude lê no começo de toda conversa, no app e no terminal.
• Crie pedindo, leia o diff, aceite e guarde uma versão. O teste é numa conversa nova, com + New: ele diz as regras sem você contar e pergunta antes de instalar.
• Para mudar uma regra, peça "acrescente ao CLAUDE.md...". Para ele lembrar de um gosto seu, "lembre que..." vai para a memória automática, que fica só neste computador. Para ver o que ele anotou, pergunte.
• As regras da casa orientam, não trancam: o que precisa ser garantido vai numa regra deny ou ask.
• Curto e sem segredo: nada de senha, telefone ou dado de cliente, porque ele vai junto para o GitHub no projeto final.

Na próxima aula, você vai ver que, às vezes, o Claude chama ajudantes para uma parte do trabalho: os subagentes.