Comentários e documentação

Quando comentar

• Regras de negócio não óbvias (ex.: cálculo de comissão, janela de cutoff).
• Workarounds temporários: incluir ticket Organiza e data prevista de remoção.
• Integrações externas: URL, contrato, limites de rate.

Quando não comentar

• Código que repete o óbvio (// incrementa i).
• Código morto comentado — apague; o Git guarda histórico.

Documentação no repositório

• Mudanças de API, permissões ou schema: atualizar docs/ do próprio projeto quando aplicável.
• Documentação central (este site): roda npm run sync-docs no repositório DOCUMENTACAO_GEVTECH após merge.

ADR e decisões

Decisões arquiteturais relevantes: preferir pasta docs/adr/ ou equivalente no produto, com contexto, decisão e consequências.