01Arquivo

padroes-projeto.md

Padrões de projeto

Git, pré-commit, CI, deploy, banco, variáveis, seeds e documentação. Pensado para Next.js com PostgreSQL, adaptável a outra stack.

Voltar para skills

Padrões de projeto

Como montar e manter um projeto: idioma, git, pré-commit, CI, deploy, banco, variáveis de ambiente, usuário master, seeds e documentação. Vale para todo projeto novo; o que é de um projeto (domínio, servidor, nomes) fica no README.md e no CLAUDE.md dele.

Stack mais comum: Next.js (App Router) e TypeScript, PostgreSQL com Prisma, Supabase (Auth, banco e Storage), Untitled UI, Docker numa VPS atrás de nginx e GitHub Actions. Ela muda de projeto para projeto: banco, autenticação e hospedagem podem ser outros. As regras de banco valem para qualquer PostgreSQL; as que são só do Supabase dizem isso.

Idioma

  • Código em inglês: variáveis, funções, tipos, arquivos, pastas, rotas internas e comentários.
  • Banco em inglês: models, tabelas, colunas, enums e policies.
  • Só o que o usuário final lê fica no idioma da aplicação: interface, mensagens de erro e de validação, e-mails e notificações.
  • Conversa, README.md, documentação e mensagens de commit no idioma do time.

Documentação

  • O README.md da raiz é a fonte de verdade do projeto: estado atual, como rodar, banco, produção, variáveis e comandos. Ao mudar requisitos, portas, comandos, variáveis ou deploy, ele é atualizado na mesma alteração, com fatos conferidos nos scripts e no código.
  • Toda pasta docs/ tem, criados no início e mantidos em dia:
    • roadmap.md: o que o produto precisa ser, em checklists por fase (e por etapa, numa jornada), publicado como página;
    • produto.md: glossário, regras de negócio e registro datado das decisões, com o porquê;
    • design.md: decisões de interface, atualizado na mesma alteração do código (parte 1, padrões gerais; parte 2, o projeto);
    • concorrentes.md: análise dos concorrentes e do posicionamento;
    • migrations.md: cada migration, o que muda no schema e o SQL manual que ela traz;
    • deploys.md: cada push, com data, hora local, commit, resultado e duração do deploy;
    • gotchas.md: armadilhas confirmadas, que economizariam tempo no futuro, com a data.
  • O CLAUDE.md do projeto diz o que é o projeto, as regras que o agente segue nele e importa o docs/design.md e o docs/migrations.md.
  • Projeto de cliente é descrito como o sistema do cliente, sem linguagem de template.

Git

  • Mensagem no padrão tipo(escopo): descrição (feat, fix, docs, chore...), com o corpo listando o que mudou.
  • Nunca pular o hook de pré-commit (--no-verify ou outra forma). Se ele falhar, corrigir a causa.

Pré-commit, CI e deploy

Prioridade: deploy rápido e seguro, sem analisar arquivo desnecessário. Cada etapa verifica uma coisa só.

  • Pré-commit (obrigatório): husky + lint-staged, só nos arquivos staged. O prettier formata; o lint só aponta, sem --fix.
  • CI (depois do push): compara com o último commit publicado com sucesso, não com o push anterior, para um push que falhou não ser publicado sem verificação pelo seguinte.
    • Mudou dependência, config, schema, Dockerfile ou o próprio workflow: lint e typecheck no projeto inteiro.
    • Mudou só código: lint nos arquivos alterados e typecheck.
    • Também reprova nome de migration fora do padrão.
  • Push só de docs (*.md, docs/, .claude/) não dispara o workflow. Exceção: arquivo que entra no build (ex.: o docs/roadmap.md da página do roadmap), liberado com paths e !.
  • Deploy: publica só commit aprovado no CI; gera a imagem Docker, aplica as migrations antes de trocar a imagem (migration que falha barra o deploy), envia para a VPS, que volta para a imagem anterior se o container não ficar saudável. Só termina com sucesso quando o health check responde com o commit publicado.
  • Health check em /api/health: { "status": "ok", "commit": "<sha>" }.
  • Chave de deploy limitada a um comando só no authorized_keys da VPS (command="...",restrict).
  • Depois de cada push: acompanhar o workflow e registrar a linha em docs/deploys.md (push só de docs entra como "sem deploy"). A linha vai no commit seguinte.
  • Nunca usar db push --accept-data-loss em produção como alternativa a uma migration que falhou.

Hospedagem

  • Docker numa VPS compartilhada, com o container publicado só em 127.0.0.1 e o nginx do host na frente.
  • DNS com @, www e * apontando para a VPS; certificado do domínio e do curinga (*.dominio), renovado pelo certbot com token de DNS exclusivo do projeto.
  • www redireciona (308) para o domínio principal, para a sessão ficar num endereço só.
  • Subdomínios de apoio (design., roadmap.) e de clientes resolvidos pelo app; o nginx só libera os que existem. Antes de editar server_name com sed, conferir com grep se o nome já está lá.
  • Comandos contra produção (SSH, scripts com chaves de produção) são passados para o dono do projeto rodar com !.

Banco de dados

  • O Prisma é dono do schema e das migrations. Nada é alterado pelo painel do provedor do banco (Supabase, Neon, RDS...) ou por outro caminho.
  • Policies RLS, triggers e funções entram em SQL dentro das migrations.
  • Nome das migrations: NNNN-AAAA-MM-DD-descricao-em-kebab-case.sql, como arquivo solto em prisma/migrations/, sem pasta.
    • NNNN: sequencial com 4 dígitos, continuando do último.
    • AAAA-MM-DD: data de criação.
    • Descrição curta em inglês, começando pela ação (create-, add-, drop-, split-...).
    • Exemplo: 0060-2026-10-09-add-status-to-leads.sql.
  • O Prisma exige <nome>/migration.sql, então os scripts montam esse formato numa pasta fora do git antes de chamá-lo. Comandos de migration sempre pelos scripts (npm run db:migrate -- <descricao>, npm run db:deploy), nunca npx prisma migrate direto.
  • Migration aplicada não é editada: correção vira migration nova. Toda migration ganha uma entrada em docs/migrations.md na mesma alteração.
  • Duas conexões: a do app (DATABASE_URL) usa uma role sem BYPASSRLS e que não é dona das tabelas; a administrativa (DIRECT_URL, role dona) fica restrita a migrations e scripts.
  • Toda query de usuário roda numa transação que define a identidade e o contexto ativo, para as policies lerem. Nada de query sem esse contexto.
  • RLS se testa com duas conexões: dados gravados com a administrativa, consulta com a do app.
  • Com Supabase, a Data API não é usada: as migrations retiram o acesso de anon e authenticated ao schema public.

Variáveis de ambiente

  • .env e .env.example com a mesma estrutura: mesmas variáveis, na mesma ordem e nos mesmos grupos. Só os valores mudam. Ao mexer num, mexer no outro.
  • Arquivos enxutos: variáveis agrupadas por assunto, comentários curtos só onde ajudam, nenhuma variável sem uso.
  • O .env é a fonte das chaves: toda chave de serviço externo entra no .env, no .env.prd e, vazia, no .env.example, mesmo que por enquanto só seja usada num painel. Chave nunca é pedida no chat: o dono cola o valor direto no arquivo.
  • Valores de produção no .env.prd local, fora do git. Nunca .env.production, que o Next carregaria nos builds locais.
  • Cada variável aparece numa tabela do README.md, dizendo onde é usada.
  • Onde fica cada chave: o README.md tem uma seção que diz, para cada chave, onde ela está: os arquivos locais (.env, .env.prd), o servidor (o .env da VPS ou do container), o CI (variables e secrets do GitHub) e os painéis externos onde ela nasce (provedor do banco, provedor de e-mail, gateway de pagamento, DNS). Inclui as chaves que não são variáveis do app (chave SSH do deploy, token de DNS do certificado). Conferida pelos nomes, nunca pelos valores (gh secret list, gh variable list, os nomes do .env do servidor), e atualizada na mesma alteração que cria, move, troca ou remove uma chave. Serve para quem chega ao projeto (outra pessoa do time, a liderança técnica) saber onde mexer sem perguntar.
  • Toda variável que o app lê em produção também entra no arquivo que leva o ambiente ao container (compose.yml ou equivalente): estar no .env do servidor não basta.
  • Variável NEXT_PUBLIC_* entra na imagem no build: trocar o valor exige novo deploy.

Usuário master

  • Todo projeto com login tem um usuário master (admin inicial), vindo de MASTER_EMAIL e MASTER_PASSWORD.
  • E-mail do domínio do projeto (ex.: admin@seudominio.com.br). A senha nunca tem valor padrão no código: cada ambiente define a sua, e no .env.example ela fica vazia.
  • Em produção, o script de criação exige senha forte (pelo menos 12 caracteres) e se recusa a seguir sem ela.

Seeds

  • São completos e deixam o sistema utilizável e demonstrável: dados realistas em todas as entidades principais e nos relacionamentos, com arquivos e mídias (avatares, anexos, logos) quando o projeto precisar.
  • Ligados e desligados por SEED_ENABLED=true|false, documentado no .env.example e desligado por padrão em produção.

Detalhes fixos de todo projeto

  • Commit curto no canto das telas logadas e do login, vindo de GIT_SHA em produção e do git local em desenvolvimento.
  • npm run dev mostra um rodapé com os endereços úteis (app, subdomínios de apoio, health, rede).
  • Referência a projeto antigo (<projeto>-old) serve só para regras e decisões, nunca para copiar código ou estrutura sem avaliar.