Clean Code e Regras de Legibilidade para Agentes
Definition
Regras de legibilidade agrupam 4 livros que ensinam o agente a escrever código que um humano consegue raciocinar localmente: Clean Code (Martin, 220 regras full), Code Complete (McConnell, 180), The Pragmatic Programmer (Hunt/Thomas, 179) e A Philosophy of Software Design (Ousterhout, 177). No repo agent-rules-books cada um vira um mini de ~28-47 regras focadas em nomes, funções, módulos e pragmatismo.
Key Points
- Clean Code (mini 29 regras): nomes precisos / um termo por conceito, funções pequenas em um nível de abstração, separar commands de queries, esconder representação, manter construção/framework/persistência fora do domínio, comentários só para racional/warnings.
- Code Complete (mini 38 regras): disciplina de construção — design de rotinas, variáveis, classes, fluxo de controle, programação defensiva, padrões de teste.
- Pragmatic Programmer (mini 47 regras): DRY no nível de conhecimento, ortogonalidade, automação, feedback rápido, prototipação; funciona como camada geral de engenharia.
- Philosophy of SD (mini 28 regras, validado 74/100): combater complexidade com módulos profundos, interfaces simples, information hiding; reduzir carga cognitiva do leitor.
O que pedir ao agente (checklist do founder)
- “Nomes carregam significado sem precisar de comentário narrativo?”
- “Função cabe numa tela e conta a história top-down?”
- “Caminho feliz legível, erro/cleanup isolados?”
- “Domínio livre de detalhes de framework/banco/vendor?”
- “Pelo menos um smell removido na área tocada, sem alargar o escopo silenciosamente?”
- “Testes como código de produção — legíveis, determinísticos, rodados?”
Implications
Este cluster é o default para todo MVP vibe-coded: se você só puder escolher um mini, comece por Clean Code. Ele desloca a revisão do founder de “o código roda?” para “eu consigo seguir o caminho feliz sem pular arquivo?”. Conecta com especificacao-de-issues-para-agentes (critérios de pronto legíveis) e com agents-md-como-instrucao-operacional (manter prompt enxuto).
Related Concepts
- agents-md-como-instrucao-operacional — onde estas regras moram sem inchar o contexto
- especificacao-de-issues-para-agentes — issue como contrato legível
- regras-de-agentes-a-partir-de-livros — hub dos 4 clusters
- vibe-coding — prática que estas regras sustentam