Claude Code Rules: Como Escrever CLAUDE.md e Gerenciar o Contexto de Codificação Agente

As regras do Claude Code residem em arquivos CLAUDE.md — arquivos markdown que você coloca no repositório do seu projeto, diretório home ou configuração da organização, e que o Claude lê no início de cada sessão. Combinadas com regras de escopo de caminho em .claude/rules/, um settings.json para permissões e memória automática para preferências aprendidas, o sistema de regras oferece controle preciso e persistente sobre como o agente de codificação se comporta em qualquer tarefa.

O Que São as Regras do Claude Code?

Cada sessão do Claude Code começa com uma janela de contexto vazia. As regras são como você pré-carrega o contexto que o Claude precisa para que ele não comece do zero — ou cometa o mesmo erro duas vezes.

Dois sistemas complementares lidam com isso:

Arquivos CLAUDE.md são arquivos markdown que você escreve e que o Claude lê no início de cada sessão. Use-os para instruções que devem sempre se aplicar: comandos de build, convenções de código, decisões de arquitetura, restrições rígidas.

Memória automática são notas que o Claude escreve por conta própria com base em correções e preferências que você fornece durante as sessões. Elas se acumulam automaticamente; o Claude decide o que vale a pena salvar e lê essas notas de volta em sessões futuras.

Ambos são carregados no contexto no início da sessão, mas não são configuração imposta. São instruções que o Claude segue como contexto. Para imposição rígida — bloquear um comando específico independentemente do que o Claude decidir fazer — você precisa de um hook PreToolUse ou uma regra deny no settings.json. A distinção é importante para execuções autônomas onde você deseja comportamento previsível, não conformidade probabilística.

Locais e Escopo do Arquivo CLAUDE.md

O Claude Code carrega arquivos CLAUDE.md de vários locais, cada um cobrindo um escopo diferente. Eles são carregados em ordem do mais amplo para o mais específico:

Local	Escopo	Para que serve
~/.claude/CLAUDE.md	Todos os projetos na sua máquina	Preferências pessoais, hábitos de fluxo de trabalho globais
./CLAUDE.md (raiz do repositório)	Todas as sessões naquele projeto	Convenções do projeto, comandos de build, regras compartilhadas pela equipe
./CLAUDE.local.md (raiz do repositório)	Apenas suas sessões locais	Preferências por desenvolvedor; adicione ao .gitignore
./src/CLAUDE.md (subdiretório)	Sessões que tocam arquivos naquele diretório	Regras específicas do módulo que não se aplicam a todo o projeto

Todos os arquivos descobertos são concatenados no contexto — eles não se sobrescrevem. Dentro dessa concatenação, o conteúdo desde a raiz do sistema de arquivos até o diretório de trabalho é ordenado com o mais específico por último, de modo que uma instrução do projeto aparece após uma instrução do usuário. Isso proporciona especificidade natural: uma regra do projeto vence quando conflita com uma de nível de usuário.

Você pode importar arquivos adicionais com referências @path dentro de qualquer CLAUDE.md:

@./docs/architecture.md
@./CONTRIBUTING.md

Os arquivos importados são carregados no início da sessão, da mesma forma que o próprio CLAUDE.md. As importações são úteis para organização, mas não economizam contexto — o conteúdo importado conta para o seu orçamento de tokens.

Para equipes: commit o CLAUDE.md do projeto no controle de versão. Isso garante que todas as sessões do Claude de cada desenvolvedor — e quaisquer execuções de agentes baseadas em CI — comecem com o mesmo contexto compartilhado. Trate-o como .eslintrc ou pyproject.toml.

O Que Colocar no CLAUDE.md

O conteúdo mais útil é aquilo que você teria que reexplicar a cada sessão, ou o que um novo membro da equipe precisaria saber na primeira hora.

Bons candidatos:

• Comandos de build e teste que diferem dos padrões óbvios (./scripts/test.sh --ci, não apenas npm test)
• Convenções de código que não são capturadas pelo linter (“usamos named exports em todos os lugares; sem default exports em utilitários compartilhados”)
• Decisões de arquitetura que não são óbvias apenas lendo o código (“o diretório lib/ é compartilhado entre serviços — não adicione lógica específica de serviço lá”)
• Pegadinhas conhecidas (“o arquivo config.ts é gerado no build; não edite manualmente”)
• Restrições de fluxo de trabalho (“sempre crie um branch antes de fazer alterações; faça push para o remoto antes de abrir um PR”)

Coisas para deixar de fora:

• Listagens de diretórios e árvores de arquivos — o Claude lê isso do repositório
• Listas de dependências — disponíveis em package.json, pyproject.toml e similares
• Descrições em prosa do que o código existente faz — o Claude lê o código-fonte diretamente
• Mudanças recentes — o Claude usa git log e git diff quando precisa de histórico

Mantenha o CLAUDE.md focado no que não pode ser derivado da leitura do código. Arquivos com mais de 200 linhas consomem mais contexto e reduzem a confiabilidade da adesão. O comando /doctor no Claude Code audita um CLAUDE.md versionado e sugere remover conteúdo que é derivável do código — uma maneira útil de reduzir um arquivo inchado.

Escrevendo regras eficazes

Especificidade importa. Compare:

# Vago — menos consistente
Siga os padrões de codificação do projeto.

# Específico — mais consistente
- Use pnpm, não npm ou yarn
- Execute pnpm test antes de cada commit; não faça commit se os testes falharem
- Exporte todos os tipos compartilhados de src/types/index.ts — não defina tipos inline em arquivos de componente
- O diretório data/ é somente leitura nos testes; use fixtures de teste de tests/fixtures/ em vez disso

Cada regra deve ser acionável sem explicação adicional. Se você precisar explicar o raciocínio de uma regra para alguém, adicione o raciocínio inline — isso ajuda o Claude a aplicar a regra corretamente em casos extremos.

Regras com Escopo de Caminho com .claude/rules/

O diretório .claude/rules/ permite que você anexe regras a padrões de arquivo específicos sem carregá-las em todas as sessões. O Claude descobre arquivos em .claude/rules/ e os carrega quando você trabalha com arquivos correspondentes.

Uma estrutura típica para um monorepo TypeScript:

.claude/rules/
  api.md             # regras para src/api/** — validação de requisição, formatos de erro
  components.md      # regras para src/components/** — tipos de props, convenções de estilo
  tests.md           # regras para tests/** — padrões de fixture, configuração de mock
  database.md        # regras para migrations/ e models/ — nomenclatura de migrações, padrões de consulta

Cada arquivo de regra usa frontmatter YAML com um campo paths para controlar quando é carregado:

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# Regras de Desenvolvimento da API

- Todos os manipuladores de rota devem validar a entrada com zod antes de qualquer lógica de negócio
- Retorne erros como `{ error: string; code: string }` — nunca strings simples
- A limitação de taxa é aplicada no gateway; não a adicione dentro dos manipuladores

Regras sem um campo paths carregam incondicionalmente no início da sessão, da mesma forma que o conteúdo no CLAUDE.md do projeto. Regras com paths carregam apenas quando o Claude abre arquivos que correspondem a esses padrões.

Isso mantém o CLAUDE.md raiz do projeto conciso e garante que convenções detalhadas para uma camada da pilha não preencham o contexto durante sessões focadas em uma área diferente.

settings.json vs. CLAUDE.md

CLAUDE.md controla o que o Claude sabe e pretende fazer. settings.json controla o que o Claude realmente tem permissão para fazer.

	CLAUDE.md	settings.json
Propósito	Instruções e contexto	Permissões e configuração
Imposto?	Não — o Claude age com base nisso como orientação	Sim — regras deny bloqueiam chamadas de ferramenta incondicionalmente
Formato	Markdown de forma livre	JSON estruturado
Localização	./CLAUDE.md, ~/.claude/CLAUDE.md	.claude/settings.json, ~/.claude/settings.json

Um settings.json de projeto em .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(pnpm build)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

A lista allow pré-aprova comandos específicos para que o Claude possa executá-los sem solicitação. Isso acelera as sessões interativas para operações nas quais você confia. A lista deny bloqueia comandos incondicionalmente — independentemente do que o Claude decida fazer, independentemente do que o CLAUDE.md diga. Use deny para operações irreversíveis em dados de produção ou infraestrutura.

As configurações de nível de usuário em ~/.claude/settings.json se aplicam a todos os projetos. As configurações de projeto em .claude/settings.json se aplicam apenas naquele repositório. As configurações de projeto têm precedência sobre as configurações de usuário onde houver sobreposição.

Memória Automática: Notas do Claude

A memória automática é a contraparte do CLAUDE.md. Enquanto o CLAUDE.md são instruções que você escreve, a memória automática são notas que o Claude escreve por conta própria com base no que aprende durante suas sessões.

Quando você corrige o Claude durante uma sessão — “nós usamos Vitest, não Jest neste projeto” — ele pode salvar isso como uma nota em ~/.claude/projects/<repo>/memory/. Na próxima sessão, o Claude lê essa nota de volta e aplica a correção sem precisar ser informado novamente.

O diretório de memória contém:

~/.claude/projects/<repo>/memory/
  MEMORY.md          # índice que o Claude usa para encontrar outros arquivos; primeiras 200 linhas carregadas a cada sessão
  debugging.md       # padrões que o Claude descobriu ao resolver problemas neste repositório
  conventions.md     # convenções que o Claude aprendeu com suas correções

Isso é local da máquina e por repositório. A memória automática complementa o CLAUDE.md em vez de substituí-lo: CLAUDE.md é para regras de projeto compartilhadas pela equipe; a memória automática é para padrões pessoais que o Claude aprendeu trabalhando com você.

A memória automática é markdown legível que você pode editar ou excluir a qualquer momento. Execute /memory dentro de uma sessão para navegar e editar os arquivos. Se algo estiver desatualizado ou errado, exclua — o Claude parará de aplicar a regra desatualizada.

Melhores Práticas para Codificação Agente

Executar o Claude Code autonomamente — através de claude -p, do Agent SDK ou de pipelines de CI — aumenta a importância da sua configuração de regras. O agente pode completar dezenas de chamadas de ferramenta sem pausar, e não há vai e volta interativo para capturar mal-entendidos no meio da execução.

Escreva restrições explícitas, não apenas preferências. O Claude interativo pode pedir esclarecimentos. Uma execução autônoma trabalha com o que encontra no contexto. Se “nunca modificar arquivos de migração sem criar um snapshot de banco de dados primeiro” for importante, precisa estar no CLAUDE.md. Não presuma que o Claude inferirá a restrição a partir da estrutura do código.

Use regras deny para qualquer coisa difícil de reverter. Pré-aprovar Bash(pnpm build) acelera sessões interativas e é de baixo risco. Mas para execuções autônomas, a lista deny é sua rede de segurança para operações que tocam infraestrutura de produção, fazem commit permanente no histórico do git ou excluem dados.

Mantenha o CLAUDE.md do projeto no controle de versão. Um CLAUDE.md commitado na raiz do repositório se aplica consistentemente a sessões interativas, execuções de CI e ao agente local de qualquer membro da equipe. Este é o lugar certo para as regras que definem o que “correto” significa para sua base de código.

Use .claude/rules/ para conteúdo específico de domínio. Se o seu projeto tem camadas distintas — componentes frontend, API backend, esquema de banco de dados, scripts de infraestrutura — coloque as regras para cada camada em .claude/rules/ com escopo de caminho. Um único CLAUDE.md de 400 linhas com tudo dentro é mais difícil para o Claude navegar e custa mais contexto por sessão.

Mova material de referência para skills. Skills (.claude/skills/) são carregadas sob demanda, não no início da sessão. Documentação de API longa, procedimentos de implantação em várias etapas e playbooks de solução de problemas pertencem a skills que você invoca com /deploy ou /debug — não no CLAUDE.md, onde consomem contexto mesmo quando irrelevantes.

Revise a memória automática periodicamente. A memória automática se acumula ao longo do tempo. Comandos de build mudam, convenções são refatoradas, padrões de teste mudam. Uma nota de memória desatualizada que diz “use o cliente da API v1” quando você migrou para v2 causará bugs sutis em execuções autônomas. Audite ~/.claude/projects/<repo>/memory/ quando você fizer mudanças significativas na estrutura do projeto.

Usando Modelos de Código Aberto com Sua Configuração de Regras

O contexto CLAUDE.md e .claude/rules/ que você construiu funcionam da mesma forma, independentemente de qual modelo executa a inferência. Depois que suas regras são escritas, trocar de backend de modelo preserva tudo — e modelos de código aberto através da API LLM da Novita AI são uma opção prática para trabalho agente de alto volume.

A configuração é uma variável de ambiente:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<sua-chave-api-novita>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

Com ANTHROPIC_BASE_URL apontando para a Novita AI, o Claude Code envia todas as requisições de inferência para o endpoint compatível com Anthropic da Novita, em vez de api.anthropic.com. Seu CLAUDE.md, regras com escopo de caminho e settings.json se aplicam exatamente como antes — a camada de regras está a montante da seleção do modelo.

A Novita AI hospeda modelos de peso aberto focados em codificação, incluindo Qwen3-Coder, GLM-4.7, MiniMax M2.5 e DeepSeek V4. Esses modelos são otimizados para uso de ferramentas em várias etapas e chamada de funções, o que se alinha bem aos padrões de chamada de ferramentas que o Claude Code usa internamente para edições de arquivos, comandos de shell e navegação em repositórios.

Para equipes executando tarefas agênticas em escala — pipelines de revisão de código, refatoração automatizada em grandes repositórios, geração de testes — modelos de peso aberto na Novita geralmente custam significativamente menos por milhão de tokens do que alternativas de código fechado, enquanto ainda leem e aplicam suas regras de projeto de forma eficaz.

Se você estiver executando agentes em uma base de código de produção e quiser uma camada de segurança adicional além das regras deny, considere parear a API LLM da Novita com o Agent Sandbox da Novita. O sandbox fornece ao agente um ambiente Linux completo para operações de arquivos e execução de comandos, isolado do seu sistema host. O contexto do seu CLAUDE.md viaja com a tarefa; o risco de execução permanece contido.

FAQ

O que é CLAUDE.md no Claude Code?

CLAUDE.md é um arquivo markdown que fornece instruções persistentes ao Claude Code entre sessões. Ele é carregado no início da sessão para que o Claude não precise ser reensinado as convenções do seu projeto a cada vez. Você pode ter arquivos CLAUDE.md em vários escopos: nível de usuário (~/.claude/CLAUDE.md) para preferências pessoais que se aplicam em todos os lugares, nível de projeto (raiz do repositório) para regras compartilhadas pela equipe versionadas no controle de versão, e nível de subdiretório para regras específicas de módulo.

O que devo colocar nos arquivos de regras do Claude?

Escreva o que você reexplicaria a cada sessão: comandos de build e teste, convenções de codificação que diferem dos padrões do framework, restrições de arquitetura e pegadinhas conhecidas da base de código. Deixe de fora o conteúdo que o Claude pode derivar da própria base de código — árvores de arquivos, listas de dependências e descrições do que o código existente faz. Mantenha os arquivos com menos de 200 linhas para adesão consistente.

Qual é a diferença entre CLAUDE.md e settings.json no Claude Code?

CLAUDE.md são instruções que o Claude segue como orientação. settings.json é a configuração que o Claude Code impõe no nível do sistema. Uma regra no CLAUDE.md molda o que o Claude pretende fazer; uma entrada deny no settings.json bloqueia uma chamada de ferramenta incondicionalmente. Para qualquer coisa que não pode acontecer independentemente do que o Claude decidir — exclusões irreversíveis, force pushes, operações em ambiente de produção — use settings.json, não CLAUDE.md.

O que é o diretório .claude/rules/?

.claude/rules/ contém arquivos de regras com escopo de caminho que são carregados apenas quando o Claude está trabalhando com arquivos que correspondem ao escopo da regra. Isso permite que você escreva regras detalhadas e específicas de domínio sem carregá-las em todas as sessões. As regras são arquivos markdown com frontmatter YAML opcional especificando padrões glob paths. Regras sem frontmatter paths carregam incondicionalmente no início da sessão, como conteúdo adicional do CLAUDE.md.

O CLAUDE.md funciona em CI e tarefas automatizadas do Claude Code?

Sim. Qualquer invocação de claude -p, chamada do Agent SDK ou pipeline de CI executado em um diretório de repositório carrega o CLAUDE.md do projeto. Isso torna o CLAUDE.md eficaz para impor comportamento consistente tanto em contextos interativos quanto automatizados. Commitá-lo no controle de versão garante que toda execução — local e CI — comece com o mesmo contexto compartilhado.

Como funciona o contexto do Claude Code e como gerenciá-lo?

Contexto é o orçamento de tokens para a sessão atual. Arquivos CLAUDE.md, referências importadas, memória automática e o histórico da conversa contam para ele. Gerencie-o mantendo o CLAUDE.md conciso, usando .claude/rules/ para carregar conteúdo de domínio apenas quando relevante, e usando /compact para resumir sessões longas sem perder continuidade. Após /compact, o Claude relê o CLAUDE.md raiz do projeto do disco e o reinsere automaticamente na sessão.

Como usar as melhores práticas do Claude Code para codificação agente em uma equipe?

Commit o CLAUDE.md do projeto no seu repositório para que todos os membros da equipe e agentes de CI compartilhem as mesmas regras. Use .claude/rules/ com escopo de caminho para conteúdo específico de domínio. Adicione regras deny ao .claude/settings.json para operações que nunca devem ser executadas em contextos automatizados. Mantenha a memória automática fora da CI — ela é local da máquina e por desenvolvedor; o CLAUDE.md commitado é a fonte da verdade para comportamento compartilhado.

Novita AI é uma plataforma de nuvem de IA que oferece aos desenvolvedores uma maneira fácil de implantar modelos de IA usando nossa API simples, além de fornecer GPU em nuvem acessível e confiável para construir e escalar.

Artigos Recomendados

• Documentação do Claude Code CLI: Configuração, Comandos Slash e Integração com API LLM
• Claude Code SDK: Construa Agentes Autônomos com Python e TypeScript
• Construindo um Agente de Codificação com o Agent Sandbox da Novita

---

Fontes verificadas em 21 de julho de 2026: Documentação de memória do Claude Code, Visão geral de recursos do Claude Code, API LLM da Novita AI