Diretório de Regras do Claude Code

Problema: Um único CLAUDE.md está fazendo trabalho demais. Tem notas sobre React ao lado de convenções de API ao lado do seu padrão de testes, e cada sessão puxa tudo isso mesmo quando você está editando um arquivo de migração.

Ganho rápido: Crie seu primeiro arquivo de regra com foco:

mkdir -p .claude/rules
echo "# Testing Rules
- Run tests before committing
- Mock external services in unit tests" > .claude/rules/testing.md

Claude pega essa regra no início da sessão, junto com o CLAUDE.md, com as duas preocupações separadas de forma limpa.

O Que É o Diretório de Regras?

A partir da versão Claude Code v2.0.64, você tem outra opção para organizar instruções: o diretório .claude/rules/. Em vez de um único arquivo de memória enorme, você coloca vários arquivos markdown dentro, e Claude puxa cada um para a memória do projeto no início da sessão.

Detalhe importante da Anthropic: os arquivos dentro de .claude/rules/ carregam com a mesma prioridade alta que o CLAUDE.md. Isso importa, porque a janela de contexto do Claude não é plana. Fontes diferentes carregam pesos diferentes durante a geração.

Sem etapa de configuração. Qualquer arquivo .md dentro de .claude/rules/ vira parte do contexto do projeto automaticamente.

.claude/rules/
├── code-style.md      # Formatting and conventions
├── testing.md         # Test requirements
├── security.md        # Security checklist
└── frontend/
    ├── react.md       # React-specific patterns
    └── styles.md      # CSS conventions

Separação de responsabilidades, mas na camada de instruções. Edite suas regras de segurança sem mexer no arquivo de estilo, e vice-versa.

Regras por Caminho: O Recurso Poderoso

Aqui é onde o diretório se paga. Um arquivo de regra pode focar em padrões de arquivo específicos via frontmatter YAML:

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes: { error: string, code: number }
- Log all requests with correlation IDs

A regra só ativa quando Claude toca arquivos que combinam com src/api/**/*.ts. Edite um componente React e essas notas de API ficam em silêncio.

Múltiplos Padrões de Caminho

Um arquivo pode vigiar vários padrões ao mesmo tempo:

---
paths:
  - src/components/**/*.tsx
  - src/hooks/**/*.ts
---
 
# React Development Rules
 
- Use functional components exclusively
- Extract logic into custom hooks
- Memoize expensive computations

Padrões de Caminho Comuns

Por Que a Prioridade Importa: O Problema do CLAUDE.md Monolítico

Nem todo token no contexto do Claude tem o mesmo peso. As fontes são classificadas, e a Anthropic é clara: CLAUDE.md e os arquivos de regras ficam na prioridade alta. Claude trata ambos como orientação autoritativa.

Isso criava uma armadilha na forma antiga de trabalhar. Empilhar cada convenção em um CLAUDE.md gigante significava que tudo recebia tratamento elevado. Padrões de API brigavam por atenção com padrões de React, mesmo quando o trabalho era uma migração de banco de dados.

Alta prioridade em todo lugar = prioridade em lugar nenhum.

Marque tudo como importante e Claude não consegue mais distinguir o que realmente se aplica agora. As instruções perdem foco, o contexto fica barulhento, e o comportamento fica imprevisível.

A Hierarquia de Prioridade de Contexto

Um mapa rápido de como Claude pesa cada fonte:

O diretório de regras corrige o monólito ao distribuir a orientação de alta prioridade em arquivos de escopo restrito. Regras de API ficam na prioridade alta, mas apenas quando Claude está nos arquivos de API.

Alvo por Caminho = Escopo de Prioridade

Uma regra com uma entrada paths: só carrega, e só recebe atenção elevada, quando Claude está trabalhando em arquivos que combinam:

---
paths: src/api/**/*.ts
---
 
# These instructions get high priority ONLY during API work

Esse é o insight real. Você não está apenas organizando as coisas com cuidado. Você está escolhendo quando as instruções ganham peso extra.

Regras vs CLAUDE.md vs Skills

Qual deles assume qual trabalho?

CLAUDE.md guarda o que se aplica em todo lugar: lógica de roteamento, padrões de qualidade, protocolos de coordenação. Mantenha curto. Cada linha aqui compete pelo mesmo orçamento de alta prioridade.

Regras guardam o que se aplica a uma área: regras de API para arquivos de API, regras de teste para arquivos de teste. O alvo por caminho mantém essa alta prioridade no momento certo.

Skills guardam o que se aplica entre projetos: playbooks de deploy, checklists de revisão, guias de marca. Ficam quietas com prioridade menor até algo as acionar.

Exemplos Práticos

Regras de Segurança para Diretórios Sensíveis

---
paths:
  - src/auth/**/*
  - src/payments/**/*
---
 
# Security-Critical Code Rules
 
- Never log sensitive data (passwords, tokens, card numbers)
- Validate all inputs at function boundaries
- Use parameterized queries exclusively
- Require explicit authorization checks before data access

Padrões para Arquivos de Teste

---
paths: **/*.test.ts
---
 
# Test Writing Standards
 
- Use descriptive test names: "should [action] when [condition]"
- One assertion per test when possible
- Mock external dependencies, never real APIs
- Include edge cases: empty inputs, null values, boundaries

Regras de Migração de Banco de Dados

---
paths: prisma/migrations/**/*
---
 
# Migration Safety Rules
 
- Always include rollback instructions
- Test migrations on a copy of production data first
- Never delete columns in the same migration that removes code using them
- Add columns as nullable first, populate, then add constraints

Migração do CLAUDE.md Monolítico

Um CLAUDE.md inflado é geralmente sintoma de saturação de prioridade. Tudo está marcado como importante, então nada é. A correção é tirar seções específicas de domínio e colocar cada uma em uma regra com alvo por caminho:

Antes (único CLAUDE.md com 400 linhas):

# Project Context
 
...
 
## API Guidelines
 
- Validate inputs with Zod
- Return consistent errors
  ...
 
## React Patterns
 
- Use functional components
- Extract hooks
  ...
 
## Testing Rules
 
- Mock external services
  ...

Depois (CLAUDE.md enxuto + regras modulares):

# CLAUDE.md - Operational Core Only
 
## Routing Logic
 
- Simple tasks: execute directly
- Complex tasks: delegate to sub-agents
 
## Quality Standards
 
- Correctness > Maintainability > Performance

.claude/rules/
├── api-guidelines.md      # API section with paths: src/api/**/*
├── react-patterns.md      # React section with paths: src/components/**/*
└── testing-rules.md       # Testing section with paths: **/*.test.*

CLAUDE.md mantém o foco em como você opera. O conhecimento de domínio vai para regras com alvo que só ganham prioridade alta quando os arquivos ativos combinam.

Saturação de prioridade é o que você está resolvendo de verdade. A orientação operacional central está sempre ativa. Regras de domínio só levantam a voz quando Claude está editando arquivos na sua faixa. Em todo o resto, silêncio.

Regras em Nível de Usuário: Padrões Pessoais em Todos os Projetos

Regras de projeto não são a única camada. Regras pessoais que te acompanham em todos os projetos ficam em ~/.claude/rules/:

~/.claude/rules/
├── preferences.md     # Your personal coding preferences
├── workflows.md       # Your preferred workflows
└── shortcuts.md       # Custom patterns you always want

Regras do usuário carregam primeiro, depois as regras do projeto chegam por cima. Seus padrões pessoais viajam com você, mas qualquer projeto ainda pode sobrescrevê-los quando precisar.

Útil para qualquer coisa que reflita como você trabalha: estilo de indentação, formato de mensagem de commit, padrões de teste favoritos, pequenos hábitos que você quer sempre, independentemente do codebase.

Expansão de Chaves em Padrões de Caminho

Padrões de caminho suportam expansão de chaves, então uma entrada pode cobrir várias extensões ou diretórios de uma vez:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---
 
# TypeScript/React Rules
 
- Use strict TypeScript
- Prefer interfaces over type aliases for public APIs

{ts,tsx} inclui tanto .ts quanto .tsx. {src,lib} cobre tanto src/ quanto lib/. Seu frontmatter fica compacto quando uma regra abrange tipos de arquivo ou pastas relacionados.

Symlinks: Compartilhando Regras Entre Projetos

Symlinks funcionam dentro de .claude/rules/, o que permite manter uma fonte canônica de regras e compartilhá-la entre repositórios:

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared
 
# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

Arquivos vinculados resolvem e carregam da mesma forma que arquivos locais. Symlinks circulares são detectados e tratados, então você não precisa se preocupar com loop infinito.

Bom para equipes que compartilham padrões de código entre projetos. Mantenha o repositório canônico de regras em um lugar. Faça symlink em todos os projetos que precisarem.

Descoberta Recursiva em Subdiretórios

Subdiretórios são bem-vindos. Todo arquivo .md na árvore é capturado:

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

Aninhado ou plano, o carregador percorre o diretório inteiro. Agrupe arquivos relacionados como quiser sem perder a descobribilidade.

Boas Práticas

Mantenha regras focadas: uma preocupação por arquivo. Segurança em um lugar, estilo em outro.

Use nomes de arquivo descritivos: api-validation.md vale mais que rules1.md.

Aposte no alvo por caminho: regras sem paths: carregam em todo lugar. Adicione um padrão no momento em que uma regra começar a vazar para trabalhos não relacionados.

Versione tudo: regras são código. Revise em PRs, acompanhe o histórico, reverta as que deram errado.

Documente o propósito da regra: abra cada arquivo com uma linha explicando quando ele deve se aplicar.

Próximos Passos

1. Audite seu CLAUDE.md: sinalize seções que realmente só se aplicam a certos tipos de arquivo
2. Extraia uma regra: tire o bloco mais específico de domínio para .claude/rules/
3. Adicione alvo por caminho: aponte essa regra para os arquivos que ela realmente serve
4. Itere: sempre que Claude carregar contexto que você não precisava, extraia outra regra

Para a arquitetura de memória mais ampla e por que um único arquivo gigante causa problemas, veja CLAUDE.md Mastery. Para como a prioridade se encaixa em uma estratégia de contexto mais ampla, leia sobre gerenciamento de contexto e otimização de memória.

Lembre-se: o objetivo é entregar ao Claude exatamente a orientação de alta prioridade que combina com os arquivos na tela. Nada mais. Atenção onde importa, silêncio em todo o resto. Combine isso com uma arquitetura de skills que carrega conhecimento de domínio sob demanda, e sua janela de contexto fica enxuta enquanto suas instruções mantêm o peso.