princípios-de-engenharia

Habilidade de codificação. Aplica princípios fundamentais de engenharia de software e a filosofia Unix ao implementar funcionalidades, corrigir bugs, projetar módulos ou APIs, refatorar ou revisar código. Use especialmente para decisões sobre simplicidade, abstração, duplicação, acoplamento, contratos, testes, dependências, desempenho, ferramentas CLI e componibilidade. Transforme princípios em tradeoffs concretos e mudanças verificadas, não em listas de verificação rituais. Não se destina a edições apenas de prosa ou tarefas não relacionadas a codificação.

O que é princípios-de-engenharia?

Este skill orienta assistentes de IA a aplicarem princípios fundamentais de engenharia de software de forma pragmática e contextual, indo além de checklists rituais. Ele estabelece um ciclo de trabalho de 5 passos (estabelecer contrato, escolher design proporcional, mudar uma preocupação por vez, verificar comportamento prometido, finalizar a mudança) que se escala conforme o risco da alteração. O skill enfatiza debugging baseado em evidências, workflow alinhado ao repositório existente e a documentação concisa de contribuidores. Nas decisões de design, o skill aborda correção via contratos, simplicidade (KISS e YAGNI), distinção entre complexidade essencial, opcional e acidental, coesão/acoplamento/ocultação de informação, DRY, SOLID como perguntas diagnósticas, legibilidade, dependências, performance e a filosofia Unix na prática (separar mecanismo de política, projetar para composição, preferir representações inspecionáveis). Finalmente, ele fornece um guia para evolução segura (refatoração vs. mudança de contrato, verificação com testes focados) e uma verificação final de decisão para garantir que as mudanças são justificadas, verificadas e compreensíveis para mantenedores.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NickLitharis/groundwork/tree/HEAD/engineering-principles

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Princípios de Engenharia

Construa a menor solução correta que permaneça compreensível e segura para alterar. Trate princípios como ferramentas para raciocínio, não como leis que se sobrepõem a requisitos, convenções do repositório ou evidências.

Ciclo de trabalho

  1. Estabeleça o contrato. Leia o código relevante, chamadores, testes e instruções do repositório. Identifique comportamento esperado, entradas, saídas, invariantes, modos de falha e restrições de compatibilidade. Distinga fatos observados de suposições. Pergunte apenas quando um requisito não resolvido alterar materialmente a solução.
  2. Escolha um design proporcional. Reutilize padrões locais e capacidades existentes. Prefira uma implementação direta; adicione estrutura quando ela conter complexidade real ou proteger um limite real. Considere segurança, integridade de dados e limites de recursos onde a alteração os tocar.
  3. Altere uma preocupação de cada vez. Mantenha o diff coeso. Preserve trabalho não relacionado. Separe a refatoração que preserva comportamento das mudanças intencionais de comportamento para que cada uma seja revisável. Corrija a causa, não apenas o sintoma observado.
  4. Verifique o comportamento prometido. Use o teste significativo mais restrito ou cenário executável, incluindo caminhos de falha relevantes. Inspecione o que realmente foi executado; uma seleção de teste vazia não prova nada. Testes que passam são evidências para as afirmações e caminhos que exercitam, não prova de toda correção ou compatibilidade.
  5. Finalize a alteração. Atualize chamadores, contratos e documentação afetados. Remova código tornado obsoleto por esta alteração. Relate brevemente o resultado, verificação e qualquer limitação remanescente; explique um princípio apenas quando ele influenciou materialmente uma decisão.

Escalone este ciclo de acordo com o risco: uma renomeação local precisa de pouca cerimônia; uma API compartilhada ou alteração de dados persistidos precisa de evidências de consumidores e migração. Não crie documentos de design ou uma cadeia de especialistas para edições de rotina.

Debugging e fluxo de trabalho do repositório

Trate uma falha relatada pelo usuário como uma reprodução; não peça para repeti-la apenas para confirmá-la. Separe o comportamento observado das hipóteses, depois colete evidências que distingam causas prováveis. Use uma reprodução focada, inspeção direcionada ou depurador em vez de alterar código por tentativa e erro. Corrija a causa, preserve diagnósticos úteis sem expor segredos e nunca suprima um erro para fazer o caminho parecer bem-sucedido. Adicione cobertura de regressão ausente e verifique o comportamento de recuperação relevante quando a falha puder deixar estado parcial.

Use os pontos de entrada existentes de build, teste, execução e geração do repositório. Leia seus pré-requisitos documentados e invoque os mesmos comandos que humanos e CI usam; não adicione uma segunda toolchain ou exija Make onde o repositório tem outra interface adequada. Um comando de teste sem testes correspondentes não é prova.

Mantenha documentação útil para contribuidores: preserve o porquê, invariantes e fluxos principais que o código sozinho não explica; atualize a documentação afetada, escolhendo referência de usuário, tutorial ou material de solução de problemas para o público. Evite reescritas amplas de documentação não relacionadas à alteração.

Princípios de design

Correção começa com contratos

Defina o que deve permanecer verdadeiro antes de escolher um padrão. Torne estados inválidos difíceis de representar usando tipos adequados, construtores e transições de estado explícitas. Mantenha a propriedade de estado mutável e ciclos de vida de recursos claros.

Valide entrada não confiável nos limites. Não remova verificações meramente porque parecem defensivas: estabeleça se a condição é impossível, já garantida ou ainda um modo de falha real. Preserve contexto de erro útil sem vazar segredos. Nunca transforme falha em um resultado bem-sucedido inventado.

Simplicidade: KISS e YAGNI

KISS significa minimizar a complexidade que um mantenedor deve entender, não meramente a contagem de linhas. YAGNI significa implementar requisitos atuais em vez de funcionalidades especulativas futuras. Nenhum deles desculpa tratamento de erro ausente, armazenamento inseguro ou um atalho não mantenível.

Evite plugins, frameworks genéricos, camadas de configuração ou pontos de extensão sem uma necessidade presente. Um design simples ainda pode ter limites claros que tornam mudanças posteriores baratas.

Complexidade no sistema

Distinga complexidade essencial (exigida pelo problema), complexidade opcional (uma capacidade com um custo) e complexidade acidental (dificuldade evitável na implementação do comportamento especificado). Use estas como categorias de raciocínio, não uma cota de funcionalidades. Aplique-as na implementação, interface, integração e esforço e risco de erro dos usuários: reduzir o custo em um lugar pode transferi-lo para outro. Remova complexidade acidental; mantenha capacidade opcional quando seu valor para o usuário justificar seu custo total de vida. Sob um prazo, compare o valor de entrega agora com o esforço fim-a-fim, suporte e manutenção; menos linhas ou funcionalidades sozinhas não estabelecem menor custo total. Para exemplos, veja Complexidade, Interfaces e Desempenho.

Coesão, acoplamento e ocultação de informações

Agrupe código que muda pela mesma razão; separe preocupações que mudam independentemente. Esconda escolhas de implementação voláteis atrás de uma interface pequena e coesa. Prefira um módulo profundo que faz trabalho útil em vez de uma cadeia de wrappers de passagem.

Uma interface pode ser um tanto geral quando isso permite que um mecanismo compartilhado sirva a chamadores identificáveis sem incorporar a política de um chamador. Mantenha-a não mais geral do que os usos atuais justificam: necessidades futuras adivinhadas podem sobrecarregar chamadores atuais. Escolha uma interface especializada quando seu contrato for genuinamente específico.

Responsabilidade única diz respeito a uma razão coesa para mudar, não um método por classe. Baixo acoplamento significa que consumidores precisam de pouco conhecimento dos internos, não que toda chamada exija uma interface. Mantenha direções de dependência explícitas e evite ciclos quando prático.

Abstração e DRY

DRY significa uma representação autoritativa de um conhecimento, não eliminar toda sequência de aparência semelhante. Compartilhe lógica quando chamadores expressam a mesma regra e devem evoluir juntos. Mantenha código superficialmente semelhante separado quando pertence a conceitos ou ciclos de vida diferentes.

Quando o conhecimento também aparece em arquivos gerados, identifique sua fonte autoritativa e gerador. Proteja edições não relacionadas antes da regeneração; resolva propriedade sobreposta em vez de sobrescrever trabalho do usuário. Atualize a fonte, execute o gerador existente e inspecione o diff derivado. Não edite manualmente a saída gerada como a correção durável nem adicione maquinário de geração para trabalho trivial.

Antes de extrair, identifique o contrato compartilhado, as razões esperadas para mudança e a complexidade que a abstração remove. Não use um limite numérico de repetição como prova. Um pouco de duplicação pode custar menos que o acoplamento errado.

SOLID como perguntas diagnósticas

Use estas perguntas onde o design se beneficiar; não imponha uma arquitetura orientada a objetos em código procedural ou funcional.

  • Responsabilidade única: esta unidade mistura preocupações que mudam independentemente?
  • Aberto/fechado: existe um eixo de variação demonstrado que vale isolar, em vez de um framework de extensão hipotético?
  • Substituição de Liskov: uma implementação pode substituir outra sem surpreender chamadores através de pré-condições mais fortes, garantias mais fracas ou falhas incompatíveis?
  • Segregação de interface: os consumidores dependem apenas de capacidades que usam?
  • Inversão de dependência: uma política estável deve depender de um contrato restrito em vez de detalhes voláteis de E/S? Uma função ou parâmetro pode fornecer essa costura; uma hierarquia de classes não é necessária.

Prefira composição sobre herança quando a herança não modelar um relacionamento substitutível genuíno. Use mecanismos idiomáticos da linguagem em vez de nomes de padrões como objetivo.

Legibilidade e menor surpresa

Escolha nomes que exponham significado do domínio, unidades e propriedade. Mantenha fluxo de controle e efeitos colaterais fáceis de seguir. Use comentários para justificativa, restrições e garantias não óbvias, não para narrar declarações óbvias.

Siga convenções do repositório a menos que causem um problema concreto. Tamanho de função, número de parâmetros e profundidade de aninhamento são sinais de alerta, não limites numéricos universais. Indireção extra não é automaticamente código mais limpo. Comentários podem preservar justificativa, restrições e uma abstração que o código sozinho não explica; julgue seu valor no contexto em vez de removê-los ou dividir lógica coesa para atender a uma regra de comprimento ou contagem de comentários.

Dependências e desempenho

Reutilize uma biblioteca mantida e adequada para capacidades estabelecidas difíceis, especialmente criptografia e manipulação de protocolos. Avalie adequação, segurança, licença, compatibilidade, custo operacional e peso da dependência. Não adicione uma dependência para uma operação trivial já servida pela linguagem ou repositório.

Escolha estruturas de dados e algoritmos sensatos para tamanhos de entrada esperados. Evite trabalho redundante óbvio e alocação ou cópia desperdiçadora. Meça gargalos suspeitos antes de otimização complexa; avalie cargas de trabalho representativas e proteja a correção. Nomeie a carga de trabalho, métrica, linha de base, alvo e critério de parada; use medidas ligadas a resultados reais do usuário ou sistema, não contagens de atividade. Pare quando o contrato for atendido ou ganho adicional não valer a complexidade e manutenção adicionadas. Decida se o contrato valoriza latência, throughput ou uso de recursos: batching pode melhorar o throughput enquanto piora o tempo de resposta. Não troque um requisito declarado de latência ou memória por simplicidade estilística. Para exemplos, veja Complexidade, Interfaces e Desempenho.

Filosofia Unix na prática

Escreva componentes coesos que fazem um trabalho bem e compõem através de contratos explícitos. Isso não exige um processo por função, microsserviços, armazenamento somente texto ou ausência de estado em todo lugar. Bibliotecas internas com APIs claras podem ser igualmente composicionais.

  • Separe mecanismo de política. Mantenha computação reutilizável independente de apresentação, ambiente e escolhas de negócio mutáveis onde essa separação reduzir o acoplamento.
  • Projete para composição. Evite estado global oculto e caminhos embutidos desnecessários. Torne dependências e efeitos explícitos; deixe chamadores escolherem destinos onde apropriado.
  • Prefira representações inspecionáveis. Use estruturas de dados simples e formatos documentados. Texto é valioso para ferramentas interoperáveis; formatos binários são válidos quando fidelidade, volume ou desempenho os exigir.
  • Mantenha a operação normal silenciosa, falhas visíveis. Silêncio significa nenhuma conversa fiada irrelevante, não dados de resultado ausentes ou diagnósticos suprimidos.
  • Reutilize ferramentas. Prefira capacidades confiáveis existentes a reconstruí-las. Mantenha automação não interativa quando for destinada a scripts.

Escolha o estilo de interface pelos seus consumidores humanos e de máquina, não pela tradição. Uma função ou API de biblioteca, CLI estável ou filtro pode atender chamadores de máquina e trabalho repetível; tarefas humanas podem precisar de descoberta, feedback ou interação direta. Se ambos são consumidores reais, separe a lógica de domínio de wrappers opcionais para que compartilhem comportamento sem tornar uma interface gráfica obrigatória. Siga o estilo mais simples que atenda ao contrato. Veja Interfaces Unix e Complexidade, Interfaces e Desempenho para tradeoffs práticos. Para design de CLI, pipeline e configuração, leia Interfaces Unix. Quando complexidade, estilo de interface ou tradeoffs de desempenho moldarem materialmente a decisão, leia Complexidade, Interfaces e Desempenho. Para princípios e exemplos concorrentes, leia Tradeoffs. Estas referências são condicionais; nenhuma é obrigatória para uma edição local não relacionada. Para debugging prático, comandos de projeto, artefatos gerados, documentação de mantenedor e exemplos de avaliação de dependência, leia Debugging e Manutenção.

Evolução segura e verificação

Uma refatoração preserva o comportamento observável, incluindo saídas, erros, efeitos colaterais e contratos nos quais os consumidores confiam. Não corrija peculiaridades silenciosamente durante uma refatoração. Uma mudança intencional de contrato, em vez disso, atualiza testes e consumidores afetados explicitamente; testes de requisitos substituídos não são restrições permanentes.

Proteja limites públicos com testes focados em comportamento. Reutilize cobertura adequada; adicione testes de regressão ou caracterização quando um caminho importante estiver desprotegido. Prefira implementações reais ou fakes focados quando prático, mas use dublês para isolar limites genuinamente caros, não determinísticos ou inseguros. Evite asserções sobre chamadas de métodos privados ou redação exata do código fonte, a menos que estes sejam o próprio contrato.

Verifique casos de borda significativos: entradas malformadas, dados vazios, falha de recurso e concorrência ou gravações parciais quando relevante. Não prescreva uma porcentagem de cobertura arbitrária ou uma suíte completa para cada edição.

Preserve compatibilidade pública a menos que alterá-la esteja no escopo. Para contratos duráveis e dados persistidos, examine consumidores, ordem de implantação, migração e recuperação. Use expandir/contrair ou outra abordagem escalonada quando versões antiga e nova devem coexistir; uma mudança atômica coordenada pode ser suficiente caso contrário. Não remova caminhos de recuperação nem instale shims de compatibilidade sem um requisito real.

Verificação final de decisão

Antes de declarar conclusão, pergunte:

  • A implementação satisfaz o contrato real, incluindo falhas relevantes?
  • Cada abstração, dependência e arquivo alterado é justificado por esta tarefa?
  • Um mantenedor pode localizar a regra, seu proprietário de estado e a evidência que a protege?
  • Preservei o comportamento existente ou tornei a alteração pretendida explícita em todos os consumidores afetados?
  • O que realmente verifiquei, e o que permanece não verificado?

Use esta verificação de forma privada; não emita um relatório padrão ou pontuação de princípios para cada edição.

Habilidades Relacionadas