Escreva código como um humano vai mantê-lo

Comentários, nomes e legibilidade

• Muitos preferem comentários mínimos e nomes claros em vez de muitos comentários.
• Comentários redundantes que “explicam o que o código faz” são vistos como ruído e propensos a ficar defasados; comentários devem explicar o “porquê”, não o “o quê” ou “como o framework funciona”.
• Alguns defendem um fluxo parecido com programação literária (escrever primeiro a prosa/intenção, depois o código), mas reconhecem que isso muitas vezes acaba virando apenas uma reescrita do próprio código.
• O consenso: bons nomes, estrutura simples e comentários ocasionais do tipo “here be dragons / rationale” são o ideal.

Comentários e estilo gerados por LLMs

• Há forte frustração com LLMs produzindo comentários verbosos e de baixo valor, notas históricas e conversa sobre o processo de implementação.
• Os modelos frequentemente descrevem noções básicas da linguagem, peculiaridades do código ao redor ou o comportamento do chamador, quebrando o encapsulamento e ficando obsoletos rapidamente.
• Tentativas de restringir isso via regras em CLAUDE.md / AGENTS.md ajudam um pouco, mas são seguidas de forma inconsistente; instruções negativas (“não faça X”) são especialmente falhas.

Produtividade vs. manutenibilidade com IA

• Alguns afirmam ter um throughput 10x maior de features/bugs ao enviar qualquer coisa que passe nos testes e deixar a IA “lidar com a bagunça depois”.
• Outros alertam que essa sujeira se acumula: lógica duplicada, regras de negócio divergentes e camadas defensivas aninhadas tornam o trabalho futuro de IA e de humanos mais lento e arriscado.
• Há debate sobre se a velocidade de curto prazo será compensada pela complexidade de longo prazo, especialmente em bases de código grandes.

Prompts, checklists e fluxos de revisão

• Muitos usam CLAUDE.md / AGENTS.md no nível do projeto, além de comandos explícitos de “/review” com longas checklists (DRY, estilo, duplicação, código morto, testes, documentação).
• Alguns dividem a revisão em várias passagens especializadas (segurança, acessibilidade, desempenho, simplificação) e até revisão adversarial com múltiplos modelos.
• Outros relatam retornos decrescentes conforme as listas de instruções crescem; os modelos ainda ignoram regras básicas (por exemplo, uso de git), exigindo guardrails no nível do sistema.

Ferramentas tradicionais e guardrails

• Analisadores estáticos, linters, formatadores de código, detectores de duplicação e checagens de pre-commit/CI são amplamente recomendados como bases não estocásticas.
• Alguns escrevem linters personalizados ou checagens no nível do compilador para impor coisas que LLMs violam rotineiramente (sem números mágicos, sem imports dinâmicos, exigência de docs/testes).

Papéis de humanos vs. IA

• Vários desenvolvedores agora usam LLMs principalmente para exploração, refatoração e revisão, mas ainda escrevem o código central manualmente.
• Outros adotam fluxos de trabalho intensivos em IA, aceitando que os humanos talvez não mantenham mais um modelo mental completo do sistema e passem a depender de harnesses e ferramentas robustas.
• No fundo, muitos enfatizam: estrutura manutenível, DRY e abstrações claras ainda importam — tanto para humanos quanto para agentes que consumirem o código depois.