🏗️ Project Overview
A primeira secao do CLAUDE.md e o Project Overview - uma descricao concisa do que o projeto faz, para quem serve e qual problema resolve. Essa secao da ao Claude o contexto de alto nivel necessario para tomar decisoes alinhadas com o proposito do projeto.
💡 Conceito Principal
O Project Overview deve ser curto (3-5 linhas) mas informativo. Inclua o tipo de aplicacao, o publico-alvo e o objetivo principal.
# Project Overview
Este e um SaaS de gerenciamento de tarefas para equipes
remotas. O app permite criar projetos, atribuir tarefas e
acompanhar o progresso em tempo real via dashboard.
- •Descreva O QUE o projeto faz em 1-2 frases
- •Mencione o publico-alvo ou usuarios principais
- •Inclua o contexto de negocio quando relevante
⚡ Dica Pratica
Escreva o overview como se estivesse explicando o projeto para um dev senior no primeiro dia de trabalho. Seja direto e evite jargoes internos que o Claude nao entenderia.
⚙️ Tech Stack
A secao Tech Stack lista todas as tecnologias, frameworks e ferramentas usadas no projeto. Isso e crucial para que o Claude gere codigo compativel com as dependencias reais do projeto, em vez de sugerir alternativas que voce nao usa.
💡 Conceito Principal
Liste as tecnologias de forma organizada, separando frontend, backend, banco de dados e ferramentas de infraestrutura. Inclua versoes quando relevante.
# Tech Stack
- Frontend: Next.js 14 (App Router), React 18, TypeScript
- Styling: Tailwind CSS v3
- Backend: Next.js API Routes + Server Actions
- Database: PostgreSQL via Prisma ORM
- Auth: NextAuth.js v5
- Deploy: Vercel
- •Especifique versoes maiores para evitar codigo incompativel
- •Mencione ORMs e bibliotecas de autenticacao explicitamente
- •Inclua o gerenciador de pacotes (npm, pnpm, yarn, uv)
⚡ Dica Pratica
Se voce usa Next.js com App Router, especifique isso claramente. O Claude pode gerar codigo para Pages Router se nao souber. O mesmo vale para React Server Components vs Client Components.
🖥️ Commands
A secao Commands documenta os comandos essenciais do projeto: como instalar dependencias, rodar o servidor de desenvolvimento, executar testes e fazer build. Essa e uma das secoes mais uteis porque permite ao Claude executar comandos corretamente.
💡 Conceito Principal
Liste cada comando com uma descricao breve do que ele faz. Inclua comandos para rodar um unico teste, pois o Claude frequentemente precisa validar suas alteracoes.
# Commands
- `npm install` - instalar dependencias
- `npm run dev` - servidor de desenvolvimento
- `npm run build` - build de producao
- `npm test` - rodar todos os testes
- `npm test -- --testPathPattern="nome"` - rodar um teste especifico
- `npm run lint` - verificar linting
- •Inclua o comando para rodar um unico teste (muito importante!)
- •Documente variaveis de ambiente necessarias para cada comando
- •Adicione comandos de migracao de banco de dados se aplicavel
⚡ Dica Pratica
O comando para rodar um unico teste e o mais importante. O Claude usa isso para validar cada alteracao que faz. Se esse comando estiver errado, o Claude vai ficar preso em loops de erro.
📐 Code Conventions
A secao Code Conventions define os padroes de codigo que o projeto segue. Isso inclui estilo de nomenclatura, organizacao de arquivos, padroes de importacao e qualquer regra especifica que a equipe adota.
💡 Conceito Principal
Seja especifico nas convencoes. Quanto mais claro, menos o Claude vai desviar dos seus padroes. Foque nas convencoes que sao unicas do seu projeto.
# Code Conventions
- Use TypeScript strict mode em todo codigo novo
- Componentes React: function declarations, nao arrow functions
- Nomes de arquivos: kebab-case (user-profile.tsx)
- Imports: absolutos com alias @ para src/
- Testes: colocate com o arquivo (component.test.tsx)
- Tratamento de erros: sempre use try/catch em Server Actions
- •Defina padroes de nomenclatura (arquivos, variaveis, componentes)
- •Especifique padroes de tratamento de erros
- •Documente a estrutura de pastas esperada
⚡ Dica Pratica
Nao liste convencoes obvias (como "use camelCase em JavaScript"). Foque nas decisoes que sao especificas do seu projeto e que o Claude nao conseguiria adivinhar sozinho.
🚫 Things To Avoid
A secao Things To Avoid e tao importante quanto as convencoes positivas. Aqui voce lista explicacitamente o que o Claude NAO deve fazer. Essa secao previne erros recorrentes e padroes indesejados.
💡 Conceito Principal
As proibicoes sao poderosas porque eliminam categorias inteiras de erros. O Claude respeita muito bem instrucoes negativas quando sao claras e diretas.
# Things To Avoid
- NUNCA use `any` em TypeScript - sempre defina tipos
- NAO use CSS inline ou styled-components (use Tailwind)
- NAO crie arquivos na raiz do projeto
- EVITE useEffect para data fetching (use Server Components)
- NAO commite arquivos .env ou secrets
- NUNCA altere arquivos de migracao ja aplicados
- •Use linguagem forte: NUNCA, NAO, EVITE
- •Explique a alternativa correta quando possivel
- •Adicione itens conforme descobrir erros recorrentes do Claude
⚡ Dica Pratica
Toda vez que voce corrigir o Claude dizendo "nao faca isso", adicione essa regra na secao Things To Avoid. Com o tempo, essa lista se torna um filtro poderoso contra erros.
📎 Additional Context
A secao Additional Context e o espaco para qualquer informacao extra que nao se encaixa nas outras secoes. Aqui voce pode incluir decisoes arquiteturais, links uteis, workflows especificos ou notas sobre areas sensiveis do codigo.
💡 Conceito Principal
Use essa secao para comunicar o "por que" das decisoes, nao apenas o "o que". Quando o Claude entende as razoes, ele toma decisoes melhores em situacoes novas.
# Additional Context
- Estamos migrando de Pages Router para App Router
(novos arquivos devem usar App Router)
- O sistema de pagamentos usa Stripe e nao deve ser alterado
sem aprovacao explicita
- O arquivo lib/legacy.ts esta deprecated, nao adicionar
novas funcoes la
- Usamos feature flags via LaunchDarkly para releases graduais
- •Documente migracoes em andamento e seus estados
- •Marque areas criticas que precisam de cuidado extra
- •Inclua decisoes arquiteturais e suas justificativas
⚡ Dica Pratica
Mantenha o CLAUDE.md conciso e relevante. Se uma secao de contexto adicional ficar muito longa, considere criar um CLAUDE.md separado no subdiretorio relevante.
📋 Resumo do Modulo
Proximo Modulo:
2.3 - Escopos: Projeto, Subdiretorio e Global