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

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

Abra o Claude Code na pasta da sua página e confira o manual mode on (o passo 1 do Na prática mostra como). Peça:

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".

Leia o arquivo que ele propõe e aprove. 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.

Confira numa conversa nova

O teste de verdade é numa conversa em que o Claude não ouviu nada do que vocês combinaram. Digite /clear, que começa uma conversa nova (Aula 07), confira se continua manual mode on 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.

💡 Quer ver que o arquivo foi lido? Digite /context: o CLAUDE.md aparece na lista Memory files (arquivos de memória).

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.

Ele propõe a mudança no arquivo, e você aprova, 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 aprovar: é 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:

Para ver as anotações, digite /memory. Ele mostra a lista dos arquivos de regras, o interruptor que liga e desliga a memória automática e a opção de abrir a pasta onde ficam as anotações. Use as setas para andar pela lista e Esc para fechar. Por enquanto, só olhe: escolher um arquivo da lista abre esse arquivo para editar.

O jeito mais simples de ler o que ele anotou é perguntar: "o que você guardou na memória sobre este projeto?"

💡 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: o /init, 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 com o /init

Num projeto de código, o /init analisa o projeto e gera um CLAUDE.md inicial, com os comandos de build e de testes e as convenções que ele encontrar. Se já existir um, ele sugere melhorias em vez de sobrescrever. Depois, corte o que ele descobriria sozinho lendo o código e acrescente o que ele erra. Com a variável CLAUDE_CODE_NEW_INIT=1, o /init vira um passo a passo que passa também por skills, hooks e arquivos de memória pessoais.

/init

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.

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. O /doctor prompt-audit procura instruções desatualizadas ou contraditórias no CLAUDE.md, nas regras, nas skills e nos subagentes, e só muda os arquivos se você pedir.

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, rode /clear ou /compact 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 opção Project instructions, no /config, muda esse padrão.

A memória automática por dentro

Quando o Claude grava ou consulta a memória, a conversa mostra linhas como Saved 2 memories ou Recalled 2 memories. As anotações são arquivos Markdown comuns, que você pode ler, editar ou apagar. Ela não vai para outro computador nem para as sessões na nuvem.

• Ligar e desligar: o interruptor do /memory grava autoMemoryEnabled no ~/.claude/settings.json. Para desligar só num projeto, "autoMemoryEnabled": false nas configurações daquele projeto; para desligar por variável, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• Editar pelo /memory: escolher um arquivo abre o seu editor. Editores de janela, como o VS Code, abrem à parte; editores de terminal, como o Vim, tomam conta do terminal até você sair deles.

Na prática

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

1. Abra o terminal, entre na pasta e abra o Claude Code: cd Documents/confeitaria, com o nome da sua pasta, e depois claude. Aperte Shift + Tab uma vez e confira se aparece manual mode on.
2. Faça o pedido das regras da casa, do jeito que está lá em cima, com o complemento do decisoes.md, se você tiver. Leia o que ele propõe e aprove.
3. Peça "guarde uma versão com o CLAUDE.md" e aprove os comandos do Git.
4. Digite /clear, confira o manual mode on 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", aprove e peça "guarde uma versão com a regra nova".
7. Peça "lembre que eu prefiro fotos com fundo claro". Digite /memory, olhe a lista e aperte Esc. 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.
• Crie pedindo, leia o que ele propõe, aprove e guarde uma versão. O teste é numa conversa nova: 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. O /memory mostra as duas.
• 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.