# 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.

---

## 1. 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.

---

## 2. 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.

---

## 3. 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.

---

## 4. 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.

---

## 5. 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.

---

## 6. 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.

---

## Diretrizes 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.


---

## Roteiro 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.

### Prompt de aplicação

```text
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]
```


### Como 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.

### Exemplo preenchido

```text
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.
```