Existe um costume preguiçoso na adoção de agentes de IA em times de engenharia: criar um AGENTS.md (ou CLAUDE.md, ou .cursorrules) com uma linha do tipo "OBEY Clean Code by Robert C. Martin" e considerar o trabalho feito. A intuição é razoável, o modelo conhece o livro, foi treinado em milhares de blogs sobre o assunto, devia bastar mencionar. Não basta. E agora existe medição.
Maciej Ciemborowicz, autor do repositório ciembor/agent-rules-books (1.4k stars, MIT), publicou um experimento desconfortavelmente claro. Mesma codebase de partida (um helpdesk CLI deliberadamente vibe-coded), mesmo modelo (GPT-5.5, reasoning alto), mesmo plano de refactor, só muda o conteúdo do AGENTS.md. Uma branch usa apenas a linha "obey Clean Code". A outra usa o conjunto de regras mini destilado do livro. O resultado, julgado por ChatGPT na pergunta "qual código implementa melhor os princípios de Ousterhout?", foi 74 contra 46. Vinte e oito pontos de qualidade arquitetural a mais, pelo único custo de trocar uma linha de texto por umas 50 linhas de regras concretas.
Por que apenas citar o livro não funciona
O reflexo intuitivo é pensar que o modelo "sabe" Clean Code porque o livro inteiro está no corpus de treinamento. Saber e aplicar consistentemente não são a mesma coisa. O LLM tem ativações esparsas sobre o livro, referências, citações, exemplos isolados, blogs sobre o livro, posts que discordam do livro, contradições entre Uncle Bob de 2008 e Uncle Bob de 2020. Pedir "obedeça Clean Code" deixa o modelo navegar essa nuvem inteira sem âncora operacional. O que sai é uma média ponderada do que circula no corpus, não as decisões específicas que o livro defende.
Já um conjunto de regras concretas faz três coisas que a menção sozinha não faz. (1) Reduz a entropia, o modelo não precisa adivinhar qual interpretação de "clean" usar, recebe a interpretação pronta. (2) Cabe na atenção, 50 linhas de regras estão sempre no contexto, o livro inteiro nunca está. (3) Resiste à diluição de longas sessões, quanto mais o agente itera, mais a menção ao livro fica afastada do span de atenção atual; uma regra explícita em AGENTS.md volta a ser relida a cada decisão de arquivo.
O que o repo entrega na prática
O agent-rules-books destila 13 livros canônicos de engenharia de software em conjuntos de regras prontas para colar em AGENTS.md, em CLAUDE.md, em Cursor rules, ou para virar skills de Claude Code. A lista é exatamente a que você esperaria ver na estante de quem leva engenharia a sério:
- Clean Code (Robert C. Martin), leitura local, nomes, funções pequenas, responsabilidade única
- Clean Architecture (Martin), fronteiras estáveis, regra de dependência, isolamento de detalhes
- A Philosophy of Software Design (Ousterhout), módulos profundos, interfaces simples, redução de carga cognitiva
- Code Complete (McConnell), construção disciplinada, defensive programming, controle de fluxo
- Refactoring (Fowler), passos pequenos, code smells, separação de refactor e feature
- Refactoring.Guru, catálogo prático de smells e técnicas de tratamento
- Patterns of Enterprise Application Architecture (Fowler), Repository, Unit of Work, Data Mapper, etc.
- Domain-Driven Design (Evans), modelagem de domínio, bounded contexts, ubiquitous language
- Domain-Driven Design Distilled (Vernon), DDD sem cerimônia excessiva
- Implementing DDD (Vernon), aggregates, eventos de domínio, integrações
- Designing Data-Intensive Applications (Kleppmann), replicação, partição, consistência, schema evolution
- Release It! (Nygard), circuit breaker, bulkhead, timeout, backpressure
- The Pragmatic Programmer (Hunt/Thomas), DRY, ortogonalidade, automação, feedback rápido
- Working Effectively with Legacy Code (Feathers), characterization tests, seams, dependency breaking
Cada um vem em três tamanhos: full (canônico, 12-60KB), mini (recomendado para uso real, 3-8KB) e nano (fallback de orçamento apertado, 1-3KB). Essa estratificação não é estética. É a admissão honesta de que contexto é um recurso finito e que cada byte de system prompt compete com a tarefa real.
Full vs Mini vs Nano: a economia do orçamento de contexto
Aqui está o detalhe que muita gente ignora: o tamanho do conjunto de regras altera a economia da sessão inteira. Um AGENTS.md com 60KB de Clean Architecture full + DDD full + DDIA full é impressionante de ler, e patologicamente caro de usar. Cada turno do agente paga aqueles tokens em latência e em accuracy points deslocados da tarefa real. É exatamente o mesmo padrão que o post sobre custo da abstração ritualística denunciou: cerimônia que não cabe no orçamento vira imposto recorrente.
O mini resolve isso com pragmatismo digno de respeito. Em ~5KB por livro, ele entrega: quando usar, viés primário a corrigir, regras de decisão (12-15 itens), regras de gatilho (quando aplicar), e um checklist final. É a destilação operacional que cabe na atenção do modelo durante uma sessão longa. A escolha entre full/mini/nano deve ser feita exatamente como a escolha de qualquer outra dependência: quanto valor entrega, quanto orçamento consome, vale o trade?
O detalhe metodológico que mais importa: Reek quase não viu a diferença
Esse é o ponto que separa o experimento de marketing puro. Quando Ciemborowicz rodou o linter Reek (analisador de code smells para Ruby) em ambas as branches, o resultado foi 1.083 smells na branch "só menciona o livro" contra 1.077 smells na branch com regras mini. Praticamente empate técnico no medidor automático. O ganho não estava na superfície, não era variável melhor nomeada, função mais curta, ou import mais limpo. Era arquitetural: profundidade de módulo, fronteiras de responsabilidade, ocultação de informação, quantidade de código que o leitor precisa entender de uma vez para mudar algo.
Esse achado tem implicação prática enorme para quem mede qualidade só com SonarQube, ESLint ou similares: se o seu único critério é contagem de warning estático, você é cego para o ganho real de regras de arquitetura. O linter mede o que cabe em uma AST. A regra de design mede o que cabe na cabeça do próximo engenheiro que vai tocar o código. Os dois medem coisas diferentes, e a indústria, faz duas décadas, otimiza só o primeiro.
Como escolher os livros certos pro seu time (não copie todos)
A tentação ao olhar para 13 livros é colar tudo no AGENTS.md. Não faça isso. Os livros conflitam entre si em pontos importantes, DDD pesado vs DDD Distilled vs A Philosophy of Software Design têm visões diferentes sobre quanta abstração introduzir. Empilhar conflito não dá ao agente "o melhor de todos"; dá uma média confusa.
A heurística saudável é escolher de 2 a 3 livros em função do caso de uso dominante do repositório. Padrões úteis:
- Codebase de produto novo, sem dívida grande: Clean Code (mini) + A Philosophy of Software Design (mini). Foco em legibilidade + módulos profundos.
- Codebase legado com baixa cobertura de testes: Working Effectively with Legacy Code (mini) + Refactoring (mini). Seams primeiro, transformações depois.
- Serviço crítico de produção (pagamentos, autenticação): Release It! (mini) + Clean Architecture (mini). Resiliência operacional + fronteiras imutáveis.
- Sistema com domínio rico e regras complexas de negócio: DDD Distilled (mini) + Implementing DDD (mini). DDD na dose certa, sem cerimônia academicista.
- Pipeline de dados, ETL, eventos: DDIA (mini) + Pragmatic Programmer (mini). Consistência semântica + automação.
Combinar mais que 3 conjuntos costuma ser sintoma de indecisão arquitetural, está mais fácil escolher tudo do que olhar para a realidade do código. Resista.
Os limites do experimento, e por que ele ainda importa
O próprio Ciemborowicz é honesto sobre as limitações: foi um caso só, julgado por um LLM (ChatGPT) com prompt subjetivo, sobre um projeto deliberadamente ruim para servir de cobaia. Não é benchmark. Não está pareado contra outros conjuntos de regras (Cursor official, awesome-prompts, etc.). Não tem replicações em linguagens diferentes. Como ele mesmo escreveu, deve ser tratado como "early qualitative signal, not benchmark".
Mesmo assim, a direção do sinal é forte demais para ser ignorada. Dobrar a especificidade da instrução melhorou substancialmente a saída arquitetural, e isso bate com a intuição que qualquer um que prompt-engineera há mais de seis meses já tem: ser específico vence ser elegante. O custo de adoção é absurdamente baixo (copiar 50 linhas de markdown), e o downside é desprezível (se as regras conflitam com seu estilo, você edita ou remove). É a definição de asymmetric upside.
Adoção pragmática, o caminho de 30 minutos
A maioria dos times trava na fase de "vou estudar todas as opções antes de escolher". Pula essa fase. O ciclo curto é o seguinte:
- Escolha 1 livro que casa com a dor mais visível do repositório agora. Clean Code se o problema é legibilidade. Release It! se o problema é estabilidade. DDD Distilled se o problema é modelo confuso.
- Cole o conjunto mini no
AGENTS.md(ouCLAUDE.md, ou Cursor rules). Não edite na primeira vez, observe o agente operando com o conjunto cru. - Faça uma feature real com o agente seguindo as regras. Compare com uma PR equivalente da semana passada, feita sem as regras. Olhe especificamente: profundidade de módulo, número de arquivos abertos, tamanho de função, clareza de fronteira.
- Itere: edite o conjunto removendo regras que conflitam com o estilo do seu time, adicionando 2-3 específicas do seu domínio.
- Só agora considere adicionar um segundo livro, se sentir que falta algo. Mais de 3 livros é sinal de que você está fugindo da decisão.
O jogo mudou: AGENTS.md não é mais decoração
Por dois anos, AGENTS.md foi um arquivo que times criavam por completude, "vamos colocar algumas regras genéricas". O agent-rules-books faz o que precisava ser feito: trata o arquivo como artefato de engenharia de primeira ordem, com versionamento (full/mini/nano), metodologia de validação, e curadoria a partir das fontes que a indústria já reconhece como canônicas. Não é a única forma. Mas é a primeira que combina rigor metodológico com licença MIT e uso prático imediato.
Para quem ainda acredita que basta mencionar o livro, o número 74 contra 46 deveria ser suficiente. Para quem já desconfiava, o repo entrega o atalho. O custo de adoção é uma manhã. O ganho é arquitetural e cumulativo. Em um time onde metade das interações com o código passa por um agente, ignorar essa otimização é decisão consciente de pagar imposto recorrente em qualidade, pelo único benefício de parecer minimalista no AGENTS.md.
