Além do Clean Code: Projetando Sistemas para a Mente Sintética

Durante décadas, o mantra da engenharia de software foi "escreva código para humanos". Ocupamos nossas mentes com a clareza de um bate papo, nomes que soam bem aos ouvidos e abstrações que facilitam o modelo mental de um colega. Mas em 2026, o colega mais ativo no repositório não tem ouvidos, nem lê como nós.

O Agente de IA tornou-se o leitor onipresente. Ele não apenas "ajuda" a escrever; ele mantém, refatora e depura. No entanto, sua "mente" — baseada em janelas de contexto, probabilidades estatísticas e chamadas de ferramentas — opera sob uma física diferente da cognição humana.

Projetar código hoje exige uma nova camada de disciplina: a Arquitetura para Agentes. Não se trata de abandonar o Clean Code clássico, mas de entender que o que antes era estética, agora é infraestrutura.

1. A Física do Contexto

Para um humano, um arquivo de 2.000 linhas é cansativo. Para um agente, ele é tecnicamente proibitivo. Quando um modelo lê um arquivo, ele o faz através de uma janela de tokens. Arquivos "god-files" forçam o agente a paginar ou truncar a leitura, o que degrada sua capacidade de raciocínio.

A unidade de processamento do agente é o arquivo pequeno.
Se uma função ou módulo não cabe em um "snapshot" de 300 linhas, você está pedindo ao agente para montar um quebra-cabeça com metade das peças escondidas. O custo disso não é apenas financeiro (tokens), mas cognitivo: a probabilidade de alucinação aumenta exponencialmente quando o contexto está fragmentado.

2. O Pilar da Descobribilidade (Grep-ability)

Nós navegamos código por pastas e IDEs. O agente navega por Busca e Salto. Ele usa ferramentas como ripgrep para localizar alvos antes de decidir o que ler.

Neste cenário, a precisão do nome supera a beleza.
- Nomes genéricos são ruído: Se você nomeia uma classe como Manager, o agente receberá 50 resultados ao pesquisar. Ele perderá tempo e contexto filtrando lixo.
- Nomes únicos são endereços: InboundInvoiceProcessor é um endereço de precisão cirúrgica. Um único grep leva o agente exatamente onde ele precisa estar.

A estrutura de diretórios também deve ser um mapa previsível. Agentes são excelentes em inferir caminhos. Se seu projeto segue convenções rígidas, o agente "adivinha" onde está o teste ou o modelo sem precisar listar diretórios, economizando latência e ciclos de processamento.

3. A Camada de Metadados: Tipos e Proveniência

Um dos maiores mitos do Clean Code original era que "comentários são sinais de falha". Na era dos agentes, comentários são sinais de intenção.

A IA é fluente em sintaxe, mas cega para a história. Ela sabe o que o código faz, mas não sabe por que aquele if estranho existe para contornar um bug de uma biblioteca legada de 2022.
- Tipagem Estrita: Funciona como um contrato imediato. O agente não precisa explorar 10 arquivos para entender a forma de um objeto se ele estiver explicitamente tipado.
- Comentários de Proveniência: Documente o "Porquê". Referencie tickets, decisões de arquitetura e workarounds. Para o agente, isso é metadado vital que ele não consegue extrair apenas lendo a lógica.

4. O Ciclo de Feedback Autônomo

Um agente sem testes é um agente perigoso. A capacidade de uma IA de ser produtiva está diretamente ligada à facilidade com que ela pode validar sua própria hipótese.

Se o seu ambiente de testes exige um setup manual complexo, você excluiu o agente do ciclo de melhoria contínua.
- Testes Headless: O comando deve ser único e previsível (npm test, pytest).
- Isolamento via DI: A Injeção de Dependência permite que o agente substitua componentes pesados por simuladores em milissegundos, permitindo que ele itere sobre a lógica pura sem se preocupar com infraestrutura.

Manifesto do Código Agente-Friendly

Para garantir que seu projeto seja um terreno fértil para a inteligência artificial, adote estas diretrizes no seu CLAUDE.md ou arquivo de regras:

1. Atomicidade: Arquivos abaixo de 300 linhas. Funções que fazem apenas uma coisa.
2. Identidade: Nomes de classes e métodos agressivamente únicos para facilitar o grep.
3. Transparência: Tipagem explícita em todas as interfaces. Nada de any ou tipos implícitos.
4. Intencionalidade: Comentários que explicam decisões não óbvias e workarounds.
5. Validabilidade: Ciclo de teste executável via CLI em menos de 10 segundos.
6. Desacoplamento: Use interfaces e DI para permitir o isolamento de componentes durante a edição.

Educando a Máquina: Instruindo o Agente a Escrever Código Limpo

Ter uma arquitetura compatível com agentes é apenas metade da batalha. A outra metade é garantir que o agente, em sua pressa por entregar resultados, não ignore esses princípios. Modelos de linguagem tendem a seguir o caminho de menor resistência, o que muitas vezes resulta em funções gigantes ou duplicação de lógica se não houver um "corrimão" explícito.

Você deve tratar as instruções do agente como parte do seu sistema de governança de código. Isso é feito através de arquivos de regras (como CLAUDE.md, .cursor/rules ou .github/copilot-instructions.md). O segredo é ser curto, imperativo e focado em ações. O agente lê esses arquivos a cada iteração; se a regra não estiver lá, ele não a inventará.

Exemplo de Configuração para o CLAUDE.md:

## Code style

- Functions: 4-20 lines. Split if longer.
- Files: under 500 lines. Split by responsibility.
- One thing per function, one responsibility per module (SRP).
- Names: specific and unique. Avoid `data`, `handler`, `Manager`.
  Prefer names that return <5 grep hits in the codebase.
- Types: explicit. No `any`, no `Dict`, no untyped functions.
- No code duplication. Extract shared logic into a function/module.
- Early returns over nested ifs. Max 2 levels of indentation.
- Exception messages must include the offending value and expected shape.

## Comments

- Keep your own comments. Don't strip them on refactor — they carry
  intent and provenance.
- Write WHY, not WHAT. Skip `// increment counter` above `i++`.
- Docstrings on public functions: intent + one usage example.
- Reference issue numbers / commit SHAs when a line exists because
  of a specific bug or upstream constraint.

## Tests

- Tests run with a single command: `<project-specific>`.
- Every new function gets a test. Bug fixes get a regression test.
- Mock external I/O (API, DB, filesystem) with named fake classes,
  not inline stubs.
- Tests must be F.I.R.S.T: fast, independent, repeatable,
  self-validating, timely.

## Dependencies

- Inject dependencies through constructor/parameter, not global/import.
- Wrap third-party libs behind a thin interface owned by this project.

## Structure

- Follow the framework's convention (Rails, Django, Next.js, etc.).
- Prefer small focused modules over god files.
- Predictable paths: controller/model/view, src/lib/test, etc.

## Formatting

- Use the language default formatter (`cargo fmt`, `gofmt`, `prettier`,
  `black`, `rubocop -A`). Don't discuss style beyond that.

## Logging

- Structured JSON when logging for debugging / observability.
- Plain text only for user-facing CLI output.

Conclusão: O Código como API para Agentes

Escrever código em 2026 não é mais sobre preencher arquivos de texto; é sobre projetar uma API que agentes de IA possam consumir para nos ajudar a construir sistemas.

O Clean Code evoluiu de uma questão de artesanato humano para uma necessidade de eficiência sistêmica. Código bagunçado não é apenas feio; ele é caro, lento e propenso a erros de máquina. No fim do dia, o código mais limpo é aquele que permite que a inteligência — seja ela humana ou sintética — flua sem atrito.

Este artigo é uma releitura e expansão das ideias discutidas originalmente por Fabio Akita em Clean Code pra Agentes de IA.