🏗️ Project Overview do SaaS
Vamos construir um CLAUDE.md completo para um SaaS de gerenciamento de projetos feito com Next.js. Comecamos pelo overview que situa o Claude no contexto do negocio e da aplicacao.
💡 Exemplo Completo
# Project Overview
TaskFlow is a B2B SaaS project management tool for remote teams.
The app provides real-time Kanban boards, time tracking, sprint
planning, and team analytics. We serve 500+ companies and handle
~10k concurrent users.
Key features: workspace management, role-based access control,
real-time collaboration via WebSockets, Stripe billing integration,
and a REST + GraphQL API for third-party integrations.
⚡ Dica Pratica
Mencione metricas reais (usuarios, escala) quando possivel. Isso ajuda o Claude a tomar decisoes de performance adequadas. Um app com 10k usuarios concorrentes precisa de solucoes diferentes de um app com 100.
⚙️ Tech Stack Detalhada
A tech stack de um SaaS Next.js tipico inclui muitas pecas. Listar cada uma com a versao especifica evita que o Claude sugira APIs deprecated ou padroes incompativeis.
💡 Exemplo Completo
# Tech Stack
- Framework: Next.js 14 (App Router ONLY - no Pages Router)
- Language: TypeScript 5.3 (strict mode)
- React: v18 with Server Components by default
- Styling: Tailwind CSS v3 + shadcn/ui components
- Database: PostgreSQL 15 via Prisma ORM v5
- Auth: NextAuth.js v5 (Auth.js) with JWT strategy
- State: Zustand for client state, React Query for server state
- Real-time: Socket.io for WebSocket connections
- Payments: Stripe SDK with webhook handling
- Email: Resend + React Email templates
- Testing: Vitest + React Testing Library + Playwright
- Package Manager: pnpm
- Deploy: Vercel (production) + Railway (database)
⚡ Dica Pratica
Note o detalhe "App Router ONLY - no Pages Router". Sem essa especificacao, o Claude poderia gerar codigo usando getServerSideProps em vez de Server Components. Seja explicito nas escolhas arquiteturais.
🖥️ Comandos do Projeto
Os comandos do projeto Next.js incluem desenvolvimento, build, testes e banco de dados. Note como o comando de teste individual e documentado - isso e essencial para o Claude validar suas alteracoes.
💡 Exemplo Completo
# Commands
- `pnpm install` - install all dependencies
- `pnpm dev` - start dev server (http://localhost:3000)
- `pnpm build` - production build
- `pnpm test` - run all unit tests with Vitest
- `pnpm test -- --run src/path/to/file.test.ts` - run single test file
- `pnpm test:e2e` - run Playwright E2E tests
- `pnpm lint` - ESLint check
- `pnpm type-check` - TypeScript type checking
- `pnpm db:push` - push Prisma schema to database
- `pnpm db:migrate` - create and run migration
- `pnpm db:seed` - seed database with test data
- `pnpm db:studio` - open Prisma Studio GUI
⚡ Dica Pratica
O Claude Code pode rodar esses comandos diretamente. Se voce documentar pnpm test -- --run src/path/to/file.test.ts, o Claude sabera exatamente como rodar o teste do arquivo que ele acabou de modificar.
📐 Convencoes do Projeto
As convencoes de codigo de um SaaS Next.js cobrem desde a estrutura de componentes ate padroes de API e tratamento de erros. Veja um exemplo completo e realista.
💡 Exemplo Completo
# Code Conventions
## Components
- Use Server Components by default, add "use client" only when needed
- Component files: PascalCase (UserProfile.tsx)
- Use function declarations, not arrow functions for components
- Props interface named: ComponentNameProps
- Colocate styles, tests, and types with components
## Data Fetching
- Server Components: fetch data directly in the component
- Client Components: use React Query with custom hooks
- All API calls go through src/lib/api/ service files
## File Structure
- src/app/ - Next.js App Router pages and layouts
- src/components/ - reusable UI components
- src/lib/ - utilities, helpers, configurations
- src/hooks/ - custom React hooks
- src/types/ - shared TypeScript types
- prisma/ - database schema and migrations
⚡ Dica Pratica
A convencao "Server Components by default" e crucial. Sem ela, o Claude tende a adicionar "use client" em tudo. Especifique claramente quando cada tipo deve ser usado.
🚫 O que Evitar no Next.js SaaS
A lista de "Things To Avoid" de um projeto Next.js e particularmente importante porque existem muitos padroes antigos que o Claude pode sugerir se nao for explicitamente instruido a evita-los.
💡 Exemplo Completo
# Things To Avoid
- NEVER use Pages Router patterns (getServerSideProps, getStaticProps)
- NEVER use `any` type - define proper TypeScript interfaces
- DO NOT use CSS Modules or styled-components (Tailwind only)
- DO NOT use useEffect for data fetching in components that
could be Server Components
- NEVER modify migration files that have already been applied
- DO NOT store secrets in code - use environment variables
- AVOID creating API routes for things that can be Server Actions
- DO NOT use default exports except for pages/layouts (Next.js req)
- NEVER directly access process.env in client components
- DO NOT add dependencies without discussing first
⚡ Dica Pratica
A regra "AVOID creating API routes for things that can be Server Actions" e especialmente importante com Next.js 14. O Claude tende a criar API routes por habito, mas Server Actions sao mais simples para mutacoes.
🧪 Contexto de Testes
A secao de testes e onde voce define como o Claude deve escrever e rodar testes. Isso inclui padroes de teste, mocks e a estrategia geral de cobertura do projeto.
💡 Exemplo Completo
# Testing Strategy
## Unit Tests (Vitest + RTL)
- Test files colocated: Component.test.tsx next to Component.tsx
- Use `describe/it` pattern with descriptive names
- Mock external services in __mocks__/ directory
- Use MSW for API mocking, not jest.mock()
- Test behavior, not implementation details
## E2E Tests (Playwright)
- Located in tests/e2e/ directory
- Use Page Object Model pattern
- Run against local dev server with seeded test database
- Focus on critical user flows: auth, CRUD, payments
## Coverage
- Minimum 80% coverage for new code
- Always write tests for bug fixes (regression tests)
- Skip E2E tests in CI for draft PRs
⚡ Dica Pratica
Especifique "Use MSW for API mocking, not jest.mock()" para evitar mocks frageis. O Claude segue essas instrucoes consistentemente e gera testes mais robustos quando sabe a ferramenta correta.
📋 Resumo do Modulo
Proximo Modulo:
2.5 - Exemplo Real: Python FastAPI Backend