CLAUDE.md Prompt de Arquiteto para Agentes de Codificação de IA

# CLAUDE.md - Guia do Projeto ## Visão Geral Sistema de gerenciamento de tarefas com interface web em React e API em Node.js. Stack: React 18, Node.js 20, Express, PostgreSQL, Prisma ORM. ## Mapa da Arquitetura ``` src/ client/ # Frontend React (Vite) components/ # Componentes UI reutilizáveis pages/ # Componentes de página hooks/ # Hooks customizados server/ # Backend Express routes/ # Definições de rotas API controllers/ # Lógica de negócio middleware/ # Middleware Express utils/ # Funções utilitárias shared/ # Tipos e utilitários compartilhados prisma/ schema.prisma # Schema do banco de dados migrations/ # Migrações do banco ``` ## Comandos Comuns - **Dev server**: `npm run dev` (inicia client e server) - **Build**: `npm run build` - **Testes**: `npm test` (todos) / `npm test -- --grep "nome do teste"` (arquivo único) - **Lint**: `npm run lint` - **Type-check**: `npm run typecheck` - **Migrações**: `npx prisma migrate dev` / `npx prisma migrate deploy` (produção) ## Convenções de Código - **Nomes de arquivos**: `kebab-case` para arquivos, `PascalCase` para componentes React - **Imports**: Ordem alfabética - React, bibliotecas externas, imports internos - **Tipos compartilhados**: Definir em `src/shared/types.ts`, nunca duplicar entre client/server - **Componentes**: Usar hooks funcionais, nunca classes. Props tipadas com TypeScript - **Rotas API**: Prefixo `/api/v1/`, nomes de rotas em `kebab-case` ## Armadilhas & Avisos - **NUNCA** importar de `src/server` no client ou vice-versa; use `src/shared` para tipos compartilhados - **Prisma**: Sempre use `npx prisma generate` após alterar o schema; nunca edite arquivos de migração manualmente - **Variáveis de ambiente**: Nunca hardcode secrets; use `process.env` com validação em `src/server/config.ts` - **Erros de CORS**: Ao adicionar novas rotas, verifique se estão no whitelist de `src/server/middleware/cors.ts` - **Testes**: Testes de integração exigem banco PostgreSQL rodando localmente; use `docker-compose up -d db` se necessário ## Git & Workflow - **Branches**: `feature/nome-descritivo`, `fix/descricao-do-bug`, `chore/tarefa` - **Commits**: Formato `tipo(escopo): descrição` - ex: `feat(auth): adiciona login com Google` - **PRs**: Sempre referenciar issue relacionada. CI roda lint, typecheck e testes - todos devem passar ## Referências - Para padrões de API, veja `src/server/routes/README.md` - Para padrões de componentes React, veja `src/client/components/README.md` - Para schema e consultas do banco, veja `prisma/README.md` - Para configuração de ambiente, veja `.env.example`