# Padrões de Desenvolvimento — Mud Sentinel

**Documento:** `engenharia/01-padroes-de-desenvolvimento.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Princípios de engenharia

1. **Corretude e auditoria antes de esperteza.**
2. **Legibilidade > originalidade.**
3. **Mudanças pequenas e reversíveis.**
4. **Tudo que for crítico é testado automaticamente.**
5. **Decisões relevantes vão para ADR ou ticket linkado.**

---

## 2. Fluxo de trabalho Git

| Prática | Padrão |
|---------|--------|
| Branching | Trunk-based com short-lived branches (`feat/`, `fix/`, `chore/`, `docs/`) |
| Commits | Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `security:`) |
| PR | Obrigatório; ≥1 review; CI verde |
| Main | Protegida; sem force-push |

**Justificativa:** histórico auditável alinha com cultura de compliance do produto.

---

## 3. Qualidade de código

### Backend (Python)

- Type hints em APIs públicas de módulo.
- `ruff` (lint/format) + `mypy` (strict progressivo nos módulos core).
- Sem `except:` nu; erros de domínio tipados.
- Sem I/O em entidades de domínio.

### Frontend (TypeScript)

- `strict` no TypeScript.
- ESLint + Prettier (ou formatter padrão do repo).
- Componentes focados; estado de servidor preferir padrões do Next.js adotados pelo time.
- Acessibilidade mínima (labels, teclado) em fluxos P0.

---

## 4. API design

- RESTful JSON como padrão; OpenAPI como contrato.
- Versionamento por URL ou header (ver [Versionamento](04-versionamento.md)).
- Erros problem+json ou envelope consistente (escolher um via ADR e manter).
- Paginação cursor-based para listas grandes.
- Idempotency-Key em POSTs críticos (pagamentos, exports).

---

## 5. Banco e persistência

- Migrações apenas forward-first em produção; down scripts só para dev.
- Toda tabela de negócio com `tenant_id` quando aplicável.
- Soft delete consciente (quando necessário) + trilha; não usar soft delete para “esconder” auditoria.
- Índices justificados por query real / EXPLAIN.

---

## 6. Segurança no desenvolvimento

- Threat modeling leve em features P0 de auth, export, multi-tenant e IA.
- Sem segredos em código; scanners no CI.
- Dependabot/renovate com política de merge.
- Review obrigatório em mudanças de `iam`, `audit`, `billing`, `tenancy`.

---

## 7. IA no desenvolvimento e no produto

- Código gerado por IA passa pelos mesmos gates (review, testes, boundaries).
- Prompts de produto versionados; não “string solta” em componentes.
- Saídas de IA nunca writeiam decisões irreversíveis sem trilha e política.

---

## 8. Code review — checklist mínimo

- [ ] Boundaries de módulo respeitados
- [ ] Autorização no application boundary
- [ ] Auditoria se ação sensível
- [ ] Testes adequados ao risco
- [ ] Sem PII em logs
- [ ] Feature flag/entitlement se aplicável
- [ ] Docs/ADR se decisão estrutural

---

## 9. Definition of Done

Uma história só está Done quando:

1. Código + testes no trunk.
2. Observabilidade básica (log/metric) se novo caminho crítico.
3. Documentação de usuário ou runbook se mudança operacional.
4. Sem TODO crítico sem ticket.

---

## 10. O que evitar

- Micro-otimizações sem medição.
- Abstrações especulativas (“vai precisar um dia”).
- Compartilhar models ORM entre contextos.
- Desabilitar linters/CI por pressão de prazo sem registro de risco.