Guia de Referência: Programação Profissional e Código Sustentável (Pete Goodliffe)

Este guia consolida práticas para produzir software que possa ser compreendido, alterado e operado por pessoas reais. A prioridade é revelar intenção, reduzir complexidade acidental, trabalhar com feedback rápido e melhorar o código de forma contínua.

school1. Código como Comunicação

• Legibilidade: O código é lido por pessoas muito mais vezes do que é escrito; nomes, layout e estrutura devem tornar o propósito evidente.
• Simplicidade: Prefira a forma mais direta que expresse corretamente a regra; evite instruções e abstrações desnecessariamente longas.
• Consistência: Mantenha convenções de nomes, formatação, organização de arquivos e tratamento de erros coerentes em toda a base.
• Intenção: Torne explícito o que está implícito e separe funções que realizam responsabilidades distintas.

subdirectory_arrow_right2. Mudança Segura e Manutenção

• Pequenos passos: Faça ajustes frequentes, localizados e testáveis em vez de grandes reescritas sem proteção.
• Regra do escoteiro: Ao tocar uma área, deixe-a um pouco melhor, sem transformar uma demanda pequena em reforma total.
• Duplicação: Elimine duplicações que representam o mesmo conhecimento e que poderiam divergir com o tempo.
• Código morto: Remova caminhos, flags e abstrações que não têm uso real; menos código significa menos superfície de manutenção.

fact_check3. Testes, Bugs e Feedback

• Rede de segurança: Testes automatizados aumentam a confiança para modificar código e detectar regressões cedo.
• Testes focados: Cada teste deve afirmar um comportamento claro, incluindo casos normais, falhas e limites.
• Depuração: Investigue bugs de modo sistemático, reduza o espaço de busca e preserve um caso reproduzível.
• Integração contínua: Execute build e testes frequentemente para detectar incompatibilidades e falhas de integração rapidamente.

subdirectory_arrow_right4. Design e Complexidade

• Baixo acoplamento: Evite dependências rígidas que façam uma mudança local se espalhar por módulos não relacionados.
• Alta coesão: Mantenha responsabilidades que mudam juntas próximas e separe conceitos independentes.
• Generalidade: Não crie bibliotecas ou camadas genéricas apenas porque parecem elegantes; generalize quando houver consumidores e variação reais.
• Reutilização: Compare construir, reutilizar biblioteca existente ou comprar solução; avalie custo total, licença, integração e manutenção.

subdirectory_arrow_right5. Profissionalismo e Trabalho em Equipe

• Revisão: Use revisão de código e programação em pares quando ajudarem a descobrir erros e compartilhar contexto.
• Dívida técnica: Uma correção emergencial pode ser pragmática, mas deve ser registrada e paga logo após a urgência.
• Licenças: Respeite licenças, autoria e propriedade intelectual de código reutilizado.
• Aprendizado: Amplie continuamente domínio técnico e de negócio, mas aplique técnicas novas apenas quando forem adequadas.

school6. Como Usar com IA

Anexe este arquivo quando quiser que a IA implemente ou revise código com foco em legibilidade, manutenção e segurança de mudança. Peça que ela explique quais decisões reduzem complexidade, quais testes protegem a alteração e qual dívida técnica foi criada, se houver.

subdirectory_arrow_rightDiretrizes de Execução para IA

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

1. Revele intenção: nomes, funções e módulos devem deixar claro o que o sistema faz.
2. Mantenha alterações pequenas: evite reescritas amplas quando uma melhoria incremental resolver.
3. Proteja mudanças com testes: valide comportamento normal, falhas e limites.
4. Evite complexidade especulativa: abstraia somente variações reais.
5. Deixe o código melhor: toda alteração deve preservar ou melhorar compreensão e manutenção.

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: Aplicação interna mantida por três desenvolvedores, com JavaScript e API REST; há funções longas, nomes pouco claros e testes parciais.
Objetivo: Revisar o módulo de cadastro e propor melhorias pequenas que aumentem legibilidade, testabilidade e facilidade de manutenção.
Restrições: Preservar comportamento e contrato da API; não reescrever o módulo inteiro; cada alteração deve ser pequena e coberta por teste.