Domínio 3 — Claude Code Configuration & Workflows · Lição 1 de 6

CLAUDE.md: hierarquia, @import e rules com paths

Objetivos de aprendizagem

• Descrever a hierarquia de arquivos CLAUDE.md: nível de usuário, nível de projeto e nível de subdiretório (task statement 3.1).
• Diagnosticar o problema clássico "a instrução funciona para mim, mas não para o colega novo" — instrução no nível de usuário em vez de projeto.
• Modularizar um CLAUDE.md grande com @import e com arquivos de regra em .claude/rules/.
• Aplicar regras condicionais por caminho com frontmatter paths: (globs) e saber quando elas vencem um CLAUDE.md de subdiretório (task statement 3.3).
• Usar /memory para verificar quais arquivos de memória estão carregados e diagnosticar comportamento inconsistente entre sessões.

Por que CLAUDE.md existe

O Claude Code lê automaticamente arquivos CLAUDE.md no início da sessão e os injeta no contexto como "memória" persistente do projeto: convenções de código, comandos de build e teste, arquitetura, o que não tocar. Diferente de um prompt digitado, o conteúdo de CLAUDE.md é sempre carregado — por isso ele deve conter apenas o que vale para (quase) toda interação. Instruções raramente usadas gastam tokens em todas as sessões; a prova cobra saber quando mover conteúdo para mecanismos sob demanda (skills, lição 3) ou condicionais (.claude/rules/ com paths:, nesta lição).

A hierarquia de três níveis

flowchart TD
    U["~/.claude/CLAUDE.md
(usuário — pessoal, fora do git)"] --> S["Contexto da sessão"]
    P["CLAUDE.md na raiz do projeto
(ou .claude/CLAUDE.md — versionado)"] --> S
    D["packages/api/CLAUDE.md
(subdiretório — carregado ao tocar nessa árvore)"] --> S
    R[".claude/rules/*.md com paths: [globs]
(condicional por arquivo editado)"] --> S
  

Os níveis são combinados, não mutuamente exclusivos: instruções de usuário, de projeto e de subdiretório entram juntas no contexto. Quanto mais específico o nível, mais próximo do trabalho atual ele está — instruções de subdiretório detalham (e na prática refinam) as do projeto para aquela área do código.

O diagnóstico clássico: "não funciona para o colega novo"

Cenário recorrente na prova: você adicionou uma instrução ("sempre rode npm run lint após editar") e o Claude Code obedece na sua máquina. Um colega novo clona o repositório e a instrução é ignorada. Causa mais provável: a instrução está em ~/.claude/CLAUDE.md (nível de usuário), que não é versionado e portanto não chega a ninguém via git clone/git pull. A correção é mover a instrução para o CLAUDE.md do projeto (raiz ou .claude/CLAUDE.md), que viaja com o repositório.

Diagnóstico com /memory

O comando /memory mostra quais arquivos de memória estão carregados na sessão atual e permite editá-los. É a primeira ferramenta de diagnóstico quando o comportamento varia entre sessões ou entre máquinas: se o arquivo esperado não aparece na lista, ele não está sendo carregado (caminho errado, nível errado, arquivo não clonado). Na prova, "usar /memory para verificar o que está carregado" é a resposta proporcional antes de reescrever instruções ou suspeitar do modelo.

Modularização com @import

Um CLAUDE.md monolítico de centenas de linhas é difícil de manter e mistura assuntos. A sintaxe @caminho/arquivo.md importa o conteúdo de outro arquivo para a memória, permitindo compor a memória a partir de arquivos focados — inclusive reaproveitando documentos que já existem no repositório:

# CLAUDE.md (raiz do projeto)

## Visão geral
Monorepo com apps/web (Next.js) e packages/api (Fastify).

## Padrões compartilhados
@docs/padroes-de-codigo.md
@docs/convencoes-de-teste.md

## Específico do pacote api
Ver packages/api/CLAUDE.md, que importa apenas os padrões
relevantes àquele pacote (ex.: @../../docs/padroes-http.md).

O padrão cobrado no exame: em um monorepo, cada pacote mantém um CLAUDE.md enxuto que importa seletivamente os arquivos de padrões relevantes àquele pacote, com base no conhecimento de domínio dos mantenedores — em vez de todo pacote carregar todos os padrões do repositório.

.claude/rules/ e regras condicionais com paths

A alternativa ao CLAUDE.md monolítico é o diretório .claude/rules/: arquivos Markdown focados por tópico (testing.md, api-conventions.md, deployment.md). Um arquivo de regra pode ter frontmatter YAML com o campo paths: contendo globs — a regra só é carregada quando o Claude edita arquivos que casam com o padrão, reduzindo contexto irrelevante e uso de tokens:

---
paths:
  - "**/*.test.tsx"
  - "**/*.test.ts"
---
# Convenções de teste

- Use React Testing Library; nunca teste detalhes de implementação.
- Todo teste novo deve cobrir o caso de erro além do caminho feliz.
- Rode `npm run test -- --changed` antes de finalizar.

---
paths:
  - "terraform/**/*"
---
# Convenções de infraestrutura

- Nunca aplique mudanças; apenas gere o plano (`terraform plan`).
- Todo recurso precisa de tags `team` e `cost-center`.

paths: vs CLAUDE.md de subdiretório — quando cada um vence

Um CLAUDE.md de subdiretório é preso ao diretório: cobre packages/api/ e pronto. Ele funciona bem quando a convenção coincide com uma árvore de pastas. Mas quando a convenção se aplica a arquivos espalhados pelo repositório — o caso típico são testes colocalizados (Button.test.tsx ao lado de Button.tsx, em dezenas de pastas) — você precisaria de um CLAUDE.md em cada pasta. A regra com glob (**/*.test.tsx) cobre todos eles com um único arquivo, independentemente da localização. Este é um distrator recorrente na prova: a resposta certa para "testes espalhados pelo codebase" é .claude/rules/ com paths:, não múltiplos CLAUDE.md.

Pegadinhas da prova

• Distrator típico: "coloque a instrução do time em ~/.claude/CLAUDE.md". Errado: nível de usuário não é compartilhado via git — colegas nunca recebem a instrução.
• Distrator típico: "consolide tudo no CLAUDE.md raiz com um cabeçalho por área e deixe o Claude inferir qual seção usar". Inferência é probabilística; regras com paths: dão correspondência explícita e determinística por arquivo.
• Distrator típico: "crie um CLAUDE.md em cada subdiretório para os testes". Inviável quando os arquivos estão espalhados — glob em .claude/rules/ cobre todos com um arquivo.
• Distrator típico: "use uma skill para convenções que devem ser aplicadas automaticamente". Skills são sob demanda; para aplicação automática baseada em caminho, o mecanismo é .claude/rules/ com paths:.
• Distrator típico: diagnosticar comportamento inconsistente reescrevendo o prompt antes de rodar /memory para conferir o que de fato está carregado.

Resumo em 5 linhas

Documentação oficial

• Manage Claude's memory (CLAUDE.md e rules)
• Claude Code settings

Questões de fixação