Guia de Referência: Código Limpo (Robert C. Martin)

Este guia concentra as práticas de código limpo em regras para IA: o código deve comunicar intenção, manter unidades pequenas e coesas, controlar efeitos colaterais, tratar erros de forma explícita e ser sustentado por testes e refatoração contínua.

subdirectory_arrow_right1. Nomes Significativos

• Intenção: Nomes devem explicar por que algo existe, o que faz e como é usado.
• Precisão: Evite nomes genéricos, enganadores, abreviações obscuras e diferenças irrelevantes.
• Vocabulário: Use termos consistentes do domínio e do projeto para conceitos equivalentes.

subdirectory_arrow_right2. Funções

• Pequenas e focadas: Funções devem fazer uma coisa em um nível de abstração coerente.
• Argumentos: Prefira poucos argumentos; muitos parâmetros podem sinalizar objeto/abstração ausente.
• Efeitos colaterais: Evite fazer algo inesperado além do que o nome e contrato prometem.
• Comandos e consultas: Quando possível, separe operações que mudam estado das que apenas retornam informação.

forms_add_on3. Comentários e Formatação

• Código primeiro: Prefira tornar o código autoexplicativo a usar comentário para compensar estrutura confusa.
• Comentários úteis: Documente intenção, decisões, riscos ou contexto que o código não consegue expressar sozinho.
• Formatação: Organização visual e proximidade ajudam o leitor a reconhecer relações e níveis de abstração.

subdirectory_arrow_right4. Objetos, Estruturas e Erros

• Encapsulamento: Objetos protegem invariantes e oferecem comportamento; estruturas de dados expõem dados deliberadamente.
• Demeter: Evite cadeias longas de conhecimento entre objetos quando isso cria acoplamento excessivo.
• Exceções: Use exceções/erros para separar fluxo normal de tratamento de falhas quando a linguagem/ecossistema favorecer isso.
• Null: Reduza a necessidade de null em contratos quando valores opcionais, objetos nulos ou tipos explícitos tornarem o código mais seguro.

fact_check5. Testes Limpos

• Legibilidade: Código de teste precisa ser tão compreensível e mantido quanto o de produção.
• Um conceito: Cada teste deve comunicar um comportamento/expectativa principal.
• Rápidos e independentes: Testes de unidade devem fornecer feedback rápido e evitar dependências entre si.
• Repetibilidade: Resultados não devem depender de ordem, relógio, rede ou estado externo sem controle.

subdirectory_arrow_right6. Classes e Sistemas

• Responsabilidade: Classes devem ter razões coesas para mudar.
• Organização: Separe construção/configuração da lógica de negócio; concentre wiring no ponto de composição.
• Evolução: Use refatoração contínua para melhorar nomes, remover duplicação e manter o design compreensível.
• Simplicidade: Evite estruturas desnecessárias e prefira soluções que revelem intenção.

school7. Como Usar com IA

Anexe este arquivo a qualquer implementação ou revisão. Peça que a IA aplique as regras como checklist: nomes, funções, efeitos colaterais, tratamento de erro, testes, duplicação e responsabilidades.

subdirectory_arrow_rightDiretrizes de Execução para IA

Ao criar, revisar ou reestruturar uma aplicação, garanta:

1. Escreva para leitores humanos e revele intenção no código.
2. Mantenha unidades pequenas e coesas.
3. Trate falhas explicitamente e evite efeitos colaterais escondidos.
4. Mantenha testes limpos e confiáveis.
5. Refatore continuamente para remover duplicação e melhorar estrutura.

schoolRoteiro de Uso Operacional com IA

1. Contextualize o projeto: informe domínio, stack, arquitetura atual, restrições e objetivo da mudança.
2. Selecione o recorte: diga qual princípio/capítulo deste guia deve orientar a tarefa; não aplique tudo ao mesmo tempo.
3. Peça diagnóstico antes do código: a IA deve identificar sintomas, riscos, dependências e alternativas.
4. Defina critérios de aceite: comportamento, testes, acessibilidade, performance, segurança ou operação conforme o tema.
5. Implemente incrementalmente: mudanças pequenas, reversíveis e verificadas.
6. Faça revisão final: peça à IA que confronte a solução com este guia e liste desvios deliberados.

smart_toyPrompt de aplicação

Use este guia como referência técnica para a tarefa abaixo.
Não copie regras mecanicamente. Primeiro diagnostique o problema e selecione apenas os princípios aplicáveis.
Mostre: (1) diagnóstico, (2) decisão, (3) implementação proposta, (4) testes/verificações, (5) trade-offs e (6) checklist final.

Contexto: [DESCREVA o sistema, stack, estado atual e cenário da mudança]
Objetivo: [DESCREVA o resultado esperado e o comportamento que deve existir]
Restrições: [DESCREVA limites de escopo, compatibilidade, segurança, prazo e o que não pode mudar]

schoolComo preencher os campos

• Contexto: descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente.
• Objetivo: descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar.
• Restrições: informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo.

lightbulbExemplo preenchido

Contexto: Módulo JavaScript funciona, porém possui funções extensas, variáveis genéricas e comentários explicando trechos difíceis.
Objetivo: Melhorar clareza do código sem alterar comportamento, priorizando nomes, funções coesas e remoção de duplicação.
Restrições: Não aplicar regras de estilo mecanicamente; preservar performance necessária e APIs públicas; mudanças devem ser verificadas por testes.