Files

T

João Henrique b2a8b1f24c feat: criado repositório jhonny-editor no Gitea

criado repositório jhonny-editor no Gitea
adicionado script admin/deploy.command com commit automático
atualizado admin/DEV-NOTES.md com template limpo

Resumo:
- 8 arquivos alterados
- 2 novos
- 6 modificados
- 0 removidos

 6 files changed, 33 insertions(+), 3 deletions(-)

Arquivos:
  - .agents/skills/boas-praticas-oo/SKILL.md
  - .claude/settings.json
  - AGENTS.md
  - CLAUDE.md
  - CODING_STANDARDS.md
  - code/engine/executar_scanner.py
  - .claude/hooks/
  - code/engine/testes/test_executar_scanner.py

2026-09-08 17:19:03 -04:00

4.5 KiB

Raw Permalink Blame History

Padrões de código

Este documento consolida as convenções obrigatórias de código do projeto. Serve de fonte de verdade para revisões automáticas (eixo Standards do /code-review) e vale para qualquer agente que escreva ou altere código.

A fonte completa das regras de orientação a objeto é a skill .agents/skills/boas-praticas-oo/SKILL.md. O que está abaixo é o resumo normativo; em caso de dúvida, leia a skill por inteiro.

Escopo

As regras de PT-BR e OO aplicam-se a todo Python em code/engine/. Outras linguagens seguem as convenções existentes no repositório, mas os princípios de design (responsabilidade única, baixo acoplamento, injeção de dependência, módulos profundos) são universais.

Idioma — PT-BR obrigatório

Todos os identificadores internos usam português brasileiro:

Classes, métodos, funções, variáveis, atributos, parâmetros, constantes, arquivos, pastas e módulos.
Docstrings, comentários, logs, mensagens de erro e documentação.
Nomes de testes, fixtures e exemplos.

Identificadores externos (bibliotecas, APIs, endpoints, campos de contrato, variáveis de ambiente de terceiros, protocolos) são preservados no idioma oficial somente quando exigidos, e isolados em adaptadores/conversores/clientes/repositórios. Não espalhar nomes externos pelo sistema; converter na fronteira para o modelo interno em PT-BR e documentar a exceção.

Nomenclatura

Classes: PascalCase — ex. GerenciadorDeArquivos.
Métodos, funções, variáveis, atributos, arquivos e pastas: snake_case — ex. carregar_arquivo, nome_do_usuario.
Constantes: MAIÚSCULAS_COM_SUBLINHADO — ex. TEMPO_LIMITE_DA_OPERACAO.
Evitar nomes genéricos: Util, Helper, Manager, Processor, Data, Object, Thing, Temp.

Documentação

Todo módulo tem docstring no topo: finalidade, problema que resolve, responsabilidade, o que não faz, componentes e dependências principais.
Toda classe tem docstring: o que representa, responsabilidade, dependências, o que não deve fazer, efeitos colaterais quando aplicável.
Todo método/função público tem docstring: o que faz, dados que recebe, retorno, erros possíveis, se altera estado, se realiza operações externas.
Documentação viva: docstring/comentário deve descrever o comportamento atual. Proibido manter documentação de comportamento que não existe mais.

Design / orientação a objeto

Responsabilidade única: cada classe/função/módulo tem uma responsabilidade principal.
Alta coesão: métodos da classe relacionam-se à sua responsabilidade.
Baixo acoplamento: depender do mínimo; receber dependências, não criá-las internamente.
Composição antes de herança; herança apenas com relação real de "é um".
Encapsulamento: dados e regras protegidos, alterados por operações apropriadas.
Interfaces pequenas e injeção de dependências explícita.
Métodos pequenos e objetivos; retornos previsíveis e consistentes.
Módulos profundos: muita funcionalidade atrás de interface pequena (ver skill codebase-design).

Domínio e integrações

Regras de negócio ficam no domínio/aplicação, nunca na interface, em controladores gigantes, scripts, SQL, HTTP ou camada de apresentação.
Integrações externas (APIs, banco, arquivos, serviços) isoladas em módulos próprios; o resto do sistema usa contratos/classes internas.
Não duplicar regras: centralizar em classe, função, validador, objeto de valor ou constante.
Evitar dependências circulares; resolver com contratos, módulo comum, inversão ou injeção de dependência.

Erros e segurança

Tratar erros com exceções específicas; nunca except Exception: pass.
Validar toda entrada externa (tipo, formato, limites, nulos, estrutura) antes de usar.
Não registrar senhas, tokens, chaves ou dados sensíveis em logs.
Configurações em componentes próprios, não espalhadas no código.

Testes

Toda funcionalidade relevante tem testes (unitário, integração, regressão).
Cobrir: entradas válidas/inválidas, casos vazios/extremos, erros, retornos, efeitos colaterais, regras de negócio.
Ao corrigir bug, criar/atualizar teste que impeça regressão.

Checklist antes de finalizar

Antes de dar como concluída qualquer implementação Python em code/engine/, percorrer a seção 41 da skill boas-praticas-oo.md: requisitos, arquitetura, código, documentação e testes.

4.5 KiB Raw Permalink Blame History