CLAUDE.md ou spec da tarefa: o que é regra permanente e o que é escopo?

Fala aí, beleza? Todo projeto tem aquele arquivo que começou pequeno e virou depósito de tudo: convenção do repositório, comando de build, decisão de arquitetura e, no meio da bagunça, um "não mexe no schema até sexta" que alguém escreveu numa terça de três meses atrás

São dois papéis diferentes empurrados pra dentro do mesmo arquivo

Um é a convenção do repositório: vale hoje, vale amanhã, vale pra quem entrar no time semana que vem

O outro é a especificação de uma entrega: nasce quando a tarefa começa e morre quando ela termina

A documentação do Claude Code é bem direta sobre o primeiro: o CLAUDE.md é um arquivo markdown com instruções persistentes que o Claude lê no início de toda sessão

Ou seja, o que tu escreve ali volta pro contexto SEMPRE, inclusive quando o trabalho do dia não tem nada a ver com aquilo

Bora montar um critério pra decidir onde cada linha que você escreve deveria morar?

O que você precisa saber antes de separar os dois arquivos

Antes do passo a passo, o básico verificável, porque metade da confusão vem daqui

CLAUDE.md é markdown, escrito em texto puro, com instruções persistentes

Você escreve, o Claude lê no começo de toda sessão

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Ele é encontrado subindo a árvore de diretórios

O Claude Code lê os arquivos CLAUDE.md caminhando pra cima a partir do diretório de trabalho atual, checando cada pasta em busca de CLAUDE.md e CLAUDE.local.md

Isso já te diz uma coisa importante: o CLAUDE.md é escopado por DIRETÓRIO

Ele pode morar na raiz do repositório ou dentro de .claude/

Os dois lugares valem, e o .claude é o diretório onde o Claude Code lê os artefatos do projeto (CLAUDE.md, settings.json, hooks, skills, comandos, subagents, workflows e rules)

Se serve de alívio: a maioria das pessoas só edita CLAUDE.md e settings.json, o resto é opcional

Instrução sua, de pessoa, fica em ~/.claude/CLAUDE.md

No Windows, ~/.claude resolve pra %USERPROFILE%\.claude

E tem um segundo mecanismo que carrega junto e costuma ser confundido com o que você escreveu à mão: a auto memory

São notas que o próprio Claude escreve a partir das suas correções e preferências

Dois mecanismos, os dois carregados no início de toda conversa: os arquivos CLAUDE.md (o que VOCÊ escreve) e a auto memory (o que ELE escreve)

Cada projeto tem seu diretório de auto memory em ~/.claude/projects/<project>/memory/, e esse caminho <project> é derivado do repositório git, então todas as worktrees e subpastas do mesmo repo compartilham um único diretório de auto memory

Saber disso evita o clássico "eu não escrevi isso aí" 😀

Passo a passo: decidindo onde escrever cada linha

A régua é uma pergunta só, aplicada linha por linha

1. Pergunte se o Claude precisa disso em TODA sessão

A documentação dá o corte explícito: coloque no CLAUDE.md se o Claude sempre deve saber aquilo (convenções de código, comandos de build, estrutura do projeto, regras de "nunca faça X")

Coloque numa skill se for material de referência que ele precisa às vezes (documentação de API, guia de estilo) ou um fluxo que você dispara com /<nome> (deploy, review, release)

O detalhe que muda tudo: por padrão, as descrições das skills carregam no início da sessão e o conteúdo completo só entra quando a skill é usada

O erro comum deste passo é despejar o guia de estilo inteiro no CLAUDE.md "pra garantir", e aí ele viaja junto em toda sessão

Se a sua dúvida for especificamente sobre padrão visual, vale a leitura de escolher entre skill e CLAUDE.md pra esse caso

2. Reconheça os gatilhos legítimos de escrever no CLAUDE.md

A própria documentação lista quando adicionar:

• o Claude comete o mesmo erro pela segunda vez
• um code review pega algo que o Claude deveria saber sobre este repositório
• você digita no chat a mesma correção ou esclarecimento que digitou na sessão passada
• um colega novo precisaria do mesmo contexto pra ser produtivo

Repara que os quatro têm a mesma cara: é conhecimento sobre o REPOSITÓRIO, não sobre a tarefa de hoje

3. Reconheça o que não é permanente

Restrição que só existe por causa de uma entrega não pertence à orientação permanente do repositório

O motivo é meio óbvio quando alguém fala em voz alta: adicionar uma restrição temporária à orientação permanente deixa uma restrição temporária pra trás depois que o trabalho terminou

Aí o Claude segue obedecendo em janeiro uma regra que fazia sentido em agosto

O erro comum deste passo é o "deixa aí que depois eu tiro"… spoiler: ninguém tira

4. Coloque o escopo da entrega onde ele pertence: no plano

O plan mode diz pro Claude pesquisar e propor mudanças sem fazê-las

Ele lê arquivos, roda comandos de shell pra explorar e escreve um plano, mas não edita o seu código

Pra entrar, é Shift+Tab ou prefixar um prompt único com /plan

/plan quero adicionar paginação na listagem de posts

Outro Shift+Tab sai do plan mode sem aprovar plano nenhum

Quando o plano fica pronto, o Claude apresenta e pergunta como seguir

Ctrl+G abre o plano proposto no seu editor de texto padrão pra você editar antes de ele prosseguir

Esse é o lugar do "nesta tarefa, não toque em X": no plano da tarefa, editado por você, e não na regra eterna do repo

O erro comum deste passo é tratar plano aprovado como convenção do repositório e sair copiando o combinado da entrega pro CLAUDE.md

5. Respeite o teto de tamanho

A recomendação é mirar abaixo de 200 linhas por arquivo CLAUDE.md, porque arquivos mais longos consomem mais contexto e REDUZEM a aderência

E tem o custo silencioso: o conteúdo do CLAUDE.md é carregado no contexto no início da sessão, então se ele tem instruções detalhadas pra fluxos específicos (tipo review de PR ou migração de banco), esses tokens estão lá mesmo quando você está fazendo trabalho não relacionado

O erro comum deste passo é achar que quebrar o arquivo resolve: dividir em imports @path ajuda na organização, mas NÃO reduz contexto, já que os arquivos importados carregam no lançamento

A saída indicada pra arquivo grande é outra: usar regras escopadas por caminho, pra que as instruções carreguem só quando o Claude trabalha com os arquivos que casam, ou cortar o que não é necessário em toda sessão

6. Confira o que está realmente carregado

/memory

O comando lista todos os arquivos CLAUDE.md, CLAUDE.local.md e de regras carregados na sua sessão atual, deixa ligar e desligar a auto memory e dá um link pra abrir a pasta da auto memory

É o jeito de parar de adivinhar e ver a lista

Se você chegou até aqui e percebeu que seu arquivo tá mais pra diário de bordo, tem um post inteiro sobre escrever um CLAUDE.md melhor

Onde cada tipo de instrução mora: CLAUDE.md, regras por caminho, CLAUDE.local.md

Decidido o que é permanente, falta escolher o destino

E aqui entra a diferença mais útil de todas: CLAUDE.md é escopado por diretório, enquanto .claude/rules/ é escopado por padrão de arquivo

Regras podem ser escopadas pra arquivos específicos usando frontmatter YAML com o campo paths

Essas regras condicionais só se aplicam quando o Claude está trabalhando com arquivos que casam com os padrões especificados

Ou seja: a convenção de migration só aparece quando ele mexe em migration, e não em toda sessão

Sobre a terceira linha, se liga que é bem prático: pra preferências pessoais por projeto que não devem ir pro controle de versão, você cria um CLAUDE.local.md na raiz do projeto

Ele carrega junto com o CLAUDE.md e é tratado da mesma forma

Aí você adiciona CLAUDE.local.md ao seu .gitignore pra ele não ser commitado

/init

Rodando o /init e escolhendo a opção pessoal, isso já é feito pra você

A divisão geral é essa: arquivos de projeto devem ser commitados no git pra compartilhar com o time, e os arquivos em ~/.claude são configuração pessoal que se aplica em todos os seus projetos

O desenho fica mais ou menos assim:

projeto/
  CLAUDE.md
  CLAUDE.local.md
  .claude/
    rules/

E vale repetir o ponto do passo 5, porque é a válvula de escape do arquivo inchado: quando as instruções estão crescendo demais, regras escopadas por caminho fazem elas carregarem só quando o Claude trabalha com os arquivos correspondentes

O spec não sobreviveu à sessão seguinte: por que acontece e o que fazer

O sintoma é conhecido: você combinou o escopo, ele seguiu direitinho por um tempo, e na sessão seguinte o Claude ignora o combinado ou repete algo que você já corrigiu

A causa incomoda, mas é honesta: o CLAUDE.md comunica intenção, não impõe restrição

É orientação, não trava

Por isso escrever mais texto em maiúsculas ali dentro não é a solução (nem "PROIBIDO", nem "CRÍTICO", nem nada disso)

A solução que times usam é somar mecanismos: hooks de pre-commit e regras escopadas por caminho, pra que as specs se sustentem entre sessões

Um é orientação, o outro é verificação de verdade no momento do commit

E antes de culpar o modelo, roda o /memory e confere o que está carregado de fato naquela sessão

Muita "regra ignorada" é regra que nunca entrou, porque o diretório de trabalho atual estava em outro lugar da árvore

Como prevenir, em duas linhas:

• permanente enxuto, abaixo de 200 linhas, só o que o Claude precisa em toda sessão
• escopo da entrega no plano da tarefa, onde ele pode ser editado, aprovado e depois esquecido sem sobrar lixo

Um material pra organizar o Claude Code do zero

Se você está começando agora a organizar o seu setup, o vídeo abaixo apresenta o GStack no Claude Code

Conclusão

O critério cabe numa pergunta: essa linha vale em toda sessão ou só nesta entrega?

Se vale sempre, é convenção do repositório e mora no CLAUDE.md, commitado pro time

Se é condicional, vira regra escopada por caminho e carrega só quando o Claude toca nos arquivos que casam

Se é preferência sua, é CLAUDE.local.md no .gitignore ou o seu ~/.claude

E se nasceu com a tarefa, é escopo: vive no plano, editável com Ctrl+G, e some quando a entrega acaba

O próximo passo é bem concreto: abre o seu CLAUDE.md atual, roda /memory pra ver o que está carregado de verdade, corta o que era de tarefa antiga e move o que é condicional pras regras por caminho

Mira abaixo de 200 linhas e olha a diferença na aderência

Até o próximo post! 🙂