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