Compreendendo a estrutura de pastas .claude/ para configuração do Claude Code

Pastas de configuração do projeto e global

Existem dois diretórios .claude: um na raiz do seu projeto para configuração da equipe que é commitado no git, e outro no seu diretório pessoal (~/.claude/) para preferências pessoais e estado local da máquina, como histórico de sessões.

CLAUDE.md: O manual de instruções

O CLAUDE.md é carregado no prompt do sistema do Claude no início de cada sessão e seguido durante toda a conversa. Você pode ter o CLAUDE.md na raiz do projeto, em ~/.claude/ para preferências globais ou em subdiretórios para regras específicas de pastas.

Conteúdo eficaz do CLAUDE.md inclui:

• Comandos de build, teste e lint (npm run test, make build, etc.)
• Decisões arquiteturais importantes
• Armadilhas não óbvias
• Convenções de importação, padrões de nomenclatura, estilos de tratamento de erros
• Estrutura de arquivos e pastas para os módulos principais

Mantenha o CLAUDE.md com menos de 200 linhas. Arquivos maiores que isso começam a consumir muito contexto e a aderência do Claude às instruções diminui.

Exemplo de estrutura do CLAUDE.md

# Projeto: Acme API

Comandos
npm run dev # Iniciar servidor de desenvolvimento
npm run test # Executar testes (Jest)
npm run lint # Verificação ESLint + Prettier
npm run build # Build de produção

Arquitetura

• API REST Express, Node 20
• PostgreSQL via Prisma ORM
• Todos os handlers ficam em src/handlers/
• Tipos compartilhados em src/types/

Convenções

• Use zod para validação de requisições em cada handler
• O formato de retorno é sempre { data, error }
• Nunca exponha stack traces ao cliente
• Use o módulo logger, não console.log

Atenção para

• Os testes usam um banco de dados local real, não mocks. Execute npm run db:test:reset primeiro
• TypeScript estrito: sem imports não utilizados, nunca

  Substituições pessoais com CLAUDE.local.md

  Crie o CLAUDE.local.md na raiz do seu projeto para preferências pessoais que não se aplicam a toda a equipe. O Claude o lê junto com o CLAUDE.md principal, e ele é automaticamente ignorado pelo git para que ajustes pessoais nunca entrem no repositório.

  Instruções modulares com a pasta rules/

  Para equipes maiores, a pasta rules/ fornece instruções modulares que escalam melhor do que um único arquivo CLAUDE.md grande.

  📖 Leia a fonte completa: HN AI Agents