Windsurf Rules: Personalize a IA para o seu Projeto

Um dos problemas comuns com IAs de código é que elas não conhecem as convenções específicas do seu projeto — elas geram código que funciona, mas não segue o padrão que sua equipe adotou. O Windsurf resolve isso com o sistema de Rules.

O que são Rules no Windsurf

Rules são instruções que o Cascade segue automaticamente em todas as interações. Você as define uma vez e a IA as respeita em todos os requests — sem precisar repetir nas suas mensagens.

Criando seu arquivo de Rules

Crie um arquivo .windsurfrules na raiz do projeto:

# Convenções do Projeto

## Stack
- Frontend: React 18 + TypeScript strict mode
- Estilização: Tailwind CSS (sem CSS customizado, apenas utilities)
- Componentes: shadcn/ui como base
- Estado: Zustand para global, useState para local
- Data fetching: React Query (TanStack Query v5)
- Backend: Supabase (PostgreSQL + Auth + Storage)

## Convenções de código
- Sempre use arrow functions para componentes React
- Nomeie componentes em PascalCase, funções em camelCase
- Prefixe hooks customizados com "use"
- Exports sempre no final do arquivo, nunca inline
- Props: sempre desestruture, nunca use props.xxx

## Estrutura de arquivos
- Componentes: src/components/[ComponentName]/index.tsx
- Hooks: src/hooks/use-[name].ts
- Services: src/services/[name].service.ts
- Types: definir junto ao arquivo que usa, ou em src/types/ se compartilhado

## Proibições
- NÃO use any no TypeScript
- NÃO use class components
- NÃO use useState para estado que deve ser global
- NÃO instale bibliotecas sem listar no rule de bibliotecas aprovadas

## Bibliotecas aprovadas
- UI: shadcn/ui, lucide-react
- Forms: react-hook-form + zod
- Gráficos: recharts
- Datas: date-fns
- Animações: framer-motion

Regras por tipo de arquivo

Você pode ter regras mais específicas para contextos:

## Rules para Testes
- Use Vitest + Testing Library
- Nomeie arquivos: [Component].test.tsx
- Sempre mock chamadas de API
- Teste comportamento do usuário, não implementação

## Rules para Supabase
- Sempre habilite RLS em novas tabelas
- Use service key apenas em Edge Functions, nunca no frontend
- Nomeie tabelas em snake_case plural (users, user_profiles)
- Toda tabela deve ter id (uuid), created_at e updated_at

Rules para diferentes perfis de projeto

Para uma API Node.js/Express:

## Stack API
- Node.js + TypeScript
- Express.js com async/await (nunca callbacks)
- Validação de input com Zod
- Erros: sempre retorne { error: string, code: string }
- HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found
- Logs com pino (nunca console.log em produção)

Para Python/FastAPI:

## Stack
- Python 3.11+, FastAPI, SQLAlchemy 2.0, Pydantic v2
- Type hints obrigatórios em todas as funções
- Use async/await em todos os endpoints
- Erros: sempre HTTPException com detail estruturado

Verificando se as rules estão funcionando

Após criar o .windsurfrules, peça algo que contraria o padrão antigo:

Crie um componente de botão

O Cascade deve gerar automaticamente com arrow function, TypeScript tipado, Tailwind e seguindo a estrutura de arquivo definida nas rules — sem você precisar pedir.

Rules bem definidas são o que transforma o Cascade de um gerador genérico em um colaborador que realmente conhece seu projeto.