Vibecoding mais seguro para seus apps web, com menor esforço seu.

O problema

Vibecodar um app pessoal funciona, até não funcionar

Quatro falhas aparecem em quase todo app pessoal construído com IA. Nenhuma se anuncia; todas custam caro, e a primeira custa os dados de outras pessoas.

Como funciona na prática

Rígido nas pontas, livre no meio

Carregue com o primeiro prompt sobre o app e depois só construa. O objetivo não é deixar a construção lenta: é tornar o começo deliberado e o fim verificado, para que a parte rápida do meio continue rápida sem acumular débito técnico em silêncio.

1. Você pede
"Faz um sistema de controle de chamados em Next.js pra eu publicar na Vercel."

2. As seis perguntas de bootstrap, um lote
Repositório (novo nasce privado)? Projeto na Vercel, domínio, projeto e plano do Supabase?
Preview com Supabase Branching ou projeto separado? Tem login, dado pessoal, pagamento,
upload, API paga? Nome, slug e versão inicial? Quem executa o QA? Posso me conectar à sua
conta da Vercel?   # e o agente confirma: pasta isolada do projeto
# e instala os plugins Vercel, Supabase, Chrome DevTools e Impeccable, do repositório original

3. A documentação é lida, não lembrada
nextjs.org · docs da Vercel · Supabase · OWASP · o .d.ts instalado  →  evidências com data

4. Uma spec, depois uma parada
specs/0001-controle-de-chamados.md. RF-001…RF-012, modelo de dados com índices,
políticas de RLS, rotas nomeadas, dados pessoais com finalidade, critérios de aceite
(dado/quando/então), nível de segurança, 31 casos
⛔ "Aprova e eu construo?"

5. Agora o vibecoding
Você constrói. Ela segura três linhas e sai da frente.

6. O código pronto é verificado
lint · tsc · testes · vercel build · npm audit · teste de RLS com a publishable key
· scan-secrets.sh · scan-sql-injection.sh · scan-linguagem.sh · scan-doc-sync.sh
· checklist de revisão · resumo do diff, arquivo por arquivo, para você ler
+ as sete perguntas adversariais ("qual linha deste diff eu atacaria primeiro?")

7. O roteiro de testes é gerado e executado no preview
Um caso por critério de aceite + um de SQL injection para CADA campo que chega ao banco
+ XSS + IDOR + CSRF + RLS pela API + Storage + upload + rotas + cabeçalhos
+ varredura de estranho: deslogado, outra conta, curl    # o Cowork executa

8. Versão, documentação, push, deploy
A matriz de documentos diz o que esta mudança obriga a atualizar; o commit sai sem
atribuição de IA (R18)
⛔ "Publicar v1.0.0?"   ⛔ "Promover para seu-dominio.com.br? Há 1 migração. Faço backup antes."

O núcleo

Dezoito regras inegociáveis

Elas passam por cima de qualquer outro instinto, inclusive "mas essa mudança é minúscula". Se uma não puder ser cumprida, o agente para e diz, nunca entrega uma versão degradada em silêncio.

R5

A regra que mais importa

SQL injection é a única falha desta lista que transforma um projeto pessoal em um incidente com dados de terceiros. Tem uma causa única: dado do usuário virando parte do texto do comando, seja SQL, seja o filtro que o cliente do Supabase manda para a API. E uma cura única.

// ❌ NUNCA. Nem "só nesse caso". Nem "o campo é numérico". Nem "é área logada".
await supabase.from('chamados').select().or(`titulo.ilike.%${busca}%,status.eq.${status}`);
await sql.unsafe(`SELECT * FROM chamados WHERE usuario_id = '${id}'`);
await sql.unsafe("DELETE FROM logs WHERE dia < '" + dia + "'");

// ✅ Cliente do Supabase: cada método tipado leva o valor separado da coluna.
const { data } = await supabase
  .from('chamados')
  .select('id, titulo, status')
  .eq('status', status)
  .ilike('titulo', `%${escaparLike(busca)}%`);   // o padrão é um valor, não um filtro

// ✅ SQL direto no servidor (driver `postgres`): a template tag vira $1, $2…
const pedidos = await sql`SELECT * FROM pedidos WHERE cliente_id = ${id}`;
const outros  = await sql.unsafe('SELECT * FROM pedidos WHERE cliente_id = $1', [id]);

O primeiro ❌ é o mais traiçoeiro: .or() recebe uma string de filtro do PostgREST (@supabase/postgrest-js 2.117.3, dist/index.d.cts:3328). Uma vírgula ou um parêntese na busca vira condição nova.

O caso difícil, o que não pode ser parametrizado: nome de coluna, nome de tabela, ASC/DESC. A resposta nunca é "concatena com cuidado". É allowlist, com a exceção declarada:

// ✅ O valor que chega do usuário é uma CHAVE, não um fragmento de SQL.
const COLUNAS = { nome: 'p.nome', data: 'p.criado_em', valor: 'p.total' } as const;
const ORDENS  = { asc: 'ASC', desc: 'DESC' } as const;

const coluna = COLUNAS[ordenarPor as keyof typeof COLUNAS] ?? 'p.criado_em';
const ordem  = ORDENS[direcao as keyof typeof ORDENS] ?? 'DESC';

// scan-sql:allow: coluna e ordem saem de COLUNAS/ORDENS
const texto = `SELECT * FROM pedidos p WHERE p.cliente_id = $1 ORDER BY ${coluna} ${ordem} LIMIT $2`;
const linhas = await sql.unsafe(texto, [id, limite]);

O scanner acusa toda interpolação em SQL. Para silenciá-la é preciso escrever o marcador citando a allowlist: na própria linha ou na linha imediatamente acima, onde cabe a justificativa por extenso. Isso transforma a exceção em algo visível na revisão, em vez de uma concatenação silenciosa. Com o cliente do Supabase a regra é a mesma: .order(coluna) recebe a coluna da allowlist, nunca o texto cru da URL.

R15

A URL é interface, não caminho de arquivo

É a única parte da aplicação que sai dela: vai para o histórico, os favoritos, o WhatsApp de quem compartilha, o índice do Google e o log do servidor. Por isso não pode ser um detalhe de implementação.

❌ https://seu-dominio.com.br/users/new
❌ https://seu-dominio.com.br/usuarios?acao=novo
✅ https://seu-dominio.com.br/cadastrar-novo-usuario

❌ https://seu-dominio.com.br/tickets/detail?id=8
✅ https://seu-dominio.com.br/chamados/8/impressora-nao-imprime

/users/new fala a língua do framework, não a de quem usa o app. /usuarios?acao=novo esconde a navegação numa query string que ninguém consegue ler, favoritar com sentido nem redirecionar quando a tela mudar.

app/
├── entrar/page.tsx                    → /entrar
├── cadastrar-novo-usuario/page.tsx    → /cadastrar-novo-usuario
├── not-found.tsx                      → 404 de verdade
└── (painel)/                          grupo: NÃO entra na URL
    ├── layout.tsx                     verifica a sessão do grupo
    ├── chamados/page.tsx              → /chamados
    └── chamados/[id]/page.tsx         → /chamados/8

Renomear uma pasta de rota é uma mudança MAJOR. Links publicados quebram, e você não controla quem os publicou. A antiga responde 301 por redirects() em next.config.ts por pelo menos uma versão maior, e a mudança entra no CHANGELOG. A referência traz o helper rota() que evita escrever a mesma URL duas vezes, a geração de slug, uma tabela de tradução de URLs antigas e os treze casos de teste que vão para o roteiro de QA.

R9

O app sobe do zero com três comandos

Um app pessoal costuma morrer no clone seguinte: ninguém lembra quais variáveis existem, qual SQL rodar e em que ordem, nem como criar o primeiro usuário. Ou sobe em produção e quebra na primeira requisição, com undefined onde devia haver a URL do Supabase. A R9 fecha as duas portas.

vercel env pull .env.local    # as variáveis do ambiente Development, do painel da Vercel
npm run db:migrate            # supabase db push: aplica supabase/migrations/ pendentes
npm run db:seed               # cria o administrador no Supabase Auth, se ainda não existir

1. lib/env.ts

   Validado na carga

   Toda variável passa por um esquema Zod. Faltou uma, o build quebra dizendo qual e onde configurar, em vez de o app subir e falhar em silêncio.

2. .env.example

   Todas listadas

   Cada variável com placeholder óbvio, como https://SEU-PROJETO.supabase.co. Nunca um valor que pareça funcionar.

3. db:migrate

   Schema por script

   supabase db push aplica as migrações pendentes, que o próprio banco registra em supabase_migrations.schema_migrations.

4. db:seed

   Administrador inicial

   Criado pelo Auth Admin API só se ainda não existir, com a senha vinda de variável e o papel em app_metadata. Nunca um admin/admin "para facilitar".

// ✅ falha cedo, com nome e endereço
import 'server-only';
import { z } from 'zod';

const Esquema = z.object({
  NEXT_PUBLIC_SUPABASE_URL: z.url(),
  NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: z.string().regex(/^(sb_publishable_|eyJ)/),
  SUPABASE_SECRET_KEY: z.string().regex(/^(sb_secret_|eyJ)/),   // nunca com NEXT_PUBLIC_
});

const resultado = Esquema.safeParse(process.env);
if (!resultado.success) {
  const faltando = resultado.error.issues.map((i) => i.path.join('.')).join(', ');
  throw new Error(`Variável ausente ou inválida: ${faltando}. Configure em Vercel → Settings → Environment Variables.`);
}

export const env = resultado.data;

// ✅ Auth Admin API, só quando o e-mail ainda não existe
await supabase.auth.admin.createUser({
  email,
  password: cfg.ADMIN_SENHA_INICIAL,                          // de variável, nunca fixa
  email_confirm: true,
  app_metadata: { papel: 'admin', deve_trocar_senha: true },  // nunca em user_metadata
});

O papel vai em app_metadata, que só o servidor altera: o user_metadata o próprio usuário edita, e política que confia nele deixa qualquer um se promover. Esqueletos prontos em env.ts.template, env.example.template, seed.ts.template e supabase-server.ts.template. Quem prefere o Supabase inteiro na própria máquina usa supabase start e npm run db:reset:local. O roteiro de QA ganha um caso que faz exatamente isto num clone limpo: se os três comandos não deixam o app funcionando, o release não sai.

R10

Migrações que sobrevivem ao rollback

O Instant Rollback da Vercel volta o código em segundos. O banco fica onde estava. Se a migração do release novo apagou a coluna que o código antigo lê, o rollback devolve um código que quebra procurando o que não existe mais.

1 PREVIEW   branch do Supabase Branching (ou projeto
            separado), nunca produção
2 BACKUP    backup conferido antes de tocar produção
3 MIGRAR    supabase db push (--dry-run antes),
            antes da promoção
4 PROMOVER  ⛔ com aprovação: merge em main
            ou vercel promote
5 VOLTAR?   vercel rollback: seguro, porque o
            schema ainda serve ao código anterior

npx supabase migration new adiciona_anexos
npx supabase db reset --local   # reaplica tudo, só local
npx supabase migration list     # o que já rodou
npx supabase db push --dry-run  # o que vai rodar
npx supabase db push

# ❌ apaga o banco REMOTO do projeto linkado
npx supabase db reset --linked

R11

Um roteiro de testes que o Cowork executa

Não é um resumo do que foi feito. É um procedimento: escrito para outro agente executar navegando pela aplicação, sem ter participado do desenvolvimento e sem poder fazer perguntas.

### CT-014. Filtrar chamados por status
| Requisito | RF-004 |
| Pré-condição | Logado como usuario.a@example.com. Seed: 3 abertos, 2 fechados. |

**Passos**
1. Acessar /chamados.
2. Conferir que [data-testid="tabela-chamados"] exibe 5 linhas.
3. Em [data-testid="filtro-status"], escolher Fechado.
4. Clicar em [data-testid="botao-filtrar"].

**Resultado esperado**
- A tabela exibe exatamente 2 linhas, ambas com status Fechado.
- [data-testid="contador-resultados"] exibe "2 chamados".
- A URL passa a conter ?status=fechado. Nenhum erro no console.

**Falha se**: a contagem diverge, aparece chamado com outro status, ou o filtro se perde.

R16

Build quebrado na Vercel, corrigido em ciclo fechado

Você pede, o agente se conecta à sua conta, acha o deploy que falhou, lê o log, corrige e empurra, e o CI/CD da Vercel publica a versão nova. O ciclo repete até o preview ficar verde. O que impede isso de virar empurra e reza são o passo 3 e o teto.

1 OBTER      identificar o deploy que falhou e baixar o LOG COMPLETO
2 LER        classificar: falha de CÓDIGO ou de AMBIENTE
3 REPRODUZIR vercel pull && vercel build   → a MESMA mensagem tem que aparecer
4 CORRIGIR   a menor mudança que resolve a causa raiz
5 PROVAR     vercel build + tsc + lint + testes + os scanners
6 EMPURRAR   UM push, no ramo de trabalho → deploy de preview
7 CONFIRMAR  verde? Se não, volta ao passo 1 com o NOVO log
8 PORTÃO     ⛔ merge em main (produção) só com aprovação

E o que ele nunca faz para ficar verde:

// ❌ proibido pela regra: o erro continua lá, agora invisível
export default {
  typescript: { ignoreBuildErrors: true },
};

// ✅ o build falha quando o código está errado, e o erro é corrigido
export default {};

No Next 15 a mesma amputação aparecia também como eslint: { ignoreDuringBuilds: true }. No Next 16 a chave eslint nem existe mais no tipo NextConfig, e o lint roda por eslint . no script do package.json.

Também proibidos: apagar o teste que falha, @ts-ignore num erro real, any para atravessar uma incompatibilidade, e commit vazio para reprocessar. Se a única saída for uma dessas, é decisão sua: o agente apresenta o trade-off e espera. O acesso é por servidor MCP da Vercel (detectado antes de perguntar), CLI com VERCEL_TOKEN ou API REST; o token vive em .env.local, com escopo mínimo, nunca versionado e nunca colado no chat.

R17

O texto é escrito na língua de quem usa

Para quem usa o sistema, o texto é o produto. A pessoa não vê a arquitetura, não vê o schema, não vê o SQL parametrizado. Ela vê "Não foi possível concluir a operação" e decide ali se confia ou não. Um botão escrito na língua errada custa mais suporte que um bug.

❌ O prazo é curto — três dias.          ✅ O prazo é curto: três dias.
❌ A conta — que estava ativa — foi encerrada.  ✅ A conta, que estava ativa, foi encerrada.
❌ Tente de novo — se persistir, avise.    ✅ Tente de novo. Se persistir, avise.
❌ Status — Aberto                       ✅ Status: Aberto

A segunda metade da regra é pesquisar o domínio antes de escrever a primeira frase de interface. Cada setor tem vocabulário próprio, expectativa de tom e, às vezes, obrigação legal sobre o que se pode dizer. Escrever "seu dinheiro sumiu" num app bancário e "chamado encerrado com sucesso!" num sistema de suporte são erros do mesmo tipo: linguagem que ignora a convenção de quem lê.

A skill não carrega dossiês de domínio, de propósito. Seria fácil listar o vocabulário de banco, de saúde, de suporte. Seria também um erro, pelo mesmo motivo que ela não vendoriza documentação de terceiros: um dossiê congelado envelhece parecendo autoritativo, e a existência dele convida o agente a pular a pesquisa, que é justamente a regra. O que a referência traz é o protocolo e as perguntas, não as respostas.

A terceira parte é tipográfica: corpo de texto justificado, com hyphens: auto e o idioma declarado no <html>. Justificar sem hifenizar é pior que não justificar, porque o navegador estica os espaços e abre corredores brancos no meio do parágrafo. Títulos, rótulos, código, listas curtas e colunas abaixo de 40 caracteres continuam alinhados à esquerda. Esta página segue a própria regra.

R13 · R18

A documentação envelhece junto com o código

Documentação desatualizada é pior que documentação ausente. A ausente você percebe, e vai ler o código. A desatualizada você acredita, e ela te leva ao lugar errado com confiança: um README que descreve o app de duas versões atrás faz alguém instalar do jeito que não funciona mais e concluir que o projeto está quebrado.

Por isso a regra é no mesmo commit, e não "antes do release". Se o commit que muda o comportamento não muda o texto que descreve o comportamento, os dois nunca mais se encontram. A cada modificação o agente reabre o inventário de documentos do projeto e decide quais merecem atualização, com uma matriz no lugar da memória. Esta é a versão curta, com as linhas mais comuns; a referência traz a matriz completa, a coluna do AGENTS.md, onde entram as armadilhas que você já descobriu no projeto, e uma segunda matriz para comentários, TSDoc e os documentos de docs/:

Código sem documentação não está concluído

A documentação faz parte da entrega, escrita para alguém que nunca viu o projeto, inclusive um iniciante, e explica o porquê: o código já mostra o quê. A profundidade acompanha o porte. Um script pequeno precisa de README e comentários; um sistema com API e banco, de tudo o que se aplica. Nenhum documento nasce vazio só para cumprir lista.

E o commit sai com o seu nome, só o seu

Ferramenta de IA costuma assinar o que ajuda a escrever: um Co-Authored-By no rodapé do commit, um "Generated with" no corpo do pull request, um link de sessão. Em projeto pessoal isso polui o histórico, aparece no git log de quem clonar e credita como coautor algo que não é autor de nada. A R18 corta em duas camadas, porque uma só não segura.

{
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

Isto não é sobre esconder que houve IA no processo. É sobre onde esse fato fica registrado. Contar na spec como o projeto foi construído é informação útil para quem vier depois. Carimbar uma ferramenta como coautora em cada commit é ruído permanente no histórico, e no seu repositório o autor é você.

R7

Segurança proporcional, mas nunca abaixo do piso

"É só um projeto pessoal" é o raciocínio que precede a maioria dos vazamentos de projeto pessoal. O invasor não sabe que é pessoal: ele varre faixas de IP procurando formulários de login.

Regra de escada: você pode subir de nível, nunca descer. Um app que começou N2 e passou a guardar CPF virou N3 no mesmo commit em que a coluna foi criada. A revisão humana de N3 e N4 é de uma pessoa que lê o diff, não de outra IA, e o nome dela fica na spec.

R12 · R4 · R1

O agente é uma ferramenta com poder

Um agente de código lê arquivos, roda comandos no seu terminal, instala pacotes e fala com a internet, com as suas credenciais. O código que ele escreve passa pelo checklist de revisão. O lugar onde ele roda, os comandos que ele pede e o texto que ele lê também precisam de regra.

# ❌ na pasta home: ele enxerga todos os projetos, ~/.ssh, ~/.aws, downloads
cd ~ && claude

# ✅ na pasta do projeto; tarefa em paralelo, um git worktree para cada
cd ~/projetos/controle-de-chamados && claude

Começar

Instalar e usar

A skill dispara sozinha quando você menciona Next.js, Vercel, Tailwind, Supabase, RLS, Postgres, LGPD, prompt injection, SQL injection, migração, rollback, variável de ambiente, rotas amigáveis ou roteiro de testes.

npx skills add adrianorafael/development-pattern-for-web-apps

claude plugin marketplace add adrianorafael/development-pattern-for-web-apps
claude plugin install development-pattern-for-web-apps@development-pattern-for-web-apps

git clone https://github.com/adrianorafael/development-pattern-for-web-apps.git
cp -r development-pattern-for-web-apps/skills/development-pattern-for-web-apps \
      .claude/skills/development-pattern-for-web-apps

"Faz um sistema de controle de chamados
 em Next.js pra eu publicar na Vercel."

bash .../scan-secrets.sh
bash .../scan-sql-injection.sh
bash .../scan-linguagem.sh
bash .../scan-doc-sync.sh

Conteúdo

O que vem na caixa

Um SKILL.md, 18 referências carregadas sob demanda, 26 templates e quatro scanners, e nenhuma cópia da documentação de terceiros.

├── SKILL.md                          # 18 regras, 8 fases, 3 portões, roteamento
├── references/
│   ├── segredos-e-configuracao.md    # R1: .env, variáveis da Vercel, chaves do Supabase
│   ├── git-e-publicacao.md           # R2, R18: privado por padrão, commits, lockfile
│   ├── fluxo-spec-driven.md          # R3: fases, portões, anatomia da spec
│   ├── protocolo-de-verificacao.md   # R4: fontes, pacotes antes de instalar
│   ├── sql-e-acesso-a-dados.md       # R5: cliente do Supabase, $1, LIKE, RLS, .rpc()
│   ├── entrada-e-saida-seguras.md    # R6: validação, escape, CSRF, Storage, traversal
│   ├── linha-de-base-de-seguranca.md # R7: piso de 14 itens, N1 a N4, LGPD, OWASP
│   ├── stack-nextjs-vercel.md        # R8: App Router, Server Actions, proxy.ts, Tailwind
│   ├── bootstrap-do-ambiente.md      # R9: lib/env.ts, .env.example, Supabase CLI, seed
│   ├── migracoes-e-rollback.md       # R10: expand → migrate → contract, Branching, backup
│   ├── roteiro-de-testes-cowork.md   # R11: as seis suítes, payloads, rastreabilidade
│   ├── checklist-de-revisao.md       # R12: checklist + 7 perguntas adversariais
│   ├── agentes-e-ferramentas-de-ia.md # R12: pasta isolada, comandos, prompt injection
│   ├── documentacao-do-projeto.md    # R13: inventário e matriz mudança → documento
│   ├── release-e-deploy.md           # R13, R14: SemVer, CHANGELOG, promoção, rollback
│   ├── rotas-e-urls.md               # R15: convenções, pastas, 301, 404, tradução
│   ├── vercel-build-e-correcao.md    # R16: conectar, ler log, reproduzir, corrigir
│   └── linguagem-e-texto-da-interface.md # R17: domínio, travessão, microcopy, tipografia
└── assets/
    ├── templates/                    # 26: env.ts, supabase-server.ts, proxy.ts, seed.ts,
    │                                 #   schema, políticas RLS, migração, dependabot,
    │                                 #   next.config.ts, hooks, spec, roteiro, e os
    │                                 #   docs/ de arquitetura, decisão, segurança, banco, API
    └── scripts/                      # scan-secrets.sh · scan-sql-injection.sh
                                      #   · scan-linguagem.sh · scan-doc-sync.sh

Ajuda

Respostas honestas