Sessão 1:
Você: "Adicione autenticação"
IA: *adiciona código com console.log em todo lugar*
Você: "Remova console.logs, usamos logging apropriado"
IA: *corrige*

Sessão 2 (dia seguinte):
Você: "Adicione reset de senha"
IA: *adiciona código com console.log em todo lugar*
Você: "Remova console.logs de novo..."

Configuração única:
Criar arquivo de regras: "Nunca use console.log. Use logger.info() em vez disso."

Sessão 1:
Você: "Adicione autenticação"
IA: *usa logger.info() automaticamente*

Sessão 2:
Você: "Adicione reset de senha"
IA: *usa logger.info() automaticamente*

# Na raiz do seu projeto
touch .cursorrules

# Na raiz do seu projeto
touch .windsurfrules
# Ou
mkdir -p .windsurf
touch .windsurf/rules.md

# Na raiz do seu projeto
mkdir -p .claude/skills
touch .claude/skills/project-conventions.md

# Na raiz do seu projeto
mkdir -p .antigravity
touch .antigravity/rules.md

# Convenções de Codificação do Projeto

## Linguagem e Framework
- TypeScript com modo strict
- Node.js 20+ com módulos ESM
- Express para API
- PostgreSQL para banco de dados
- Jest para testes

## Estilo de Código
- Use componentes funcionais (React)
- Prefira const ao invés de let
- Use tipos de retorno explícitos em TypeScript
- Sem tipos any a menos que absolutamente necessário
- Use async/await, nunca callbacks

## Logging
- NUNCA use console.log()
- Use nosso logger: `import { logger } from './utils/logger'`
- Níveis: logger.info(), logger.warn(), logger.error()

## Tratamento de Erros
```typescript
// Bom - tratamento estruturado de erros
try {
  const result = await operation();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operação falhou', { error });
  return { success: false, error: error.message };
}

// Ruim - deixando erros propagarem
const result = await operation(); // E se isso falhar?

// Bom
const user = await db.query(
  'SELECT * FROM users WHERE email = $1',
  [email]
);

// Ruim - vulnerabilidade de injeção SQL
const user = await db.query(
  `SELECT * FROM users WHERE email = '${email}'`
);

// Bons nomes de teste
it('deve criar usuário quando email é válido')
it('deve rejeitar registro quando email já existe')
it('deve fazer hash da senha antes de armazenar')

// Maus nomes de teste
it('funciona')
it('teste criação de usuário')

feat(auth): adiciona fluxo de reset de senha
fix(api): trata caso de perfil de usuário nulo
docs(readme): atualiza instruções de configuração

// Bom
const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) {
  throw new Error('Variável de ambiente DATABASE_URL é obrigatória');
}

// Ruim
const dbUrl = 'postgresql://localhost/mydb'; // Codificado fixo!

### Use Imediatamente

**Em Cursor/Windsurf/Antigravity:**

O arquivo de regras é carregado automaticamente quando você abre o projeto. Apenas comece a codificar:


> Adicione autenticação de usuário


A IA automaticamente:
- Usará TypeScript com tipos estritos
- Usará logger.info() em vez de console.log
- Escreverá consultas parametrizadas
- Seguirá padrões de tratamento de erros
- Criará testes apropriados

**Em Claude Code:**

A skill é detectada automaticamente:

```bash
claude

# Seu diretório home
~/.cursor/rules  # Cursor
~/.config/windsurf/rules.md  # Windsurf
~/.claude/skills/global/  # Claude Code
~/.antigravity/global-rules.md  # Antigravity

# Raiz do projeto
.cursorrules  # Cursor
.windsurfrules  # Windsurf
.claude/skills/  # Claude Code
.antigravity/rules.md  # Antigravity

.claude/skills/typescript-patterns.md  # Arquivos TypeScript
.claude/skills/react-components.md  # Componentes React
.claude/skills/api-endpoints.md  # Rotas de API

# ~/.cursorrules (ou equivalente)

## Minha Filosofia de Codificação
- Legibilidade acima de inteligência
- Explícito acima de implícito
- Simples acima de complexo
- Delete código ao invés de comentá-lo

## Estilo de Comunicação
- Seja conciso nas respostas
- Forneça exemplos de código
- Explique trade-offs quando múltiplas abordagens existem
- Se você não sabe, diga

## Padrões de Segurança
- Sempre valide entrada do usuário
- Use consultas parametrizadas
- Nunca registre dados sensíveis (senhas, tokens, PII)
- Assuma que toda entrada externa é maliciosa

## Padrões de Teste
- Escreva testes para toda lógica de negócio
- Teste casos extremos e estados de erro
- Use nomes de teste descritivos
- Prefira testes de integração a testes unitários

# .cursorrules (no projeto)

## Projeto: Plataforma de E-commerce

### Stack Tecnológica
- Next.js 14 com App Router
- TypeScript modo strict
- Prisma ORM com PostgreSQL
- Tailwind CSS para estilização
- Stripe para pagamentos

### Padrões Arquiteturais
- Server Components por padrão
- Client Components apenas quando necessário
- Rotas de API em /app/api
- Consultas de banco de dados em server components ou rotas de API
- Nunca consulte banco de dados de client components

### Tratamento de Pagamentos
- NUNCA armazene números de cartão de crédito
- Use tokenização do Stripe
- Registre todas tentativas de pagamento
- Trate falhas graciosamente
- Sempre use chaves de idempotência

### Gerenciamento de Estado
- React Context para tema/usuário
- Sem biblioteca de estado global
- Estado do servidor fica no servidor
- Estado do cliente é mínimo

## Organização de Arquivos

### Antes de QUALQUER Alteração no Banco de Dados:
1. Crie uma migration: `npm run db:migrate:create`
2. Revise o SQL gerado
3. Teste no banco de dados local
4. Nunca edite arquivos de migration diretamente

# .claude/skills/payment-processing.md

Ao trabalhar em código relacionado a pagamentos:

## Idempotência é Crítica
Toda operação de pagamento DEVE ser idempotente:

```typescript
// Bom - chave de idempotência previne cobranças duplicadas
await stripe.paymentIntents.create({
  amount: 1000,
  currency: 'usd',
  idempotency_key: `order_${orderId}_${userId}`
});

// Ruim - pode cobrar cliente duas vezes se retentado
await stripe.paymentIntents.create({
  amount: 1000,
  currency: 'usd'
});

### Como a Camada Funciona

Quando a IA processa sua solicitação, ela tem contexto de:
1. Suas preferências globais (como você pensa)
2. Convenções do projeto (padrões deste projeto)
3. Padrões específicos de domínio (tratamento de pagamento, por exemplo)

A IA segue a regra mais específica quando conflitos existem.

### Quando Usar

- Regras globais: Configure uma vez, beneficie-se em todos os projetos
- Regras de projeto: Defina no início do projeto
- Regras de contexto: Adicione conforme padrões emergem

### Exemplo Real

Trabalho em múltiplos projetos:
- Plataforma de e-commerce (Next.js + Stripe)
- Ferramentas internas (React + Express)
- App mobile (React Native)

**Sem camadas:**
Constantemente explicando diferenças entre projetos:
- "Este projeto usa Stripe, não PayPal"
- "Este projeto usa Express, não rotas de API Next.js"
- "Este projeto usa componentes React Native, não componentes web"

**Com camadas:**

**Regras globais** (~/.cursor/rules):
- Minhas preferências gerais
- Padrões de segurança
- Filosofia de testes

**Projeto e-commerce** (.cursorrules):
- Padrões Next.js
- Tratamento de pagamento Stripe
- Consultas de banco de dados com Prisma

**Ferramentas internas** (.cursorrules):
- Padrões de API Express
- Convenções REST
- Consultas MongoDB

**App mobile** (.cursorrules):
- Componentes React Native
- Padrões AsyncStorage
- Preocupações específicas de mobile

Agora quando troco de projetos, a IA se adapta automaticamente. Não preciso re-explicar.

---

## Padrão 3: Comandos Que Aplicam Workflows

Regras dizem à IA o que fazer. Comandos fazem acontecer automaticamente.

### O Que Comandos Realmente São

Comandos são workflows pré-definidos acionados por atalhos.

**Cursor**: Usa comandos composer
**Windsurf**: Usa comandos slash
**Claude Code**: Usa comandos slash + skills
**Antigravity**: Usa definições de workflow

### O Padrão Universal

Defina workflows comuns uma vez, acione com um comando:

**Workflow de Teste:**

```markdown 

Gatilho: /test
Workflow:
1. Execute suite de testes
2. Se testes falharem:
   a. Mostre saída de falha
   b. Identifique o problema
   c. Sugira correção
   d. Aguarde aprovação
   e. Aplique correção
   f. Execute testes novamente
3. Se testes passarem:
   a. Confirme sucesso
   b. Pergunte se pronto para commit

Gatilho: /feature
Workflow:
1. Pergunte descrição da feature
2. Identifique arquivos que precisam de alterações
3. Mostre plano de implementação
4. Aguarde aprovação
5. Escreva testes primeiro (TDD)
6. Implemente feature
7. Execute testes
8. Crie commit apropriado
9. Sugira próximos passos

Gatilho: /debug
Workflow:
1. Pergunte descrição do bug
2. Reproduza o problema
3. Forme hipóteses
4. Teste cada hipótese
5. Identifique causa raiz
6. Proponha correção com explicação
7. Implemente correção
8. Verifique que correção funciona
9. Adicione teste para prevenir regressão

# .cursorrules

## Workflows Personalizados

Quando eu disser "execute workflow de feature":
1. Me pergunte para descrever a feature
2. Me mostre quais arquivos precisam de alterações
3. Aguarde minha aprovação
4. Escreva testes primeiro
5. Implemente a feature
6. Execute testes para verificar
7. Crie um commit convencional

Quando eu disser "execute workflow de debug":
1. Me pergunte para descrever o bug
2. Me ajude a reproduzi-lo confiavelmente
3. Forme hipóteses sobre a causa
4. Teste cada hipótese sistematicamente
5. Identifique a causa raiz
6. Proponha uma correção com explicação
7. Implemente a correção
8. Verifique que o bug está resolvido
9. Adicione um teste para prevenir regressão

# .claude/skills/feature-workflow.md

---
name: feature-workflow
description: Use ao implementar novas features - fornece processo sistemático de desenvolvimento
---

# Workflow de Desenvolvimento de Features

Ao implementar uma nova feature, siga este processo sistemático:

## Passo 1: Entenda Requisitos
- Faça perguntas esclarecedoras se algo não estiver claro
- Identifique critérios de aceitação
- Note quaisquer casos extremos potenciais

## Passo 2: Planeje Implementação
- Liste arquivos que precisam de alterações
- Identifique novos arquivos necessários
- Note quaisquer migrations de banco de dados
- Mostre plano de implementação
- AGUARDE aprovação do usuário antes de prosseguir

## Passo 3: Escreva Testes Primeiro (TDD)
- Escreva testes falhando que definem comportamento desejado
- Cubra caminho feliz
- Cubra casos de erro
- Cubra casos extremos

## Passo 4: Implemente
- Faça alterações mínimas para passar testes
- Siga padrões de código existentes
- Mantenha alterações focadas

## Passo 5: Verifique
- Execute suite de testes
- Verifique que todos os testes passam
- Verifique teste manual se necessário

## Passo 6: Commit
- Crie commit convencional
- Inclua descrição da feature
- Referencie números de issue

## Passo 7: Próximos Passos
- Sugira atualizações de documentação
- Note qualquer trabalho de acompanhamento necessário
- Confirme que feature está completa

# .windsurfrules

## Workflow: Desenvolvimento de Feature

Gatilho de comando: "implementar feature" ou "adicionar feature"

Processo:
1. Coleta de requisitos
   - O que a feature faz?
   - Para quem é?
   - Quais são os critérios de aceitação?

2. Planejamento
   - Quais arquivos precisam de alterações?
   - Alguma nova dependência necessária?
   - Alterações no banco de dados necessárias?

3. Desenvolvimento orientado a testes
   - Escreva testes falhando
   - Implemente solução mínima
   - Verifique que testes passam

4. Integração
   - Execute suite completa de testes
   - Verifique que lint passa
   - Crie commit descritivo

Siga este processo para TODA feature. Sem atalhos.

implementar feature: edição de perfil de usuário

# .claude/skills/authentication-patterns.md

// Bom - fluxo de registro apropriado
export async function registerUser(email: string, password: string) {
  // 1. Valide entrada
  if (!isValidEmail(email)) {
    return { error: 'Formato de email inválido' };
  }

  if (password.length < 12) {
    return { error: 'Senha deve ter pelo menos 12 caracteres' };
  }

  // 2. Verifique se usuário existe
  const existing = await db.user.findUnique({ where: { email } });
  if (existing) {
    return { error: 'Email já registrado' };
  }

  // 3. Faça hash da senha (NUNCA armazene texto puro)
  const passwordHash = await bcrypt.hash(password, 12);

  // 4. Crie usuário
  const user = await db.user.create({
    data: {
      email,
      passwordHash,
      emailVerified: false
    }
  });

  // 5. Envie email de verificação
  await sendVerificationEmail(user.email);

  // 6. Não faça auto-login (requer verificação de email)
  return { success: true, userId: user.id };
}

// Estrutura de sessão
interface Session {
  id: string;
  userId: string;
  roles: string[];
  createdAt: Date;
  lastActivity: Date;
  expiresAt: Date;
}

// Provedores OAuth que suportamos
providers: [
  GoogleProvider({
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  }),
  GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
  }),
]

// Vincular conta OAuth a usuário existente
async function linkOAuthAccount(userId: string, provider: string, providerId: string) {
  // Verifique se conta OAuth já está vinculada a usuário diferente
  const existing = await db.account.findUnique({
    where: {
      provider_providerId: { provider, providerId }
    }
  });

  if (existing && existing.userId !== userId) {
    return { error: 'Conta OAuth já vinculada a outro usuário' };
  }

  // Vincule conta
  await db.account.create({
    data: {
      userId,
      provider,
      providerId,
      createdAt: new Date()
    }
  });

  return { success: true };
}

### Mais Exemplos de Domínio

**Processamento de Pagamento:**

```markdown
# Requisitos de Idempotência
Toda operação de pagamento DEVE ser idempotente:
- Use chaves de idempotência
- Armazene resultados de operação
- Retorne resultado em cache para solicitações duplicadas
- Nunca cobre cliente duas vezes

# Lógica de Retry
- Retente falhas transitórias (rede, timeout)
- Não retente falhas permanentes (fundos insuficientes, cartão inválido)
- Backoff exponencial para retries
- Máximo 3 tentativas de retry

# Logging
- Registre todas tentativas de pagamento (sucesso e falha)
- Registre pedidos de reembolso
- Registre eventos de webhook
- NUNCA registre: números de cartão, CVV, detalhes completos de cartão
- REGISTRE: últimos 4 dígitos, status de pagamento, valores

# Convenções REST
- GET: Ler recursos (idempotente)
- POST: Criar recursos (não idempotente)
- PUT: Substituição completa (idempotente)
- PATCH: Atualização parcial (idempotente)
- DELETE: Remover recursos (idempotente)

# Estrutura de URL
✅ /api/users/123
✅ /api/users/123/orders
✅ /api/orders/456

❌ /api/getUser?id=123
❌ /api/user_orders?user=123

# Formato de Resposta
```json
{
  "success": true,
  "data": { ... },
  "error": null
}

# ANTES de qualquer alteração de código:

1. **Entenda o código atual**
   - Leia arquivos relevantes primeiro
   - Entenda padrões existentes
   - Note quaisquer restrições

2. **Planeje a abordagem**
   - O que precisa mudar?
   - Quais arquivos estão envolvidos?
   - Alguma alteração no banco de dados necessária?
   - Alguma breaking change?

3. **Considere casos extremos**
   - O que pode dar errado?
   - Como tratamos erros?
   - E quanto à compatibilidade retroativa?

4. **Verifique testes**
   - Existem testes para este código?
   - Os testes precisarão de atualizações?
   - Devemos adicionar novos testes?

5. **AGUARDE aprovação**
   - Mostre o plano
   - Aguarde aprovação explícita
   - Só então faça alterações

# DEPOIS de qualquer alteração de código:

1. **Verifique que testes passam**
   - Execute a suite de testes
   - Mostre os resultados
   - Corrija quaisquer falhas antes de prosseguir

2. **Verifique lint**
   - Execute o linter
   - Corrija quaisquer problemas
   - Não faça commit com erros de lint

3. **Verifique que a alteração funciona**
   - Teste manualmente se necessário
   - Confirme que o problema está resolvido
   - Verifique efeitos colaterais

4. **Crie commit apropriado**
   - Siga convenções de commit
   - Escreva mensagem descritiva
   - Referencie números de issue

5. **Sugira próximos passos**
   - O que mais precisa ser feito?
   - Alguma tarefa de acompanhamento?
   - Alguma atualização de documentação?

Você: "Corrija o bug de login"
IA: *imediatamente começa a mudar código*
IA: *quebra outra coisa*
Você: "Espere, você executou os testes?"
IA: "Deixe-me executá-los agora"
Testes: FALHARAM
Você: *frustração intensifica*

Você: "Corrija o bug de login"

IA: "Antes de corrigir isso, deixe-me:
1. Ler o código de login atual
2. Entender como a autenticação funciona
3. Reproduzir o bug
4. Planejar a correção

[Lê arquivos]
[Testa reprodução]

Encontrei o problema: validação de token JWT está usando chave secreta errada.

Aqui está meu plano:
- Atualizar validação de token para usar chave correta
- Adicionar teste para verificar validação de token
- Verificar que testes existentes ainda passam

Devo prosseguir?"

Você: "Sim, vá em frente"

IA: [Implementa correção seguindo checklist]
- Testes escritos ✓
- Correção implementada ✓
- Testes passando ✓
- Lint passando ✓
- Commit criado ✓

Pronto. O bug está corrigido e não acontecerá novamente.

// Use tipos de retorno explícitos
function getUser(id: string): Promise<User> { ... }

// Não retornos implícitos
function getUser(id) { ... }

// Bom - tratamento estruturado de erros
try {
  const result = await operation();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operação falhou', { error });
  return { success: false, error: error.message };
}

// Ruim - deixando erros propagarem
const result = await operation();

Use consultas parametrizadas para prevenir injeção SQL:

// Bom - seguro contra injeção SQL
db.query('SELECT * FROM users WHERE id = $1', [userId])

// Ruim - vulnerável a injeção SQL
db.query(`SELECT * FROM users WHERE id = '${userId}'`)

Por quê: userId malicioso como "1' OR '1'='1" poderia expor todos os usuários.

## Padrão Bom:
const user = await fetchUser(userId);
if (!user) {
  return { error: 'Usuário não encontrado' };
}

## Padrão Ruim:
const user = await fetchUser(userId);
// Sem tratamento de erro - e se usuário não existir?

## Antes de Deploy para Produção:

- [ ] Todos os testes passam
- [ ] Lint passa
- [ ] Migrations de banco de dados rodam
- [ ] Variáveis de ambiente configuradas
- [ ] Monitoramento configurado
- [ ] Plano de rollback documentado
- [ ] Equipe notificada

## Erro: IA usou console.log em vez de logger

## Nova Regra:
NUNCA use console.log(). Sempre use:
- logger.info() para informação
- logger.warn() para avisos
- logger.error() para erros

Quando eu pedir para você implementar uma feature:
1. Me mostre seu plano de implementação
2. Aguarde minha aprovação
3. Escreva testes primeiro
4. Implemente a feature
5. Verifique que testes passam

Workflow de Implementação de Feature:
1. Planeje implementação
2. Solicite aprovação
3. Escreva testes (TDD)
4. Implemente código
5. Verifique testes

Gatilho: Usuário diz "implementar feature" ou "adicionar feature"

---
name: feature-implementation
description: Use ao implementar novas features
---

# Implementação de Feature

Ao implementar uma feature:
1. Mostre plano de implementação
2. Aguarde aprovação
3. Escreva testes primeiro
4. Implemente feature
5. Verifique que testes passam

## Processo de Desenvolvimento de Feature

Passos:
- Fase de planejamento (mostre plano, obtenha aprovação)
- Fase de teste (escreva testes falhando)
- Fase de implementação (faça testes passarem)
- Fase de verificação (confirme que testes passam)

Aplique este processo para todas solicitações de feature.

// Não faça isso
const x = y.map(z => z.foo);

// Ruim - nomes de variável pouco claros
const x = y.map(z => z.foo);

// Bom - nomes descritivos
const userNames = users.map(user => user.name);

# Convenções do Projeto

## Linguagem
TypeScript modo strict, Node.js 20+, módulos ESM

## Testes
Escreva testes ANTES da implementação (TDD)
Use Jest, cobertura mínima de 80%

## Commits
Formato: `tipo(escopo): descrição`
Tipos: feat, fix, docs, refactor, test

## Configuração
TODA config de variáveis de ambiente
Nunca codifique fixo chaves de API, URLs, segredos

## Logging
Use `logger.info/warn/error()`
Nunca use console.log()

## Antes de QUALQUER alteração de código:
1. Leia arquivos relevantes
2. Entenda padrões existentes
3. Planeje suas alterações
4. Obtenha aprovação se significante

## Depois de QUALQUER alteração de código:
1. Execute testes: `npm test`
2. Execute linter: `npm run lint`
3. Verifique que alterações funcionam
4. Crie commit apropriado

# Convenções do Projeto

## Stack Tecnológica
[Sua stack aqui]

## Estilo de Código
[Suas preferências com exemplos]

## Padrões Comuns
```js
// Bom
[exemplo]

// Ruim
[exemplo]

### Configuração Específica de Ferramenta

**Cursor:**
```bash
touch .cursorrules
# Adicione regras, elas são carregadas automaticamente

touch .windsurfrules
# Ou
mkdir .windsurf && touch .windsurf/rules.md

mkdir -p .claude/skills
touch .claude/skills/project-conventions.md

mkdir -p .antigravity
touch .antigravity/rules.md