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.mdda 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.mddo projeto diz o que é o projeto, as regras que o agente segue nele e importa odocs/design.mde odocs/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-verifyou 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.: odocs/roadmap.mdda página do roadmap), liberado compathse!. - 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_keysda 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-lossem produção como alternativa a uma migration que falhou.
Hospedagem
- Docker numa VPS compartilhada, com o container publicado só em
127.0.0.1e o nginx do host na frente. - DNS com
@,wwwe*apontando para a VPS; certificado do domínio e do curinga (*.dominio), renovado pelo certbot com token de DNS exclusivo do projeto. wwwredireciona (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 editarserver_namecomsed, conferir comgrepse 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 emprisma/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), nuncanpx prisma migratedireto. - Migration aplicada não é editada: correção vira migration nova. Toda migration ganha uma entrada
em
docs/migrations.mdna mesma alteração. - Duas conexões: a do app (
DATABASE_URL) usa uma role semBYPASSRLSe 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
anoneauthenticatedao schemapublic.
Variáveis de ambiente
.enve.env.examplecom 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.prde, 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.prdlocal, 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.mdtem uma seção que diz, para cada chave, onde ela está: os arquivos locais (.env,.env.prd), o servidor (o.envda 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.envdo 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.ymlou equivalente): estar no.envdo 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_EMAILeMASTER_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.exampleela 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.examplee 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_SHAem produção e do git local em desenvolvimento. npm run devmostra 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.