Agent Operable Codebase

Image: AI generated

Uma pergunta

Abra o arquivo mais longo do seu projeto. Quantas funções ele contém?

Peça a um agente de IA para modificar uma função nesse arquivo. O agente lê o arquivo inteiro. Abriu o arquivo porque precisava de uma função, mas 19 funções desnecessárias vieram junto.

É aqui que o problema começa.

Código que humanos leem vs. código que agentes operam

Até agora, código era escrito para humanos lerem. Dar bons nomes a variáveis, escrever comentários, produzir documentação — tudo era para reduzir a carga cognitiva humana.

Na era dos agentes, a pergunta muda. Código fácil de ler para humanos é o mesmo que código fácil de operar para agentes?

Não é.

Um humano rolando um arquivo de 2.000 linhas tem uma intuição que diz “não mexa nessa parte”. Um agente não tem essa intuição. Quando lê 2.000 linhas, 1.950 são poluição de contexto.

Pesquisas confirmam isso. Quando informação irrelevante é misturada, o desempenho da IA cai de 30 a 85%. O desempenho cai mesmo quando os tokens desnecessários são espaços em branco. Que contexto mais curto é melhor não é intuição — é evidência experimental.

Não coloque um robô num escritório humano. Construa uma fábrica onde robôs possam trabalhar.

Três coisas que os agentes precisam

Para que agentes trabalhem de forma confiável numa base de código, três coisas devem estar no lugar.

1. Deve ser legível — sem ruído

Um conceito por arquivo. O nome do arquivo é o nome do conceito.

before: read utils.go → 20 funções, 19 desnecessárias
after:  read check_one_file_one_func.go → 1 função, exatamente o necessário

filefunc resolve esse problema. Separa o código em unidades semânticas com 22 regras estruturais. Aplicado ao framework Hono (23k+ estrelas), dividiu 186 arquivos em 626. Todos os 4.419 testes passaram. Os arquivos aumentaram 3,4 vezes, mas nenhuma linha de lógica mudou.

“Não vão ser arquivos demais?” — Agentes não navegam diretórios. Eles buscam. Sejam 500 ou 1.000 arquivos, um grep resolve. Não abrir 295 arquivos desnecessários importa mais do que encontrar os 5 que você precisa.

2. Deve ser verificável — mecanicamente

Quando você modifica uma função sem testes, ninguém sabe o que quebra. O agente também não sabe. Cai num doom loop.

before: 0 testes, sem saber o que quebra ao modificar
after:  527 funções com testes, mudanças de comportamento detectadas imediatamente

tsma resolve esse problema. Indexa cada função no projeto, detecta presença de testes, mede cobertura e retorna branches não cobertos com números de linha.

Sem feedback, pedir a um LLM para escrever testes estaciona em 60–70% de cobertura. Diga “linha 41, 44, 70 não cobertas” e ele alcança 100%. Mesmo modelo. A única diferença é a resolução do feedback.

Resultados experimentais num projeto com 527 funções: completado até TODO 0. Um agente autônomo declarou “tudo feito” em 40. Aplique o ratchet: 527 completados.

3. Especificações devem ser verificáveis cruzadamente

Deve ser mecanicamente verificável se os esquemas de API, esquemas de BD, políticas de segurança e transições de estado são consistentes entre si. Quando um muda, você precisa saber antes da compilação se há conflito com os demais.

before: 200 endpoints, humanos verificam consistência de specs
after:  um operationId encadeia todas as camadas, máquinas detectam drift

yongol resolve esse problema. Encadeia 10 SSOTs (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl, etc.) através de um único operationId e valida cruzadamente com ~287 regras. user_id é string no OpenAPI mas BIGINT no DDL — ferramentas existentes não capturam contradições entre camadas assim.

Uma estrutura que atravessa as três ferramentas

filefunc, tsma e yongol são ferramentas independentes, mas compartilham uma estrutura comum.

filefunc:  22 regras estruturais → validate → corrigir → repetir
tsma:      medir cobertura → feedback de branches não cobertos → corrigir → repetir
yongol:    validação cruzada → detectar drift → corrigir → repetir

Tudo o mesmo loop.

LLM gera → ferramenta determinística julga → resultado devolvido ao LLM → repetir

Symbolic Feedback Loop. Uma estrutura cíclica onde ferramentas determinísticas corrigem a geração probabilística dos LLMs. Não é IA verificando IA — são máquinas verificando IA.

Dê opiniões e ele bajula. Dê fatos e ele corrige. Pergunte “o código está bom?” e ele responde “sim, ótimo”. Diga “linha 41: nome de campo não corresponde” e ele corrige imediatamente. Feedback sem ninguém para bajular — porque números e localizações não são emoções.

De legado a agent-operable

Não é preciso mudar uma base de código existente de uma vez. Não é trabalho de fundação — é reforço sísmico. Reforçar o prédio sem fechar a loja.

Passo 1 — Torne legível

Comece pelos arquivos mais longos. Execute filefunc validate e leve as violações a zero. Todos os testes existentes devem passar.

Passo 2 — Torne verificável

Repita tsma next. Adicione testes a funções sem testes e cubra branches faltantes. Mesmo se o agente morrer no meio, o progresso é preservado. Um novo agente executa tsma next e continua de onde parou.

Passo 3 — Validação cruzada

Introduza SSOTs e execute yongol validate. Máquinas capturam contradições entre camadas.

Cada passo é independente. Pode fazer o passo 2 sem o 1, ou o passo 1 sem o 2. Mas quando os três se combinam, o escopo de trabalho autônomo dos agentes se expande drasticamente.

Mudando o sistema operacional

Um agent-operable codebase não é apenas linting ou ferramentas. É mudar o sistema operacional da base de código.

Muita gente está fazendo o trem andar mais rápido. Modelos maiores, agentes mais inteligentes, prompts melhores.

Quanto mais rápido o trem, mais importam os trilhos. Quase ninguém está assentando trilhos ainda.

Artigos relacionados

• filefunc — Um conceito por arquivo — Convenção de estrutura de código que elimina poluição de contexto do LLM com 22 regras estruturais
• tsma — Linha de defesa contra regressão em código legado — Automação de testes baseada em ratchet que completa 527 funções até TODO 0
• Por que agentes de código funcionam e por que quebram — Análise estrutural do Symbolic Feedback Loop
• Topologia de feedback acima do QI do modelo — Por que o mesmo modelo para em 40 ou completa 527
• whyso — O que o git blame não mostra — Extração automática de histórico de mudanças por arquivo

Referências

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) — Queda de desempenho de 30%+ quando informação relevante fica enterrada no meio do contexto
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) — Queda de desempenho de 13,9–85% mesmo quando tokens desnecessários são espaços em branco
• Estudo de caso do framework Hono — 186 arquivos → 626 arquivos, todos os 4.419 testes passaram
• Estudo de caso de 527 funções com tsma — PASS 246 (46,7%), DONE 281 (53,3%), TODO 0
• Experimento Ratchet Pattern — agente autônomo 40/527 (7,6%) vs ratchet CLI 527/527 (100%)