Claude Code: Guia de Uso do CLAUDE.md

# CLAUDE.md

## Project Overview
[Uma linha descrevendo o que o projeto é e faz]

## Tech Stack
[Linguagem, framework, banco de dados, toolchain]

## Common Commands
[Comandos de build, teste, deploy, dev]

## Code Conventions
[Padrões de nomenclatura, organização de arquivos, requisitos de estilo]

## Constraints and Limitations
[O que não fazer, o que deve ser feito]

## Known Issues
[Dívida técnica e armadilhas que requerem atenção especial]

# CLAUDE.md

## Project Overview
Backend de plataforma SaaS de faturamento, gerenciando assinaturas, geração de faturas e integração de pagamentos.

## Tech Stack
- Node.js 20 + TypeScript 5.3
- Express 4.18 + middleware chain
- Prisma 5.x (PostgreSQL)
- Redis (cache + queue)
- Jest + Supertest (testing)

## Common Commands
- `npm run dev` — Iniciar servidor dev (porta 3000)
- `npm test` — Executar todos os testes
- `npm run lint` — Verificação ESLint
- `npx prisma migrate dev` — Migração de banco

## Code Conventions
- Camada de serviço apenas lida com lógica de negócios, sem acesso direto a objetos HTTP
- Camada de controller lida com transformação de request/response
- Todas as operações de banco via padrão Repository
- Erros usam classe AppError com statusCode e code
- Formato de resposta da API: `{ success: boolean, data: T, error?: string }`

## Constraints
- ❌ Nunca usar pg client diretamente, deve usar Prisma
- ❌ Nunca acessar req/res na camada de Service
- ❌ Nunca hardcodar secrets e credenciais
- ✅ Todo endpoint de API deve ter testes de integração
- ✅ Todos os valores monetários usam centavos (inteiro), evitar erros de ponto flutuante

## Known Issues
- PaymentService.processRefund tem problema de concorrência (veja ISSUE-342)
- InvoiceService.generatePDF tem desempenho ruim com muitos itens (veja ISSUE-156)

~/.claude/CLAUDE.md          # Global: Preferências pessoais
project-root/CLAUDE.md       # Projeto: Convenções da equipe
project-root/src/api/CLAUDE.md  # Diretório: Instruções locais

<!-- ~/.claude/CLAUDE.md -->
# Global Preferences

## Code Style
- Usar TypeScript strict mode
- Preferir const, evitar let
- Funções com no máximo 20 linhas
- Adicionar comentários JSDoc

## Testing Preferences
- Usar estilo describe/it
- Cada teste independente, sem dependência de ordem de execução
- Mock dependências externas, não módulos internos

<!-- src/api/CLAUDE.md -->
# API Module Conventions

## Route Registration
- Todas as rotas registradas centralmente em index.ts
- Ordem de middleware: auth → rateLimit → validate → handler

## Response Format
- Success: { success: true, data: T }
- Failure: { success: false, error: { code, message } }

## Prohibited
- ❌ Não escrever lógica de negócios diretamente nos handlers
- ❌ Não pular validação de parâmetros

> Update CLAUDE.md based on recent code changes

Claude Code:
  → Reading recent commits
  → Changes detected: Express → Fastify, added Redis, Jest → Vitest
  → Updating CLAUDE.md with current tech stack and commands
  CLAUDE.md updated ✓