@luanpdd/kit-mcp 1.7.0 → 1.8.1

package/kit/skills/supabase-cron-queues/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: supabase-cron-queues
+description: Use ao orquestrar background jobs — pg_cron + pgmq + pg_net pattern cron → pgmq → Edge Function. Sem dep externa. Postgres 15.6.1.143+.
+---
+
+# Supabase — Cron + Queues (background jobs)
+
+## Quando usar
+
+LLM carrega esta skill quando implementar background jobs, scheduled tasks ou queues em Supabase **sem dependência externa** (Inngest, Trigger.dev, etc.). Trigger phrases:
+
+- "pg_cron", "supabase cron job"
+- "pgmq", "Postgres Message Queue"
+- "pg_net", "HTTP from database"
+- "background job Supabase"
+- "scheduled task Supabase"
+
+## Regras absolutas
+
+- **Extensions necessárias:**
+  - **`pg_cron`** — jobs scheduled (cron syntax)
+  - **`pgmq`** — Postgres Message Queue (requer Postgres **15.6.1.143+**)
+  - **`pg_net`** — HTTP requests do banco (recomendado v0.10.0+)
+- **Pattern canônico:** **`cron → pgmq → Edge Function`** — `pg_cron` enfileira mensagens em `pgmq`, Edge Function consome (via cron ou polling).
+- **Jobs `pg_cron` curtos** (< 10 min) — jobs longos bloqueiam scheduler. Para jobs longos, enfileire em `pgmq` e processe via Edge Function.
+- **`pgmq.send`** para enfileirar; **`pgmq.read` + `pgmq.archive`** para consumir. Visibility timeout previne double processing.
+- **`pg_net` é async** — `net.http_post` retorna `request_id`, response chega em `net._http_response`. Não bloqueia caller.
+- **Idempotência** — Edge Function consumer deve ser idempotente (mesma mensagem pode ser entregue 2× em retry).
+- **Cleanup** — sem `pgmq.archive` ou `pgmq.delete`, mensagem reaparece após visibility timeout (re-processed).
+
+## Patterns canônicos
+
+### Setup das extensions + criar fila
+
+```sql
+-- PT-BR: habilitar extensions (uma vez por projeto)
+create extension if not exists pg_cron;
+create extension if not exists pgmq;
+create extension if not exists pg_net;
+
+-- PT-BR: criar fila pgmq
+select pgmq.create('email_jobs');
+
+-- PT-BR: opcional — criar fila com retention customizado
+-- select pgmq.create_partitioned('large_jobs');
+```
+
+### Pattern canônico — `cron → pgmq → Edge Function`
+
+```sql
+-- PT-BR: 1. cron job a cada 5 min enfileira pendências em pgmq
+select cron.schedule(
+  'enqueue-pending-emails',
+  '*/5 * * * *',                    -- a cada 5 min
+  $$
+  insert into pgmq.q_email_jobs (message)
+  select jsonb_build_object(
+    'user_id', id,
+    'kind', 'reminder',
+    'enqueued_at', now()
+  )
+  from public.users
+  where pending_email = true
+  limit 1000;                       -- batch limitado
+  $$
+);
+
+-- PT-BR: 2. cron job a cada minuto despara processamento via Edge Function
+select cron.schedule(
+  'process-email-queue',
+  '*/1 * * * *',                    -- a cada minuto
+  $$
+  select net.http_post(
+    url := 'https://<project-ref>.supabase.co/functions/v1/process-emails',
+    headers := jsonb_build_object(
+      'Content-Type', 'application/json',
+      'Authorization', 'Bearer ' || current_setting('supabase.functions_token', true)
+    ),
+    body := '{}'::jsonb
+  );
+  $$
+);
+```
+
+### Edge Function consumer — pgmq.read + archive
+
+```ts
+// supabase/functions/process-emails/index.ts
+// PT-BR: consume da fila pgmq, processa, archive
+import { createClient } from 'npm:@supabase/supabase-js@2'
+
+Deno.serve(async () => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SECRET_KEYS')!
+  )
+
+  // PT-BR: pegar até 10 mensagens com visibility timeout 30s
+  const { data: msgs, error } = await supabase.rpc('pgmq_read', {
+    queue_name: 'email_jobs',
+    vt: 30,                           // visibility timeout em segundos
+    qty: 10,                          // máximo por chamada
+  })
+
+  if (error || !msgs?.length) {
+    return new Response('no jobs', { status: 200 })
+  }
+
+  for (const m of msgs) {
+    try {
+      // PT-BR: processar mensagem (idempotente!)
+      await sendEmail(m.message.user_id, m.message.kind)
+
+      // PT-BR: archive remove da fila e move para arquivo
+      await supabase.rpc('pgmq_archive', {
+        queue_name: 'email_jobs',
+        msg_id: m.msg_id,
+      })
+    } catch (err) {
+      // PT-BR: erro — não archive; visibility timeout expira e mensagem reaparece
+      console.error('processing error', m.msg_id, err)
+    }
+  }
+
+  return new Response(`processed ${msgs.length}`)
+})
+```
+
+### Job cron simples — sem queue (cuidado: < 10 min)
+
+```sql
+-- PT-BR: ok para tarefas leves e rápidas (cleanup, agregação)
+select cron.schedule(
+  'cleanup-old-sessions',
+  '0 3 * * *',                       -- 3am diário
+  $$
+  delete from public.sessions where expires_at < now() - interval '30 days';
+  $$
+);
+```
+
+### Listar e remover jobs cron
+
+```sql
+-- PT-BR: listar todos os jobs
+select * from cron.job;
+
+-- PT-BR: remover job
+select cron.unschedule('process-email-queue');
+```
+
+### `pg_net.http_post` async
+
+```sql
+-- PT-BR: dispara HTTP request, retorna request_id imediatamente
+select net.http_post(
+  url := 'https://api.example.com/webhook',
+  headers := jsonb_build_object('Authorization', 'Bearer xxx'),
+  body := jsonb_build_object('event', 'task_completed'),
+  timeout_milliseconds := 5000
+);
+
+-- PT-BR: response chega em net._http_response (consultar depois)
+select * from net._http_response order by created desc limit 10;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Job cron longo (> 10 min)
+
+**Errado:**
+```sql
+select cron.schedule(
+  'heavy-batch-process',
+  '0 * * * *',
+  $$ select pg_sleep(900); ... $$    -- ⚠ 15 min em pg_cron
+);
+```
+
+**Por quê:** `pg_cron` worker bloqueia outros jobs enquanto roda. Se job > 10 min ou trava, scheduler atrasa cascata. Em retry após failure, pode trancar inteiramente.
+
+**Certo:** cron enfileira; Edge Function processa pesado:
+```sql
+-- cron: leve (só enfileira)
+select cron.schedule('enqueue-heavy', '0 * * * *', $$
+  insert into pgmq.q_heavy_jobs (message) select ...;
+$$);
+-- Edge Function: pesado (consome com timeout próprio)
+```
+
+### Anti-pattern 2: HTTP síncrono direto de pg_cron
+
+**Errado:**
+```sql
+select cron.schedule('call-api', '*/1 * * * *', $$
+  -- ⚠ pg_net é async, mas user pode tentar sync com loops
+  select net.http_get('https://api.example.com/long');
+$$);
+```
+
+**Por quê:** HTTP requests podem demorar segundos a minutos. Se response demora, próxima execução do cron empilha. Em alta latência, scheduler fica trancado.
+
+**Certo:** enfileire em pgmq + Edge Function processa:
+```sql
+-- cron: enfileira
+insert into pgmq.q_api_calls (message) values ('{"endpoint": "/long"}');
+-- Edge Function: chama API com timeout próprio + archive
+```
+
+### Anti-pattern 3: `pgmq.read` sem `archive` ou `delete`
+
+**Errado:**
+```ts
+const { data: msgs } = await supabase.rpc('pgmq_read', { queue_name: 'jobs', vt: 30, qty: 10 })
+for (const m of msgs) {
+  await processJob(m.message)
+  // ⚠ esqueceu pgmq_archive
+}
+```
+
+**Por quê:** após visibility timeout (30s), mensagem reaparece — mesmo job rodado novamente. Em loop, leva a re-processing infinito.
+
+**Certo:**
+```ts
+for (const m of msgs) {
+  try {
+    await processJob(m.message)
+    await supabase.rpc('pgmq_archive', { queue_name: 'jobs', msg_id: m.msg_id })
+  } catch (err) {
+    // PT-BR: NÃO archive; mensagem retorna após vt para retry
+  }
+}
+```
+
+### Anti-pattern 4: Edge Function não-idempotente
+
+**Errado:**
+```ts
+async function processJob(msg) {
+  await sendEmail(msg.user_id)              // ⚠ envia email mesmo se já enviado
+  await chargeCard(msg.amount)              // ⚠ cobra mesmo se já cobrado
+}
+```
+
+**Por quê:** retries entregam mesma mensagem 2×+. Sem idempotência, side effects duplicam — usuário recebe 2 emails ou é cobrado 2×.
+
+**Certo:** rastreie estado:
+```ts
+async function processJob(msg) {
+  const { data: existing } = await supabase
+    .from('email_log')
+    .select('id')
+    .eq('msg_id', msg.id)
+    .single()
+  if (existing) return                     // já processado
+  await sendEmail(msg.user_id)
+  await supabase.from('email_log').insert({ msg_id: msg.id })
+}
+```
+
+## Ver também
+
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions consumindo pgmq
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — funções com `set search_path = ''` chamadas em cron
+- [supabase-migrations](../supabase-migrations/SKILL.md) — extensions criadas em migrations
+- [glossário](../_shared-supabase/glossary.md) — pg_cron, pgmq, pg_net

package/kit/skills/supabase-database-functions/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: supabase-database-functions
+description: Use ao criar funções Postgres — SECURITY INVOKER por padrão, SET search_path = '' SEMPRE, schema-qualified names, IMMUTABLE/STABLE quando possível.
+---
+
+# Supabase — Database Functions
+
+## Quando usar
+
+LLM carrega esta skill quando criar ou auditar funções Postgres em projeto Supabase. Trigger phrases:
+
+- "criar função Postgres", "create or replace function"
+- "trigger de banco", "function trigger"
+- "SECURITY INVOKER vs DEFINER"
+- "search_path", "set search_path"
+- "função imutável", "stable function"
+
+## Regras absolutas
+
+- **Sempre `SECURITY INVOKER`** por default — função roda com permissões de quem invoca (mais seguro). `SECURITY DEFINER` apenas com justificativa explícita escrita em comentário no topo da função.
+- **Sempre `set search_path = ''`** — sem isso, função vulnerável a hijack de schema. Documentado em [Database Advisors lint 0011](https://supabase.com/docs/guides/database/database-advisors).
+- **Schema-qualified** (em todas as referências a tabelas, colunas, outras funções): `public.tasks`, não `tasks`. Sem qualifier, lookup falha quando `search_path = ''`.
+- Marque **`IMMUTABLE`** se função não consulta DB e sempre retorna o mesmo para os mesmos inputs (ex: formatadores de string).
+- Marque **`STABLE`** se função consulta DB mas não modifica e retorna o mesmo dentro de uma transação (ex: lookups). Permite Postgres cachear o resultado por query.
+- Use **`VOLATILE`** apenas se função modifica dados ou tem side effects (default — não precisa explicitar).
+- Error handling com `RAISE EXCEPTION 'mensagem'` — nunca silent fail.
+- Para triggers: include `CREATE TRIGGER` válido junto com `CREATE FUNCTION` na mesma migration.
+
+## Patterns canônicos
+
+### Função simples — SECURITY INVOKER + search_path
+
+```sql
+-- formatador puro: IMMUTABLE
+create or replace function public.format_full_name(first_name text, last_name text)
+returns text
+language sql
+security invoker
+set search_path = ''
+immutable
+as $$
+  select first_name || ' ' || last_name;
+$$;
+```
+
+### Função com query — STABLE + schema-qualified
+
+```sql
+-- conta tasks de um usuário (não modifica) — STABLE permite caching
+create or replace function public.get_user_task_count(p_user_id uuid)
+returns integer
+language plpgsql
+security invoker
+set search_path = ''
+stable
+as $$
+declare
+  v_count integer;
+begin
+  select count(*) into v_count
+    from public.tasks                    -- schema-qualified obrigatório
+    where user_id = p_user_id;
+  return v_count;
+end;
+$$;
+```
+
+### Trigger — atualizar `updated_at`
+
+```sql
+-- function + trigger juntos na mesma migration
+create or replace function public.set_updated_at()
+returns trigger
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+begin
+  new.updated_at := now();
+  return new;
+end;
+$$;
+
+create trigger tasks_set_updated_at
+  before update on public.tasks
+  for each row
+  execute function public.set_updated_at();
+```
+
+### Função com error handling
+
+```sql
+create or replace function public.transfer_credits(
+  p_from_user uuid,
+  p_to_user uuid,
+  p_amount integer
+)
+returns void
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+declare
+  v_from_balance integer;
+begin
+  if p_amount <= 0 then
+    raise exception 'Valor de transferência deve ser positivo: %', p_amount;
+  end if;
+
+  select balance into v_from_balance
+    from public.accounts
+    where user_id = p_from_user
+    for update;                          -- lock para evitar race
+
+  if v_from_balance < p_amount then
+    raise exception 'Saldo insuficiente';
+  end if;
+
+  update public.accounts
+    set balance = balance - p_amount
+    where user_id = p_from_user;
+
+  update public.accounts
+    set balance = balance + p_amount
+    where user_id = p_to_user;
+end;
+$$;
+```
+
+### `SECURITY DEFINER` — quando justificável
+
+```sql
+-- caso raro: função precisa fazer algo que invoker não pode fazer
+-- ex: contar todos os usuários (acessível só para admins via app_metadata)
+-- mas exposto via RPC para qualquer authenticated com auth check interno
+
+-- comentário JUSTIFICANDO o DEFINER (obrigatório)
+create or replace function public.count_active_users()
+returns integer
+-- security definer porque: precisamos bypassar RLS de auth.users que bloqueia leitura
+-- mitigação: validamos role admin via app_metadata logo no topo
+language plpgsql
+security definer
+set search_path = ''
+stable
+as $$
+declare
+  v_count integer;
+begin
+  -- validar admin via app_metadata (não user_metadata!)
+  if (auth.jwt()->'app_metadata'->>'role') is distinct from 'admin' then
+    raise exception 'Acesso negado: apenas admins';
+  end if;
+
+  select count(*) into v_count
+    from public.users
+    where last_seen_at > now() - interval '30 days';
+  return v_count;
+end;
+$$;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: `SECURITY DEFINER` + sem `set search_path` + sem schema qualifier
+
+**Errado:**
+```sql
+create or replace function f()
+returns integer
+language plpgsql
+security definer                          -- ⚠ sem justificativa
+as $$                                     -- ⚠ sem set search_path
+begin
+  return (select count(*) from tasks);   -- ⚠ sem public. qualifier
+end;
+$$;
+```
+
+**Por quê:** atacante pode criar `tasks` em schema próprio + manipular `search_path` via `set local search_path = atacante,public` antes de invocar. Função `SECURITY DEFINER` executa com permissões do owner — atacante consegue ler/escrever onde não deveria.
+
+**Certo:**
+```sql
+create or replace function public.f()
+returns integer
+language plpgsql
+security invoker                          -- prefira invoker
+set search_path = ''                      -- bloqueia hijack
+stable
+as $$
+begin
+  return (select count(*) from public.tasks);  -- qualified
+end;
+$$;
+```
+
+### Anti-pattern 2: Função consulta DB mas marcada `IMMUTABLE`
+
+**Errado:**
+```sql
+create or replace function public.user_count_immutable()
+returns integer
+language sql
+immutable                                 -- ⚠ função consulta DB — não imutável
+set search_path = ''
+as $$
+  select count(*) from public.users;
+$$;
+```
+
+**Por quê:** `IMMUTABLE` diz para Postgres "este resultado nunca muda para os mesmos inputs". Postgres pode cachear ou pré-computar. Mas a contagem de usuários muda — Postgres pode retornar valor stale indefinidamente.
+
+**Certo:** usar `stable` (consulta DB, não modifica, mesmo em uma transação) ou `volatile` (default — recompute sempre).
+
+### Anti-pattern 3: Silent fail sem `raise exception`
+
+**Errado:**
+```sql
+create or replace function public.deduct_credits(p_user uuid, p_amount integer)
+returns void
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+begin
+  -- ⚠ sem validação — atualiza mesmo com saldo negativo
+  update public.accounts
+    set balance = balance - p_amount
+    where user_id = p_user;
+end;
+$$;
+```
+
+**Por quê:** silent fail oculta bugs. Saldo fica negativo sem aviso; testes downstream falham com mensagens enigmáticas.
+
+**Certo:**
+```sql
+-- valida + raise exception se inválido (ver pattern "transfer_credits" acima)
+```
+
+## Ver também
+
+- [supabase-postgres-style](../supabase-postgres-style/SKILL.md) — convenção de naming + style aplicada em funções
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — funções e RLS interagem (SECURITY INVOKER respeita RLS do invoker)
+- [supabase-migrations](../supabase-migrations/SKILL.md) — funções em migrations são versionadas
+- [supabase-cron-queues](../supabase-cron-queues/SKILL.md) — funções invocadas por `pg_cron` jobs
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + comandos CLI

package/kit/skills/supabase-declarative-schema/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: supabase-declarative-schema
+description: Use ao gerenciar schema via supabase/schemas/ — workflow stop → db diff -f → revisar → apply. Inclui caveats sobre views, RLS, partitions.
+---
+
+# Supabase — Declarative Database Schema
+
+## Quando usar
+
+LLM carrega esta skill quando trabalhar com `supabase/schemas/` (declarative source-of-truth) em vez de migrations imperativas. Trigger phrases:
+
+- "supabase schemas/", "declarative schema"
+- "supabase db diff", "gerar migration de schema"
+- "schema source of truth"
+- "como adicionar tabela em projeto declarative"
+
+## Regras absolutas
+
+- **Workflow canônico:**
+  1. Editar arquivos `.sql` em `supabase/schemas/` (representando estado **final** desejado de cada entidade)
+  2. **`supabase stop`** — derrubar containers locais (necessário antes de diff)
+  3. **`supabase db diff -f <name>`** — gera migration em `supabase/migrations/<timestamp>_<name>.sql`
+  4. **Revisar manualmente** a migration gerada (diff é heurístico — pode gerar SQL incorreto em renames, drops, etc.)
+  5. `supabase db reset` para aplicar local; `supabase db push` para aplicar remote
+- **Nunca pule `supabase stop`** antes de `db diff` — diff sem stop produz output inconsistente.
+- **Nunca pule revisão** da migration gerada — especialmente para renames (diff pode gerar `drop+create` em vez de `rename column`).
+- **DML (INSERT/UPDATE/DELETE) NÃO é declarative** — fica em migrations imperativas (`supabase/migrations/`) ou `supabase/seed.sql`.
+- **Files ordenados lexicograficamente** — para gerenciar dependências (FKs), nomeie de forma que a ordem de execução resolva referências (ex: `01_users.sql`, `02_tasks.sql`).
+- **Adicione novas colunas no fim** da definição da tabela — evita diffs falsos em PRs.
+- Seu `kit` de schemas reflete estado final, **não** o histórico — migrations carregam o histórico.
+
+## Patterns canônicos
+
+### Estrutura típica de `supabase/schemas/`
+
+```
+supabase/
+├── schemas/
+│   ├── 01_extensions.sql         -- create extension if not exists ...
+│   ├── 02_users.sql              -- public.users (mirror de auth.users)
+│   ├── 03_tasks.sql              -- public.tasks
+│   ├── 04_tasks_rls.sql          -- policies em public.tasks
+│   └── 05_functions.sql          -- public.set_updated_at, etc.
+├── migrations/                    -- gerado por db diff (revisado e commitado)
+└── seed.sql                       -- DML (não declarative)
+```
+
+### Workflow de mudança
+
+```bash
+# PT-BR: 1. editar schemas/
+# (ex: adicionar coluna priority em supabase/schemas/03_tasks.sql)
+
+# PT-BR: 2. parar containers (obrigatório antes de diff)
+supabase stop
+
+# PT-BR: 3. gerar migration
+supabase db diff -f add_priority_to_tasks
+
+# PT-BR: 4. revisar arquivo gerado
+# supabase/migrations/<timestamp>_add_priority_to_tasks.sql
+# (verificar se diff capturou só o intended change — não renames falsos, drops indevidos)
+
+# PT-BR: 5. aplicar local
+supabase db reset
+
+# PT-BR: 6. (depois) aplicar remote
+supabase db push
+```
+
+### Schema com FK e RLS
+
+```sql
+-- supabase/schemas/03_tasks.sql
+create table if not exists public.tasks (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  title text not null,
+  status text not null default 'todo',
+  priority text not null default 'low',           -- novas colunas: append no fim
+  created_at timestamptz not null default now()
+);
+
+alter table public.tasks enable row level security;
+
+-- policies em arquivo separado (04_tasks_rls.sql) ou aqui
+-- mas sempre granulares (ver supabase-rls-policies)
+```
+
+## Caveats — limitações conhecidas do declarative
+
+O `migra` diff tool (usado por `supabase db diff`) tem edge cases. **Sempre revise** a migration gerada antes de aplicar.
+
+### DML (INSERT/UPDATE/DELETE)
+- **Não rastreável** por declarative (declarative só captura DDL — Data Definition Language).
+- Use `supabase/seed.sql` para seed data ou migrations imperativas para mudanças de dados.
+
+### View ownership e atributos
+- Diff **não captura mudanças de owner** de views.
+- **Security invoker em views** não é diferenciado por diff — usar migration manual se mudar.
+- **Materialized views** têm suporte limitado.
+- **Mudança de column type em views** não recria a view — diff pode falhar silenciosamente.
+
+### RLS policies
+- `alter policy` statements são suportados mas podem ter edge cases.
+- **Column privileges** não são totalmente capturados.
+
+### Outras entidades
+- **Schema privileges:** não rastreados (cada schema diffado separadamente).
+- **Comments on objects:** não rastreados.
+- **Partitions:** suporte limitado — partitioned tables podem precisar migration manual.
+- **`alter publication ... add table`:** não detectado por diff.
+- **`create domain`:** ignorado por diff (usar migration imperativa).
+- **`grant` statements:** duplicados a partir de default privileges — verificar saída.
+
+## Anti-patterns
+
+### Anti-pattern 1: `db diff` com containers up
+
+**Errado:**
+```bash
+# containers ainda rodando
+supabase db diff -f my_change   # ⚠ output inconsistente
+```
+
+**Por quê:** diff compara schema declarado em `schemas/` com DB local atual. Se containers up, DB tem state inconsistente (mid-transaction, locks abertos).
+
+**Certo:**
+```bash
+supabase stop
+supabase db diff -f my_change
+```
+
+### Anti-pattern 2: Aplicar migration gerada sem revisão
+
+**Errado:**
+```bash
+supabase db diff -f rename_column
+supabase db push   # ⚠ aplicou sem revisar
+```
+
+**Por quê:** diff é heurístico. Em renames, pode gerar `drop column old + create column new` em vez de `alter table ... rename column`. Resultado: dados perdidos.
+
+**Certo:** sempre abrir `supabase/migrations/<timestamp>_*.sql` e revisar antes de aplicar.
+
+### Anti-pattern 3: DML em `supabase/schemas/`
+
+**Errado:**
+```sql
+-- supabase/schemas/03_tasks.sql
+create table if not exists public.tasks (...);
+
+insert into public.tasks (id, title) values (...);   -- ⚠ DML não é declarative
+```
+
+**Por quê:** declarative captura apenas DDL. Inserts em `schemas/` rodam quando schema é aplicado, mas não são rastreáveis em migrations — recriam sempre que `db reset`.
+
+**Certo:** mover INSERTs para `supabase/seed.sql` ou migration imperativa.
+
+### Anti-pattern 4: Adicionar coluna no meio da definição
+
+**Errado:**
+```sql
+-- antes
+create table public.tasks (id uuid, title text, created_at timestamptz);
+
+-- depois (coluna adicionada NO MEIO)
+create table public.tasks (id uuid, priority text, title text, created_at timestamptz);
+```
+
+**Por quê:** diff pode interpretar como reorder e gerar SQL ineficiente (drop + recreate de várias colunas).
+
+**Certo:** appendar no fim:
+```sql
+create table public.tasks (id uuid, title text, created_at timestamptz, priority text);
+```
+
+## Ver também
+
+- [supabase-migrations](../supabase-migrations/SKILL.md) — formato e regras dos arquivos gerados em `migrations/`
+- [supabase-postgres-style](../supabase-postgres-style/SKILL.md) — estilo SQL nas declarações
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — como expressar RLS em schemas/
+- [glossário](../_shared-supabase/glossary.md) — comandos CLI canônicos (`supabase stop`, `db diff -f`, `db reset`)