📝 Secao Project Overview
A primeira secao do CLAUDE.md e a mais importante: o Project Overview. Em 2-3 frases, voce explica o que o projeto faz, qual o dominio e qual a stack principal. O Claude usa isso como ancoragem para todas as decisoes subsequentes.
🎯 Conceito Principal
O Project Overview responde tres perguntas: O que e?, Para quem? e Com que tecnologia?. Mantenha curto e direto.
This is SaaSify, a B2B subscription management platform.
Built with Next.js 14 (App Router), TypeScript, and Supabase.
Target users: SaaS companies managing recurring billing.
- •Seja especifico: "B2B subscription platform" e melhor que "aplicacao web"
- •Inclua o stack principal: O Claude ajusta suas sugestoes baseado na stack declarada
- •Maximo 3 frases: Nao e README. E contexto rapido
💡 Dica Pratica
Escreva o Project Overview como se estivesse respondendo a pergunta "O que voce ta construindo?" para um colega senior em uma frase. Se precisa de mais de 3 frases, voce esta incluindo detalhes demais.
⚙️ Secao Tech Stack e Commands
A secao de Tech Stack e Commands e onde voce declara as tecnologias do projeto e os comandos que o Claude deve usar. Isso e crucial porque o Claude frequentemente precisa rodar comandos e precisa saber qual package manager e quais scripts usar.
🎯 Conceito Principal
Liste sua stack como bullet points e seus comandos como pares chave-valor. O Claude usa isso para saber qual ferramenta usar em cada situacao.
- Language: TypeScript (strict mode)
- Framework: Next.js 14 with App Router
- Database: Supabase (PostgreSQL)
- Styling: Tailwind CSS + shadcn/ui
- Testing: Vitest + Playwright
- Package Manager: pnpm
## Commands
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- E2E: pnpm test:e2e
- Lint: pnpm lint
- Type check: npx tsc --noEmit
- •Package Manager explicitamente: Sem isso, o Claude pode usar npm quando voce usa pnpm
- •Todos os comandos importantes: Dev, build, test, lint, type check. O Claude usa esses comandos frequentemente
- •Versoes especificas quando relevante: "Next.js 14 with App Router" e muito mais util que apenas "Next.js"
💡 Dica Pratica
O erro mais comum e esquecer o package manager. Se voce usa pnpm e nao declara, o Claude vai rodar npm install e criar um package-lock.json indesejado no seu projeto. Sempre declare explicitamente.
📐 Secao Code Conventions
A secao de Code Conventions define como o codigo deve ser escrito. E aqui que voce evita que o Claude gere codigo que "funciona mas nao e do jeito certo" para o seu projeto.
🎯 Conceito Principal
Documente apenas as convencoes que sao especificas do seu projeto. Nao precisa dizer "use camelCase em JavaScript". Foque no que e unico.
- Use Server Components by default, Client Components only when needed
- Named exports for all components (never default export)
- File naming: kebab-case for files, PascalCase for components
- Colocate tests next to source files as *.test.ts
- Use Zod for all input validation
- Prefer composition over inheritance
- All API responses follow { data, error, meta } pattern
- •Exports: Named vs default e uma das maiores fontes de inconsistencia. Declare explicitamente
- •Naming: kebab-case, camelCase, PascalCase para cada contexto
- •Patterns: Padroes de resposta de API, tratamento de erros, validacao
💡 Dica Pratica
Revise os ultimos 5 PRs que voce fez correcoes de estilo. Cada correcao que voce fez e uma convencao que deveria estar no CLAUDE.md. Se voce corrigiu "use named export" 3 vezes, adicione essa regra.
🔗 Secao Important Patterns
A secao de Important Patterns documenta os padroes arquiteturais do projeto. Tratamento de erros, gerenciamento de estado, autenticacao, chamadas de API. Esses padroes sao o que separa codigo que "funciona" de codigo que "se encaixa" no projeto.
🎯 Conceito Principal
Padroes arquiteturais sao decisoes que afetam multiplos arquivos e funcionalidades. O Claude precisa conhece-los para gerar codigo consistente.
- Error handling: Use Result<T, E> pattern, never throw in business logic
- State management: Zustand for client state, React Query for server state
- API calls: Always through src/lib/api.ts, never fetch directly
- Authentication: Supabase Auth with JWT, middleware checks in middleware.ts
- Database queries: Always through repository pattern in src/repositories/
💡 Dica Pratica
Se voce tem um pattern de error handling especifico, escreva um mini-exemplo no CLAUDE.md. O Claude aprende muito melhor com exemplos concretos do que com descricoes abstratas. Mostre o "antes ruim" e o "depois certo".
🚫 Secao Things To Avoid
A secao Things To Avoid e tao poderosa quanto as regras positivas. Dizer ao Claude o que NAO fazer previne erros comuns antes que eles acontecam. Essa secao funciona como guardrails automaticos.
🎯 Conceito Principal
Regras negativas sao mais faceis de seguir do que regras positivas. "Nunca use any" e mais claro do que "sempre use types adequados". Use linguagem direta e imperativa.
- Never use "any" type — use "unknown" and narrow
- Don't use the Pages Router — App Router only
- Never commit .env files
- Don't install new dependencies without discussing first
- Never use console.log in production code — use the logger
- Don't create files outside the src/ directory
- •Use "Never" e "Don't": Linguagem forte e inequivoca funciona melhor com LLMs
- •Explique brevemente o motivo: "Never use any — use unknown and narrow" e melhor que apenas "Never use any"
💡 Dica Pratica
Cada bug que voce encontrou porque o Claude fez algo errado e um candidato para Things To Avoid. Mantenha um log mental e atualize essa secao regularmente. Depois de 2 semanas de uso, essa lista se torna ouro puro.
📋 Template Completo Pronto para Copiar
Aqui esta o template completo que voce pode copiar e adaptar para qualquer projeto. Cada secao tem placeholders explicativos que voce substitui com as informacoes do seu projeto.
🎯 Conceito Principal
Este template cobre 95% dos casos de uso. Copie, substitua os placeholders e pronto. Voce tera um CLAUDE.md funcional em menos de 10 minutos.
## Project Overview
This is [PROJECT NAME], a [brief description].
Built with [primary tech stack].
## Tech Stack
- Language: [e.g., TypeScript, Python, Go]
- Framework: [e.g., Next.js, FastAPI, Express]
- Database: [e.g., PostgreSQL, MongoDB, Supabase]
- Styling: [e.g., Tailwind CSS, styled-components]
- Testing: [e.g., Jest, Pytest, Vitest]
- Package Manager: [e.g., npm, pnpm, bun, uv]
## Project Structure
- src/ — Main application source code
- src/components/ — Reusable UI components
- src/lib/ — Utility functions and shared logic
- tests/ — Test files
## Commands
- Dev server: [command]
- Build: [command]
- Test: [command]
- Lint: [command]
## Code Conventions
- [Your convention 1]
- [Your convention 2]
- [Your convention 3]
## Important Patterns
- Error handling: [describe]
- State management: [describe]
- API calls: [describe]
## Things To Avoid
- Never [thing 1]
- Don't [thing 2]
- Avoid [thing 3]
💡 Dica Pratica
Comece com esse template e va refinando ao longo do tempo. A primeira versao nao precisa ser perfeita. O importante e ter algo que o Claude possa ler. Voce vai iterar e melhorar naturalmente conforme usa.
Exercicio Pratico
Exercicio: Criar CLAUDE.md Completo para um Projeto Pessoal
Tempo estimado: 15-20 minutos
Escolha um projeto ativo
Selecione um projeto real que voce esta trabalhando atualmente.
Copie o template
Use o template completo do Topico 6 como base.
Preencha todas as secoes
Substitua cada placeholder com informacoes reais do seu projeto. Nao pule nenhuma secao.
Teste com o Claude Code
Abra o Claude Code no projeto e pergunte: "Quais instrucoes voce tem sobre este projeto?" Verifique se ele listou tudo corretamente.
📋 Resumo do Modulo
Proximo Modulo:
2.3 - Escopos e Hierarquia de Memoria