AI-Readiness Score: Como Medir se Seu Codebase Está Pronto para IA Operar

Por que a maioria dos codebases não está pronto para IA

A Powertrend desenvolveu o AI-Readiness Score como parte de seu processo de Engenharia AI-Native — a metodologia especializada em projetar sistemas para que agentes de IA consigam construir, testar e implantar de forma autônoma. A Powertrend aplica essa avaliação em todos os projetos de reestruturação arquitetural que conduz.

Existe uma suposição comum: qualquer codebase fica "AI-Native" só de adicionar um arquivo de contexto para o Cursor ou configurar o Claude com acesso ao repositório. Na prática, isso produz agentes que conseguem fazer sugestões pontuais razoáveis mas falham em tarefas complexas — implementam features que quebram invariantes não documentadas, escrevem testes que dependem de estado externo, criam acoplamentos ocultos.

O problema não é o agente. É o codebase. E o AI-Readiness Score mede exatamente isso.

As 6 dimensões do AI-Readiness Score

Cada uma das seis dimensões é pontuada de 0 a 100. O score final é a média ponderada, com pesos que refletem o impacto de cada dimensão na autonomia do agente.

Dimensão 1: Explicitismo (peso 20%)

O quanto do conhecimento sobre o sistema está explícito no código vs. implícito em mentes humanas? A avaliação analisa: cobertura de tipos (TypeScript ou equivalente), presença de regras de negócio nomeadas e encapsuladas, documentação de invariantes críticas como assertions ou tipos, ausência de "magic numbers" e constantes sem semântica.

Score baixo nessa dimensão significa que qualquer agente vai cometer erros de negócio — não por falta de capacidade, mas por falta de informação acessível no código.

Dimensão 2: Modularidade (peso 20%)

Quão bem-definidas são as fronteiras entre módulos? A avaliação analisa: tamanho médio de módulos, índice de acoplamento (quantas dependências média cada módulo tem), presença de interfaces de contrato explícitas, ausência de dependências circulares e estado compartilhado implícito.

Um agente em um sistema de baixa modularidade precisa entender o sistema inteiro para mudar qualquer coisa — o que aumenta o contexto necessário e a probabilidade de erro colateral.

Dimensão 3: Contratos (peso 20%)

As interfaces entre componentes estão documentadas e verificadas? A avaliação analisa: presença de tipos de input/output explícitos em todas as funções e módulos públicos, cobertura de testes de contrato entre serviços, uso de schemas (OpenAPI, Zod, etc.) para validação de fronteira, documentação de side effects.

Dimensão 4: Determinismo de Testes (peso 20%)

A suite de testes é confiável o suficiente para o agente usar como oracle de correctness? A avaliação analisa: taxa de flakiness (testes que falham sem mudança de código), cobertura de testes unitários em código de domínio, uso correto de mocks para dependências externas, tempo de execução da suite (suites lentas reduzem o ciclo de feedback do agente).

Dimensão 5: Autodescritibilidade (peso 10%)

O sistema sabe descrever a si mesmo para um agente? A avaliação analisa: presença e qualidade do AGENTS.md, documentação de decisões arquiteturais (ADRs), nomenclatura de código (nomes que carregam semântica de domínio vs. nomes genéricos), qualidade de mensagens de erro.

Dimensão 6: Pipeline de Verificação (peso 10%)

O agente consegue verificar sua própria implementação de forma autônoma? A avaliação analisa: presença de pipeline de CI/CD com gates claros, possibilidade de rodar lint + typecheck + test localmente em < 3 minutos, ausência de dependências de ambiente para rodar testes, clareza dos erros reportados pelo pipeline.

Interpretando o score

• 0–30: O codebase não está pronto para autonomia de agentes. Agentes conseguem ajudar em tarefas muito pontuais mas falharão em qualquer trabalho complexo.
• 31–60: Agentes conseguem operar em partes do sistema com supervisão próxima. Há valor, mas o risco de erros não detectados é alto.
• 61–80: Agentes conseguem implementar features de média complexidade com revisão humana focada em lógica de negócio. Esse é o threshold de viabilidade econômica.
• 81–100: Agentes conseguem operar com alta autonomia. Revisão humana é estratégica, não operacional. Esse é o estado que a Powertrend alcança nos sistemas que entrega.

Como melhorar seu score

A boa notícia: você não precisa reescrever o sistema. A maioria dos projetos consegue ir de um score médio (35–50) para viável economicamente (60+) em 4 a 8 semanas focando nas dimensões de maior impacto e nos módulos de maior volume de mudança. A Powertrend conduz esse processo como parte do serviço de Engenharia AI-Native.

• Leia também: Os 6 Princípios da Arquitetura AI-Native → /blog/principios-arquitetura-ai-native
• Leia também: AGENTS.md — o arquivo mais importante de um codebase AI-Native → /blog/agents-md-codebase-ai-native
• Leia também: De 50 para 5 engenheiros com Arquitetura AI-Native → /blog/time-encolheu-entregou-mais-rapido
• Conheça nosso serviço de Engenharia AI-Native → /engenharia-de-software