Introdução

Você está usando Cursor há três meses. Ou talvez seja Windsurf. Ou Claude Code. Ou Antigravity.

Não importa qual. A frustração é a mesma.

É meia-noite. Você está explicando—pela décima vez nesta semana—que sua equipe usa commits convencionais. Que os testes devem rodar antes de qualquer alteração no código. Que o linter precisa passar. Que a string de conexão do banco de dados vem de variáveis de ambiente, não de strings fixas no código.

A IA é brilhante. Mas tem amnésia.

Toda sessão é dia um. Toda instrução é a primeira vez. Você não está codificando—está treinando o mesmo desenvolvedor júnior repetidamente.

Então você descobre a personalização de agentes.

Trinta minutos depois, seu agente de IA:

Segue automaticamente suas convenções de commit
Roda testes antes de mudar qualquer código
Nunca codifica configurações fixas
Segue os padrões do seu projeto
Lembra suas preferências
Aplica os padrões da sua equipe

Toda. Única. Sessão.

Esta é a promessa da personalização de agentes. Mas aqui está o que ninguém te conta: os recursos de personalização funcionam diferentemente em cada ferramenta. Cursor tem .cursorrules. Windsurf tem arquivos de regras. Claude Code tem skills. Antigravity tem seu próprio sistema.

A sintaxe é diferente. O formato de arquivo é diferente. Mas os padrões são universais.

Depois de personalizar dezenas de agentes de codificação IA em diferentes ferramentas—e ajudar centenas de desenvolvedores a fazer o mesmo—identifiquei os padrões que funcionam em TODAS as plataformas.

Este não é um tutorial específico de ferramentas. É um manual universal para fazer QUALQUER agente de codificação IA lembrar suas preferências, seguir seus padrões e parar de fazer você se repetir.

A Mudança de Modelo Mental

Antes de mergulhar em arquivos .cursorrules e sintaxe de skills, você precisa entender o que torna a personalização de agentes fundamentalmente diferente.

O Que a Personalização Realmente É

Personalização de agentes não é configuração. É ensinar à IA sua expertise de domínio.

Pense nisso como contratar um novo desenvolvedor:

Sem personalização: Todo dia é dia um. Você explica as mesmas convenções, padrões e preferências
Com personalização: Dia um, você explica tudo uma vez. Para sempre depois, eles lembram

Sem personalização: Você instrui a IA Com personalização: A IA se instrui (com seu conhecimento)

A Diferença Crítica

Interação tradicional com IA:

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..."

Com personalização:

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*

Você codifica o conhecimento uma vez. A IA aplica para sempre.

Princípios Universais em Todas as Ferramentas

Seja usando Cursor, Windsurf, Claude Code ou Antigravity:

Princípio 1: Personalização acontece em arquivos

Cursor: .cursorrules
Windsurf: .windsurfrules ou rules.md
Claude Code: .claude/skills/*.md
Antigravity: .antigravity/rules.md

Princípio 2: Personalizações são contexto A IA carrega suas regras/skills/comandos no início de cada sessão.

Princípio 3: Especificidade vence Regras vagas ("escreva código bom") falham em todas as ferramentas. Regras específicas ("use logger.info(), nunca console.log") funcionam em todas as ferramentas.

Princípio 4: Exemplos ensinam melhor que descrições Mostre à IA o que você quer. Não apenas descreva.

A mudança de frustração para produtividade acontece quando você para de tratar a IA como se ela devesse magicamente conhecer suas preferências e começa a ensiná-la explicitamente.

Padrão 1: O Arquivo de Regras Universal (Configuração de 10 Minutos)

Todo agente de codificação IA suporta alguma forma de "arquivo de regras". A sintaxe varia, mas o conceito é idêntico.

O Que Você Está Construindo

Um único arquivo que diz à IA:

Suas convenções de codificação
Seus padrões de projeto
Seus padrões de equipe
Suas abordagens preferidas

A Configuração (Funciona em Todo Lugar)

Para Cursor:

# Na raiz do seu projeto
touch .cursorrules

Para Windsurf:

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

Para Claude Code:

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

Para Antigravity:

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

O conteúdo (mesmos princípios em todas as ferramentas):

# 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?

Consultas de Banco de Dados

Use consultas parametrizadas SEMPRE
Nunca concatene entrada do usuário em SQL
Use transações para operações multi-etapa

// 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}'`
);

Requisitos de Testes

Escreva testes ANTES da implementação (TDD)
Toda função precisa de um teste
Teste caminho feliz + casos de erro
Use nomes de teste descritivos

// 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')

Commits Git

Siga commits convencionais:

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

Formato: <tipo>(<escopo>): <descrição>

Tipos: feat, fix, docs, style, refactor, test, chore

Variáveis de Ambiente

NUNCA codifique fixo segredos, chaves de API ou strings de conexão
Use process.env para toda configuração
Forneça .env.example mas não .env

// 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!

Antes de QUALQUER alteração de código:

Leia os arquivos relevantes primeiro
Entenda os padrões existentes
Siga os mesmos padrões
Não introduza novas abordagens sem discussão

Antes de marcar trabalho como completo:

Execute testes: npm test
Execute linter: npm run lint
Verifique que as alterações funcionam
Confirme que não há código de debug


### 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

Adicione autenticação de usuário

Claude carrega suas convenções automaticamente.

Quando Usar

Iniciando um novo projeto (defina convenções cedo)
Entrando em um projeto existente (codifique padrões que você descobre)
Onboarding de membros da equipe (eles recebem convenções automaticamente)
Quando você se pega repetindo instruções

Exemplo Real

Entrei em um projeto cliente usando Cursor. Primeiro dia, estava constantemente corrigindo:

"Use tipos TypeScript"
"Não use console.log"
"Siga nosso formato de commit"
"Escreva testes primeiro"

Abordagem tradicional (dolorosa): Repeti essas correções 20+ vezes por dia.

Abordagem com arquivo de regras (resolvida em 10 minutos):

Criei .cursorrules com as convenções deles. Próxima sessão:

Adicione feature de verificação de email

Cursor automaticamente:

Usou TypeScript com tipos apropriados
Usou a biblioteca de logging deles
Escreveu testes primeiro
Criou commit formatado apropriadamente
Seguiu seus padrões de tratamento de erros

Zero correções necessárias. O arquivo de regras ensinou ao Cursor os padrões deles.

Padrão 2: Regras Específicas de Contexto (O Poder das Camadas)

Um arquivo de regras é bom. Múltiplos arquivos de regras específicos de contexto são transformacionais.

O Padrão

Regras globais (aplicam a todos os projetos):

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

Regras de projeto (aplicam a este projeto):

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

Regras específicas de tipo de arquivo (algumas ferramentas suportam):

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

Estratégia de Camadas

Camada 1: Preferências Universais (Global)

# ~/.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

Camada 2: Específico do Projeto (Raiz do Projeto)

# .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

app/ (auth)/ # Páginas relacionadas a auth login/ register/ (dashboard)/ # Páginas do dashboard api/ # Rotas de API components/ ui/ # Componentes de UI reutilizáveis lib/ # Utilitários e helpers prisma/ # Schema do banco de dados


### 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

Camada 3: Específico de Contexto (Feature/Domínio)

Para ferramentas que suportam (como Claude Code com múltiplas skills):

# .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'
});

Requisitos de Logging

Registre TUDO relacionado a pagamentos:

Tentativas de pagamento (sucesso e falha)
Pedidos de reembolso
Eventos de webhook
Mas NUNCA registre: números de cartão, CVV, PINs

Tratamento de Erros

Retente falhas transitórias (problemas de rede)
Não retente falhas permanentes (fundos insuficientes)
Sempre notifique cliente do resultado
Registre erros para equipe de suporte

Testando Código de Pagamento

Use modo de teste do Stripe
Teste casos de sucesso e falha
Teste entrega de webhook
Verifique que idempotência funciona


### 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

Workflow de Feature:

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

Workflow de Debug:

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

Implementação Entre Ferramentas

Cursor (usando .cursorrules):

# .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 Code (usando skills):

# .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

Windsurf (usando arquivo de regras):

# .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.

Quando Usar

Workflows repetidos (teste, debug, deploy)
Processos multi-etapa (desenvolvimento de feature, refatoração)
Gates de qualidade (antes de commit, antes de deploy)
Onboarding (novos membros da equipe aprendem workflows)

Exemplo Real

Minha equipe era inconsistente em como features eram desenvolvidas:

Alguns escreviam testes primeiro, outros não
Alguns esqueciam de executar linter
Alguns commitavam código quebrado
Qualidade do código variava dramaticamente

Antes de workflows: Cada desenvolvedor usava seu próprio processo. Code reviews pegavam problemas, mas depois do trabalho estar feito.

Depois de workflows:

Criamos um "workflow de feature" em nosso arquivo de regras. Agora:

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

A IA:

Fez perguntas esclarecedoras
Mostrou plano de implementação
Aguardou aprovação
Escreveu testes primeiro
Implementou a feature
Executou todos os testes
Executou linter
Criou commit apropriado

Resultado:

Processo consistente em toda equipe
Menos bugs (testes escritos primeiro)
Melhores commits (formatação automatizada)
Code reviews mais rápidas (consistência reduz carga de review)

Padrão 4: Regras Específicas de Domínio Que Escalam

Regras genéricas ajudam. Regras específicas de domínio transformam.

O Padrão

Em vez de regras gerais, crie orientação específica de domínio para:

Autenticação: Fluxos OAuth, tratamento JWT, gerenciamento de sessão
Pagamentos: Idempotência, lógica de retry, conformidade PCI
Real-time: WebSockets, tratamento de conexão, sincronização de estado
Performance: Cache, otimização de consultas, lazy loading
Segurança: Validação de entrada, encoding de saída, controle de acesso

Exemplo: Regras de Autenticação

# .claude/skills/authentication-patterns.md

## Autenticação Neste Projeto

### Stack Tecnológica
- NextAuth.js para autenticação
- Tokens JWT para API
- PostgreSQL para armazenamento de usuário
- Redis para cache de sessão

### Fluxo de Registro de Usuário

```typescript
// 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 };
}

Requisitos de Senha

Mínimo 12 caracteres
Deve incluir: maiúscula, minúscula, número, símbolo
Verifique contra senhas comuns (use biblioteca)
Nunca mostre medidor de força de senha (vazamento de informação)

Gerenciamento de Sessão

Sessões expiram após 7 dias de inatividade
Armazene em Redis para acesso rápido
Inclua: userId, roles, createdAt, lastActivity

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

Tokens JWT

Use RS256 (assimétrico), não HS256
Expiração curta (15 minutos para access token)
Refresh tokens válidos por 7 dias
Inclua: userId, roles, iat, exp

Nunca:

❌ Armazene senhas em texto puro
❌ Armazene senhas com hash fraco (MD5, SHA1)
❌ Registre senhas ou tokens
❌ Envie senhas em parâmetros de URL
❌ Retorne dados sensíveis de usuário em mensagens de erro
❌ Confie em JWT sem verificação

Sempre:

✅ Faça hash de senhas com bcrypt (fator de custo 12)
✅ Use comparação timing-safe para tokens
✅ Valide TODA entrada
✅ Limite taxa de tentativas de autenticação
✅ Registre eventos de autenticação (sucesso e falha)
✅ Exija verificação de email
✅ Implemente fluxo de reset de senha

Limitação de Taxa

Tentativas de login: 5 por 15 minutos por IP
Registro: 3 por hora por IP
Reset de senha: 3 por hora por email

Integração OAuth

// 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 };
}

Testando Código de Autenticação

Simule provedores OAuth externos
Teste limitação de taxa
Teste validação de senha
Teste expiração de sessão
Teste validação de token
Teste tentativas de acesso não autorizado

Ao implementar QUALQUER feature de autenticação, siga estes padrões exatamente.


### 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

Design de API:

# 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
}

Códigos de Status

200: Sucesso com corpo de resposta
201: Recurso criado
204: Sucesso, sem corpo de resposta
400: Erro do cliente (entrada inválida)
401: Não autenticado
403: Autenticado mas não autorizado
404: Recurso não encontrado
500: Erro do servidor

Quando Usar

Domínios complexos (pagamentos, auth, real-time)
Código crítico de segurança (nunca confie no conhecimento padrão da IA)
Padrões específicos da equipe (sua abordagem para problemas)
Requisitos regulatórios (PCI, HIPAA, GDPR)

Padrão 5: O Checklist de Pré-Voo

O padrão mais poderoso: regras que rodam ANTES do trabalho começar.

O Padrão

# 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?

Por Que Isso Funciona

O checklist de pré-voo:

Previne implementação prematura (entenda antes de mudar)
Detecta problemas cedo (planejamento revela problemas)
Aplica qualidade (testes, linting, verificação)
Fornece estrutura (processo claro toda vez)

Exemplo Real

Antes do checklist de pré-voo:

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*

Depois do checklist de pré-voo:

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.

Quando Usar

Todos os projetos (este deve ser seu padrão)
Previne implementações apressadas
Detecta erros antes de serem commitados
Fornece qualidade consistente

Melhores Práticas Universais (Funcionam em Todas as Ferramentas)

Estes padrões funcionam seja você usando Cursor, Windsurf, Claude Code ou Antigravity:

1. Seja Extremamente Específico

❌ Vago:

Escreva código limpo.

✅ Específico:

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

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

2. Mostre Exemplos

❌ Abstrato:

Siga melhores práticas de tratamento de erros.

✅ Concreto:

// 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();

3. Explique o Porquê

❌ Comando:

Use consultas parametrizadas.

✅ Raciocínio:

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.

4. Inclua Exemplos Negativos

Mostre o que NÃO fazer:

## 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?

5. Crie Checklists

Para workflows complexos:

## 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

6. Camadas Suas Regras

Regras globais (suas preferências):

Estilo de código
Preferências de comunicação
Padrões de segurança

Regras de projeto (este projeto):

Stack tecnológica
Decisões arquiteturais
Padrões específicos do projeto

Regras de domínio (específicas de feature):

Tratamento de pagamento
Autenticação
Features real-time

7. Atualize Baseado em Erros

Toda vez que a IA comete um erro, pergunte: "Uma regra poderia prevenir isso?"

Se sim, adicione a regra:

## 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

Seu arquivo de regras se torna melhor com cada erro.

Guia de Compatibilidade Entre Ferramentas

Aqui está como traduzir padrões entre diferentes ferramentas:

Localização do Arquivo de Regras

Ferramenta	Localização	Formato
Cursor	`.cursorrules`	Markdown
Windsurf	`.windsurfrules` ou `.windsurf/rules.md`	Markdown
Claude Code	`.claude/skills/*.md`	Markdown com frontmatter
Antigravity	`.antigravity/rules.md`	Markdown

Regras Globais vs Projeto

Ferramenta	Global	Projeto
Cursor	`~/.cursor/rules`	`.cursorrules`
Windsurf	`~/.config/windsurf/rules`	`.windsurfrules`
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Antigravity	`~/.antigravity/`	`.antigravity/`

Gatilhos de Comando/Workflow

Ferramenta	Como Definir	Como Acionar
Cursor	Em `.cursorrules`, descreva workflow	Linguagem natural
Windsurf	Em arquivo de regras, defina workflow	Comandos slash
Claude Code	Arquivos de skill separados	`/skill-name` ou automático
Antigravity	Definições de workflow	Linguagem natural

Exemplo: Mesma Regra, Formatos Diferentes

Cursor (.cursorrules):

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

Windsurf (.windsurfrules):

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"

Claude Code (.claude/skills/feature-implementation.md):

---
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

Antigravity (.antigravity/rules.md):

## 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.

A sintaxe difere, mas o padrão é idêntico.

Medindo Eficácia da Personalização

Como você sabe se suas regras/skills estão funcionando?

Métrica 1: Frequência de Correção

Rastreie com que frequência você corrige a IA:

Antes da personalização: 15-20 correções por sessão Depois da personalização: 2-3 correções por sessão

Métrica 2: Tempo Até Primeira Saída Correta

Quanto tempo até a IA produzir código utilizável?

Antes: 5-10 iterações Depois: 1-2 iterações

Métrica 3: Consistência Entre Sessões

Verifique código produzido em diferentes sessões. Quão consistente é?

Antes: Altamente variável (padrões diferentes cada vez) Depois: Consistente (segue mesmos padrões)

Métrica 4: Velocidade de Onboarding

Quanto tempo até um novo membro da equipe ser produtivo?

Antes da personalização: 2 semanas (aprender convenções, padrões) Depois da personalização: 3 dias (IA segue padrões automaticamente)

Revisão Semanal

Toda sexta-feira:

O que você repetiu mais frequentemente?
- Adicione ao arquivo de regras
Quais erros foram cometidos?
- Adicione regras para preveni-los
O que funcionou bem?
- Mantenha essas regras
Quais regras foram ignoradas?
- Torne-as mais específicas ou remova-as

Armadilhas Comuns e Soluções

Armadilha 1: Regras Muito Vagas

❌ "Escreva código bom" ❌ "Siga melhores práticas" ❌ "Tenha cuidado com segurança"

✅ Regras específicas e acionáveis com exemplos

Armadilha 2: Regras Muito Longas

Arquivo de regras de 500 linhas → IA fica confusa

Solução: Divida em seções focadas ou múltiplos arquivos

Armadilha 3: Regras Contraditórias

"Sempre escreva testes primeiro" vs "Pule testes ao fazer protótipo"

Solução: Torne condições explícitas: "Escreva testes primeiro para código de produção. Protótipos podem pular testes temporariamente."

Armadilha 4: Exemplos Sem Contexto

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

Sem contexto, IA não sabe por que isso é ruim.

Melhor:

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

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

Armadilha 5: Não Atualizar Regras

Regras escritas uma vez, nunca atualizadas → Regras ficam desatualizadas

Solução: Revise e atualize regras regularmente baseado em:

Erros que a IA cometeu
Novos padrões que você adota
Feedback da equipe

Estudo de Caso: Transformação de Startup

Deixe-me mostrar personalização em ação.

O Problema

Uma startup de 15 pessoas usando Cursor:

Cada desenvolvedor usava Cursor diferentemente
Qualidade do código inconsistente
Novos desenvolvedores levavam 2 semanas para ser produtivos
Mesmos erros repetidos em toda equipe
Code reviews levavam horas

Custo: 40% do tempo de desenvolvimento gasto em retrabalho e reviews

A Solução

Semana 1: Auditoria

Observei desenvolvedores trabalharem por uma semana. Notei instruções repetidas:

"Use TypeScript com modo strict"
"Escreva testes primeiro"
"Siga nosso formato de commit"
"Não codifique fixo configuração"
"Use nossa biblioteca de logging"

Estas apareceram em 80% das sessões.

Semana 2: Criar Regras Base

Criei .cursorrules com convenções da equipe:

# 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

Semana 3: Adicionar Regras de Domínio

Adicionei regras específicas de domínio para:

Padrões de design de API
Padrões de consulta de banco de dados
Fluxos de autenticação
Tratamento de erros

Semana 4: Medir e Refinar

Coletei métricas:

Frequência de correção: ↓75% (de 18 → 4.5 por sessão)
Tempo de code review: ↓60% (de 90min → 35min por PR)
Cobertura de testes: ↑de 45% → 82%
Score de consistência: ↑de 55% → 91%

A Transformação

Antes: Cursor era um desenvolvedor júnior precisando de orientação constante

Depois: Cursor era um desenvolvedor sênior que conhecia os padrões da equipe

A citação de um desenvolvedor: "Eu costumava gastar metade do meu tempo explicando nossas convenções. Agora gasto esse tempo construindo features. É como se Cursor tivesse passado de estagiário para engenheiro sênior da noite pro dia."

Resultados Após 6 Meses

23 regras específicas de domínio
Cada desenvolvedor usando mesmos padrões
Novos desenvolvedores produtivos em 3 dias
Regras open-sourced (outras equipes se beneficiando)
Regras se tornaram parte da contratação (candidatos veem práticas da equipe antecipadamente)

Seu Roteiro de Personalização

Aqui está como construir maestria, independente de qual ferramenta você usa:

Semana 1: Fundação

Dia 1: Crie arquivo básico de regras

Linguagem/framework
Preferências de estilo de código
Dos e don'ts básicos

Dia 2-3: Adicione exemplos

Mostre padrões bons vs ruins
Inclua explicações

Dia 4-5: Teste e refine

Use em trabalho real
Rastreie o que funciona
Atualize baseado em erros

Semana 2: Workflows

Dia 1-2: Defina seus workflows comuns

Desenvolvimento de feature
Correção de bug
Testes
Commits

Dia 3-4: Adicione regras de workflow

Checklists de pré-voo
Verificação pós-conclusão

Dia 5: Meça melhoria

Menos correções?
Iterações mais rápidas?
Melhor consistência?

Semana 3: Padrões de Domínio

Dia 1: Identifique necessidades específicas de domínio

Padrões de autenticação?
Processamento de pagamento?
Design de API?

Dia 2-3: Crie regras de domínio

Detalhadas, específicas
Com exemplos
Explicando trade-offs

Dia 4-5: Teste em produção

Use em features reais
Refine baseado em resultados

Semana 4: Escalando Equipe

Dia 1-2: Documente suas regras

Por que cada regra existe
Exemplos de problemas que previne

Dia 3: Compartilhe com equipe

Commit regras para git
Sessão breve de treinamento

Dia 4-5: Colete feedback

O que está funcionando?
O que está faltando?
O que está confuso?

Mês 2+: Melhoria Contínua

Revise regras mensalmente
Adicione regras para erros repetidos
Remova regras não usadas
Atualize baseado em novos padrões
Compartilhe regras bem-sucedidas com comunidade

Conclusão: A Vantagem Que Você Está Perdendo

Três meses atrás, personalizar agentes de codificação IA parecia trabalho extra.

Hoje, é a diferença entre desenvolvedores que usam IA como autocomplete inteligente e desenvolvedores que usam IA como colega de equipe treinado.

Mas maestria não é sobre qual ferramenta você usa. Cursor, Windsurf, Claude Code, Antigravity—a ferramenta não importa.

O que importa é codificar sua expertise para que a IA possa aplicá-la automaticamente.

Os padrões são universais:

Seja específico - Regras vagas falham em todo lugar
Mostre exemplos - Código fala mais alto que descrições
Explique o porquê - Contexto faz regras grudarem
Camadas suas regras - Global → Projeto → Domínio
Crie workflows - Processos multi-etapa precisam de estrutura
Atualize continuamente - Regras melhoram com cada erro
Meça eficácia - Rastreie correções, consistência, tempo

Estes padrões funcionam em todo agente de codificação IA porque não são sobre a ferramenta. São sobre ensinar IA sua forma de trabalhar.

Os desenvolvedores que dominam isso terão uma vantagem injusta.

Os que não vão continuar se repetindo toda sessão.

A diferença é personalização.

Comece a construir.

Referência Rápida

Checklist Universal de Personalização

Configurando QUALQUER agente de codificação IA:

Criar arquivo de regras na raiz do projeto
Definir suas preferências de estilo de código
Adicionar exemplos de padrões bons vs ruins
Definir workflows comuns
Adicionar checklist de pré-voo (antes de alterações)
Adicionar checklist pós-conclusão (depois de alterações)
Incluir padrões específicos de domínio
Testar com trabalho real
Atualizar baseado em erros
Compartilhar com equipe

Template de Arquivo de Regras (Funciona em Todo Lugar)

# 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]

Workflows

Desenvolvimento de Feature

Planejar
Obter aprovação
Escrever testes
Implementar
Verificar

Correção de Bug

Reproduzir
Identificar causa
Planejar correção
Implementar com teste
Verificar

Antes de QUALQUER Alteração de Código:

Ler arquivos relevantes
Entender padrões existentes
Planejar abordagem
Considerar casos extremos

Depois de QUALQUER Alteração de Código:

Executar testes
Executar linter
Verificar que alterações funcionam
Criar commit apropriado

Regras Específicas de Domínio

[Seus padrões de domínio aqui]


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

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

Windsurf:

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

Claude Code:

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

Antigravity:

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

Sua vez. Escolha uma instrução que você repete toda sessão. Adicione-a ao seu arquivo de regras hoje.

O multiplicador de produtividade 10x não está no próximo modelo de IA.

Está nas regras que você escreve hoje.