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 APIComandos
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:resetprimeiro - 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
👀 See Also
Arquitetura Multi-Agente: Evitando a Armadilha do Agente Único em Sistemas de IA
Uma publicação no Reddit identifica o erro arquitetural comum de usar um único agente para múltiplas tarefas, o que leva a sistemas frágeis que exigem monitoramento constante. A solução proposta é um modelo de orquestrador-especialista, onde cada agente tem uma função específica e limitada.
Otimizando o Qwen3.5-9B no RTX 3070 Mobile com ik_llama.cpp: Ajustes de Configuração e Benchmarks
Um desenvolvedor compartilha descobertas de otimização para executar Qwen3.5-9B Q4_K_M em uma GPU RTX 3070 Mobile 8GB usando ik_llama.cpp, alcançando velocidade de geração de ~50 tokens/segundo e melhorias significativas na avaliação de prompts através de ajustes de configuração.
Subagentes OpenClaw: Não Trate uma Resposta como Confirmação de Conclusão
O sessions_spawn do OpenClaw é não bloqueante — ele retorna um runId quando o trabalho é aceito, não concluído. Um pai pode reportar sucesso prematuramente enquanto um filho ainda está em execução, falhou ou se perdeu.
Benchmarks de 12GB VRAM: Executando Modelos Qwen 3.6 e Gemma 4 em uma RTX 4070 Super
Um usuário do Reddit compartilha benchmarks detalhados de velocidade para Qwen3.6-35B-A3B, Qwen3.6-27B, Gemma 4 26B e Gemma 4 31B em uma RTX 4070 Super de 12 GB usando llama.cpp com configurações otimizadas.