Engenharia Composta: Como Minha Base de Código Acelera em Vez de Deteriorar

A maioria das bases de código desacelera conforme cresce. A minha acelera. Depois de construir 95 hooks, 44 skills e 14 arquivos de configuração na minha infraestrutura .claude/, cada novo recurso custa menos que o anterior porque a infraestrutura assume mais do trabalho.¹

TL;DR

Engenharia composta descreve bases de código onde cada adição de funcionalidade torna as funcionalidades subsequentes mais baratas de construir. Eu vivenciei isso na prática: meu sistema de hooks do Claude Code começou com 3 hooks e cresceu para 95. O primeiro hook levou uma hora para ser construído. Hooks recentes levam 10 minutos porque a infraestrutura (eventos de ciclo de vida, carregamento de configuração, gerenciamento de estado, harness de testes) já existe. O padrão oposto, engenharia de entropia, descreve bases de código onde cada funcionalidade aumenta o custo das funcionalidades subsequentes. A diferença entre uma equipe que entrega mais rápido no terceiro ano do que no primeiro e uma equipe que estagna é se suas decisões de engenharia compõem de forma positiva ou negativa.

Composição na Prática: Minha Infraestrutura .claude/

A Curva de Crescimento

O primeiro hook (git-safety-guardian.sh) exigiu construir todo o ciclo de vida de hooks: entender eventos PreToolUse, escrever bash que faz parsing de JSON de entrada, tratar casos de erro, testar manualmente. O 95º hook herdou toda essa infraestrutura. O tempo por hook caiu 6x não porque os hooks ficaram mais simples, mas porque a infraestrutura assumiu mais do trabalho.

O Que Compõe

Consistência de padrões. Todo hook segue a mesma estrutura: ler JSON de entrada, fazer parsing com jq, verificar condições, gerar JSON de decisão como saída. Um desenvolvedor (ou agente de IA) lendo qualquer hook reconhece o padrão instantaneamente. Meu linter de blog com 12 módulos segue o mesmo princípio de consistência: cada módulo exporta a mesma interface (check(content, meta) -> findings), tornando novos módulos triviais de adicionar.

Comportamento orientado por configuração. Todos os 14 arquivos de configuração JSON codificam limiares e regras que originalmente estavam hardcoded. Quando movi o limiar de consenso de deliberação de um 0.70 hardcoded em Python para deliberation-config.json, ganhei a capacidade de ajustá-lo por tipo de tarefa (segurança=85%, documentação=50%) sem alterações no código.²

Infraestrutura de testes. Os primeiros 20 hooks não tinham testes. Adicionar o harness de testes (48 testes de integração em bash, 81 testes unitários em Python) custou duas semanas. Todo hook desde então é entregue com testes em menos de 5 minutos porque os fixtures, helpers de asserção e test runners já existem.

Sistema de memória. Meu arquivo MEMORY.md captura erros, decisões e padrões entre sessões. Com 54 entradas, ele me impede de repetir erros. O problema do ((VAR++)) em bash do hook #23 preveniu o mesmo bug nos hooks #24 até o #95. Cada entrada compõe ao longo de todas as sessões futuras.³

O Modelo de Composição

Composição Positiva

A produtividade de engenharia segue uma fórmula de juros compostos:

Productivity(n) = Base × (1 + r)^n

Onde r é a taxa de variação de produtividade por funcionalidade e n é o número de funcionalidades entregues.

r positivo (composição): Cada funcionalidade torna a próxima 2-5% mais barata. Após 50 funcionalidades: 1,03^50 = 4,38x de melhoria de produtividade.

r negativo (entropia): Cada funcionalidade torna a próxima 2-5% mais cara. Após 50 funcionalidades: 0,97^50 = 0,22x de produtividade — uma degradação de 78%.

A diferença entre essas trajetórias é um gap de 20x na velocidade de engenharia após 50 funcionalidades.⁴

Meus Números Reais

Meu site blakecrosley.com começou como uma única rota FastAPI com um template HTML. Nove meses depois:

A última entrada é o retorno composto: adicionar um novo módulo ao linter leva 15 minutos porque a interface do módulo, integração CLI, harness de testes e pipeline CI já existem. O primeiro módulo levou 3 horas porque nada dessa infraestrutura existia.⁵

Exemplos de Entropia na Minha Própria Base de Código

A composição não é automática. Eu também vivenciei entropia:

O Atalho do Schema ContentMeta

Defini a dataclass ContentMeta do blog post em uma única sessão: title, slug, date, description, tags, author, published. Não incluí category, series, hero_image, scripts ou styles. Cada adição posterior exigiu modificar o parser, atualizar cada template que consumia os metadados e re-testar o pipeline completo. Cinco adições ao longo de três meses custaram mais tempo total do que projetar o schema cuidadosamente desde o início teria custado. Este é o problema de timing de decisão: decisões irreversíveis merecem análise prévia.

A Colisão de Chaves de Cache i18n

Uma implementação rápida do cache de traduções usou slugs de blog como chaves de cache. Quando duas traduções do mesmo slug existiam em locales diferentes, o cache retornava o idioma errado. A depuração levou 3 horas. A correção levou 15 minutos (adicionar prefixo de locale à chave de cache). O atalho que economizou 5 minutos durante a implementação custou 3 horas de depuração e uma revisão arquitetural de cada chave de cache do sistema.⁶

O Diretório de Debug de 3,2 GB

A saída de debug dos hooks se acumulou em ~/.claude/debug/ sem limpeza. Ao longo de três meses, o diretório cresceu para 3,2 GB. A skill de auditoria de contexto que construí depois detectou isso e limpou arquivos com mais de 7 dias, mas a infraestrutura de limpeza deveria ter sido construída junto com a primeira saída de debug.

Práticas Que Compõem

Padrões Consistentes Sobre Padrões Ótimos

Uma equipe que usa o mesmo padrão “bom o suficiente” em 50 funcionalidades opera mais rápido do que uma equipe que usa o padrão “ótimo” para cada funcionalidade individual. Consistência reduz carga cognitiva, viabiliza ferramentas automatizadas e torna code reviews mais rápidos.⁷

Meu sistema de hooks usa o mesmo padrão bash para todos os 95 hooks, mesmo que alguns hooks seriam mais naturalmente expressos em Python. A consistência significa que qualquer hook é legível por qualquer pessoa (ou qualquer agente de IA) que tenha lido um hook. A escolha subótima de linguagem é mais do que compensada pela curva de aprendizado zero para novos hooks.

Infraestrutura Como a Primeira Funcionalidade

Construí meu pipeline CI/CD, harness de testes e fluxo de deploy antes de construir qualquer funcionalidade do produto no blakecrosley.com. O investimento pareceu lento no momento. Cada funcionalidade desde então é implantada em menos de 2 minutos com testes automatizados.⁸

O Padrão do Palácio Mental

Meu diretório .claude/ funciona como um “palácio mental” — um conjunto estruturado de documentos otimizado tanto para consumo humano quanto de IA:

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

O palácio mental compõe porque cada nova entrada enriquece o contexto disponível para sessões futuras de desenvolvimento. Após 54 entradas no MEMORY.md, o agente de IA evita erros que eu já resolvi. Após 95 hooks, novos hooks praticamente se escrevem sozinhos seguindo os padrões estabelecidos. O contexto mais rico produz código gerado por IA mais adequado, o que torna a próxima funcionalidade mais barata.⁹

Composição na Era da IA

A IA Amplifica Ambas as Direções

Assistentes de codificação com IA aceleram qualquer padrão que a base de código já segue. Meus 95 hooks com padrões consistentes produzem hooks excelentes gerados por IA porque a IA replica a estrutura estabelecida. Uma base de código com 5 estilos diferentes de hooks produziria código gerado por IA pior porque a IA não tem um padrão consistente para replicar.¹⁰

O efeito composto duplica: padrões consistentes tornam o desenvolvimento humano mais rápido (redução de carga cognitiva) E o desenvolvimento assistido por IA mais rápido (correspondência de padrões). Padrões inconsistentes tornam ambos mais lentos.

Bases de Código Legíveis por Agentes

Projetei minha infraestrutura .claude/ para consumo por agentes de IA:

• Configurações estruturadas (JSON, não valores hardcoded) que agentes analisam programaticamente
• Convenções de nomenclatura consistentes (verb-noun.sh para hooks, SKILL.md para definições de skills)
• Verificações de qualidade verificáveis por máquina (141 testes que agentes executam autonomamente)
• Documentação explícita (MEMORY.md, handoffs, docs/) que agentes leem no início da sessão

Cada investimento em legibilidade por agentes compõe à medida que as ferramentas de IA se tornam mais capazes.¹¹

Principais Conclusões

Para engenheiros: - Acompanhe seu “tempo por funcionalidade” conforme a base de código cresce; se aumenta, você tem entropia — se diminui, você tem composição - Aplique a regra de três antes de extrair abstrações: construa a solução específica duas vezes, depois extraia o padrão reutilizável na terceira ocorrência - Invista 15-20% de cada sprint em melhorias de infraestrutura e ferramentas; os retornos compostos superam o custo de velocidade de funcionalidades no curto prazo em 3-5 sprints

Para gestores de engenharia: - Meça a saúde da engenharia pelo lead time por funcionalidade ao longo do tempo; lead time crescente sinaliza entropia - Trate documentação e infraestrutura de testes como funcionalidades, não como overhead; meu investimento em infraestrutura de testes (2 semanas) economizou mais de 50 horas ao longo de 95 hooks

Referências