Código de nível internacional. Todos os produtos.

Os 7 Mandamentos

Princípio vs Decisão de Stack

Separamos o que é permanente do que pode mudar com a tecnologia.

OWASP Top 10 — Checklist Obrigatório OWASP 2025

Cada item deve ser verificado antes de qualquer PR que toque autenticação, pagamentos ou acesso a dados.

• Broken Access Control — RBAC implementado, princípio do menor privilégio, default-deny em todas as rotas
• Injection Prevention — Queries parametrizadas sempre. Zero concatenação de strings em SQL/NoSQL
• Cryptographic Failures — TLS em toda comunicação, dados sensíveis criptografados at rest, bcrypt/argon2 para senhas
• Security Misconfiguration — Headers de segurança (CSP, HSTS, X-Frame-Options), defaults seguros, features não usadas desabilitadas
• Vulnerable Components — Dependabot/Snyk ativo, lock files commitados, SBOMs gerados
• Auth & Session — MFA disponível, tokens com expiração, refresh token rotation
• SSRF Prevention — Validar e sanitizar todas as URLs recebidas de usuários
• Logging de Segurança — Log de tentativas de auth, acessos negados, mudanças de permissão

Secrets Management

Headers de Segurança Obrigatórios

Incident Response

SLA de Correção por Severidade

Rotação de Secrets

Threat Modeling

Toda feature que toca autenticação, pagamentos ou dados sensíveis passa por threat modeling antes do desenvolvimento.

Checklist de Segurança por Tipo de Mudança

Privacy by Design — 7 Princípios ISO 31700

• Proativo, não reativo — Privacidade pensada desde o design, não como patch
• Privacidade como padrão — Dados protegidos por default, sem exigir ação do usuário
• Privacidade no design — Integrada na arquitetura, não adicionada depois
• Funcionalidade total — Sem trade-off privacidade vs funcionalidade
• Segurança fim-a-fim — Proteção durante todo o ciclo de vida do dado
• Transparência — Usuário sabe o que é coletado, por quê e por quanto tempo
• Respeito ao usuário — Usuário no controle dos seus dados

Direitos do Titular (LGPD Art. 18)

Todo produto LZR deve implementar endpoints ou interfaces para estes direitos:

Data Mapping Obrigatório

Matriz de Classificação de Dados

Conventional Commits Obrigatório

Branch Strategy

Code Review Checklist

• PR tem descrição clara do que mudou e por quê
• Testes adicionados ou atualizados para a mudança
• Sem secrets, tokens ou dados sensíveis no diff
• Sem console.log ou debuggers esquecidos
• Queries SQL parametrizadas (sem concatenação)
• Error handling adequado (sem catch vazio)
• Tipos definidos (sem any em TypeScript)
• Performance: sem N+1 queries, sem loops desnecessários

Definition of Done

Naming Convention OpenAPI 3.1

Error Response Format RFC 9457

Paginação — Cursor-based (preferido)

Rate Limiting

Migrations Obrigatório

• Toda mudança de schema via migration versionada (nunca SQL manual em produção)
• Migrations são imutáveis — nunca editar uma migration já aplicada
• Backward-compatible: expand-and-contract para breaking changes
• Migrations rodam automaticamente no pipeline de deploy
• Testar rollback de toda migration antes de aplicar em produção

Multi-tenant Isolation

Performance Checklist

Naming Conventions Obrigatório

Migrations — Nomenclatura Sequencial Obrigatório

Pipeline Stages DORA Metrics

DORA Metrics — Targets

12-Factor App — Princípios Chave

Assinatura e Proveniência de Artefatos

• Build reproduzível — Mesmo commit gera mesmo artefato. Lock files commitados, versões fixas.
• Assinatura de imagens — Docker images assinadas via cosign/sigstore antes do push ao registry.
• SBOM (Software Bill of Materials) — Gerado automaticamente no pipeline. Anexado ao release.
• Proveniência — Metadados de build (quem, quando, de qual commit) registrados no artefato.

Três Pilares OpenTelemetry

Structured Logging — Formato Padrão

Padrões de Resiliência

Cobertura Mínima por Tipo

OWASP LLM Top 10 OWASP LLM 2025

• Prompt Injection — Separar system prompt de user input. Validar e sanitizar input. Filtrar output.
• Sensitive Data Disclosure — Nunca enviar PII no prompt. Mascarar dados antes de enviar ao LLM.
• Excessive Agency — IA nunca executa ações destrutivas sem confirmação humana. Princípio do menor privilégio.
• Unbounded Consumption — Limite de tokens por request. Rate limit por usuário. Cost caps por feature.
• Output Validation — Validar schema do output do LLM antes de agir. Nunca confiar cegamente.
• System Prompt Leakage — Proteger system prompts de extração via prompts adversários.

Cost Control

Prompt Lifecycle & Versioning

Eval Sets & Regression Testing

Toda feature de IA tem um eval set associado — conjunto de inputs com outputs esperados para medir qualidade.

Red-Team & Segurança de IA

• Prompt injection suite — Testes automáticos de tentativas de injection (DAN, jailbreak, role-play)
• Data extraction tests — Verificar que system prompt e dados internos não vazam
• Hallucination detection — Comparar output com fonte de verdade quando disponível
• Bias testing — Verificar fairness em outputs que afetam decisões (classificação de licitações)

Classificação de Risco por Feature

Human-in-the-Loop Policy

Grounding & Retrieval Standards

• RAG obrigatório — Para features que dependem de dados atualizados, usar Retrieval-Augmented Generation
• Citação de fontes — Output do LLM deve referenciar documentos fonte quando disponíveis
• Freshness — Dados do RAG com timestamp. Alertar usuário se dados > 24h

Rollout de Modelos

Regras Fundamentais

• Zero hardcoded strings — Toda string visível ao usuário vem de arquivo de tradução
• UTF-8 everywhere — Banco, API, frontend, arquivos. Sem exceção
• Timezone: UTC no banco — Armazenar tudo em UTC. Converter para local apenas na exibição
• Intl API — Usar Intl.NumberFormat, Intl.DateTimeFormat para formatação locale-aware
• Pluralização — Usar ICU MessageFormat. "1 licitação" vs "5 licitações" por locale
• Text expansion — UI deve acomodar textos 30-40% maiores (alemão, finlandês)

Formatação por Locale

WCAG 2.2 AA — Checklist WCAG 2.2

• HTML Semântico — Usar headings corretos (h1-h6), landmarks (nav, main, aside), labels em forms
• Navegação por teclado — Todo elemento interativo acessível via Tab. Focus indicators visíveis.
• Contraste — 4.5:1 para texto normal. 3:1 para texto grande. Verificar em ambos os temas.
• Alt text — Todas as imagens informativas têm alt descritivo. Decorativas têm alt="".
• Cor não é único indicador — Status usa cor + ícone + texto. Nunca só cor.
• Touch targets — Mínimo 44x44px em mobile. Sem exceção.
• Focus Not Obscured — Elemento focado nunca escondido por sticky headers ou modals.
• Accessible Auth — Login não depende de cognitive function tests (CAPTCHA visual).

Alertas de Budget

Checklist FinOps

• Tag everything — Todo recurso cloud tagado com: environment, service, team
• Right-sizing mensal — Revisar CPU/memória/storage. Downsizar recursos ociosos.
• Ambientes não-prod — Desligar staging/dev fora do horário comercial
• LLM costs — Maior centro de custo. Monitorar por feature. Cache agressivo.
• Cost per tenant — Rastrear custo por cliente. Garantir unit economics positivo.
• Log retention — Não guardar tudo por 90 dias. Hot: 7d, Warm: 30d, Cold: 90d.

Diátaxis Framework Diátaxis

Toda documentação LZR segue o framework Diátaxis — 4 tipos distintos, cada um com propósito diferente.

ADRs (Architecture Decision Records)

Documentação Obrigatória por Repositório

• README.md — O que faz, como rodar, como deployar. Dev novo produtivo em <1 dia.
• CHANGELOG.md — Semver. O que mudou em cada versão.
• .env.example — Todas as env vars com descrição e valor de exemplo.
• docs/adrs/ — Decisões arquiteturais documentadas.
• docs/runbooks/ — Como deployar, como fazer rollback, como responder incidentes.
• API docs — Auto-gerada via OpenAPI spec. Sempre em sync com o código.

TSConfig — Strict Mode Obrigatório

Organização de Pastas — Feature-based

Naming Conventions

Padrões Obrigatórios

• Zod para validação — Schema validation em todo input externo (API, forms, env vars)
• Result pattern — Para operações que podem falhar, retornar { success, data, error } em vez de throw
• Barrel exports — Cada feature tem um index.ts que exporta a API pública
• Dependency injection — Services recebem dependências via construtor, não import direto

App Router — Padrão LZR Next.js 14+

Padrões de Componentes

• Server Components por padrão — Só usar 'use client' quando precisa de interatividade (state, effects, event handlers)
• Co-location — Componente, types, tests e stories no mesmo diretório
• Props tipadas — Toda prop com tipo explícito. Sem any. Sem props spreading desnecessário.
• Composição sobre herança — Usar children, render props e composition patterns

Estado & Data Fetching

Performance Frontend

• Core Web Vitals — LCP < 2.5s, FID < 100ms, CLS < 0.1. Monitorar em produção.
• Bundle size — Revisar com @next/bundle-analyzer. Lazy load para routes e componentes pesados.
• Imagens — Sempre usar next/image. WebP/AVIF automático. Sizes definidos.
• Memoization consciente — useMemo/useCallback só quando há problema medido. Não otimizar prematuramente.

Stack Base

Regras Mobile-Specific

• Offline-first — App funciona sem internet. Sync quando conectar. Feedback claro de status.
• Deep linking — Toda tela acessível via URL scheme. Configurado no Expo Router.
• Biometria — Usar expo-local-authentication. Fallback para PIN.
• Push notifications — Via Expo Notifications. Permissão solicitada no momento certo, não no primeiro launch.

SLOs & Error Budget

Política de Incidentes

RTO & RPO

Disaster Recovery — Checklist

• Backup testado — Restore de backup testado trimestralmente. Resultado documentado.
• Runbook atualizado — Procedimento de DR revisado a cada 6 meses. Acessível offline.
• Multi-region aware — Saber o que acontece se a região do Supabase cai. Plano B documentado.
• Postmortem obrigatório — Todo SEV-1 e SEV-2 gera postmortem blameless em 48h.

Decisões Arquiteturais Vigentes

Boundaries & Contratos

• API como contrato — Comunicação entre serviços sempre via API documentada. Zero acesso direto ao banco de outro serviço.
• Schema validation na fronteira — Zod valida todo input na borda do sistema. Dentro, tipos são confiáveis.
• Versionamento de API — Prefixo /api/v1/. Nova versão major só com ADR e plano de migração.
• Depreciação — Endpoint deprecated fica ativo por mínimo 90 dias com header Sunset.

CODEOWNERS Obrigatório

Branch Protection Rules

Templates Obrigatórios

Repo Scaffold — Arquivos Obrigatórios

• .github/CODEOWNERS — Ownership por área
• .github/pull_request_template.md — Template de PR
• .github/ISSUE_TEMPLATE/ — Templates de issue (bug, feature, ai-spec)
• .github/workflows/ — CI/CD pipelines
• .env.example — Todas env vars documentadas
• README.md — Setup em <30min para dev novo
• CHANGELOG.md — Semver, auto-gerado por conventional commits