Maturidade do código
Seu agente de codificação IA é tão bom quanto o harness do seu código. A IA amplifica qualquer estrutura que já existe: uma base de código disciplinada acelera o desenvolvimento, uma indisciplinada acelera o desenvolvimento de código confidentemente errado. O harness (Fowler: Agent = Model + Harness) é o que esta página ajuda você a medir.
Um diagnóstico de nove dimensões com uma rubrica de pontuação de 1 a 5 por dimensão. Três são bloqueadoras: pontuações baixas comprometem fundamentalmente o trabalho do agente e não podem ser compensadas por pontuações altas em outros lugares. As outras seis são restritivas. Avalie qualquer repositório com um único comando usando a skill gratuita de código aberto para Claude Code.
Os cinco níveis de maturidade
Cada nível é definido pelo mecanismo de feedback que ele adiciona. Você não pode pular níveis; o que desbloqueia o próximo nível é sempre outro ciclo de feedback, nunca uma ferramenta nova.
| Nível | Nome | O que está presente | O que os agentes podem fazer |
|---|---|---|---|
| 0 | Opaco | Sem tipos aplicados. Pouca ou nenhuma cobertura de testes. CI ausente ou não confiável. Documentação desatualizada. Fronteiras de módulos pouco claras. | Sugestões isoladas de função única. Qualquer coisa além disso produz código alucinado sem sinal corretivo. |
| 1 | Instrumentado | Tipos aplicados no momento da compilação. Alguns testes existem. CI retorna aprovado/reprovado em minutos. | Geração de função única com confiança básica. Refatorações de escopo restrito. O sinal é fraco mas presente. |
| 2 | Validado | Cobertura significativa nos caminhos de código que mudam com mais frequência. CI abaixo de 30 min (abaixo de 5 min é melhor). Pelo menos um caminho de integração ponta a ponta. | Refatorações de múltiplos arquivos dentro de escopo delimitado. Correções de bugs validadas por testes existentes. Nível mínimo para o Rung 3 (desenvolvimento dirigido). |
| 3 | Legível | Fronteiras de módulos claras. Nomenclatura consistente. Arquitetura documentada. Contratos comportamentais declarados nas fronteiras de interface. | Trabalho entre módulos com resultados previsíveis. Agentes podem raciocinar sobre o código sem orientações. |
| 4 | Especificado | Intenção capturada em especificações, não apenas no código. Novo trabalho é spec-first. Decisões históricas documentadas. | Geração autônoma de features a partir de spec (Rung 4). O humano especifica; o agente constrói e testa. |
| 5 | Governado por cenários | Cenários ponta a ponta cobrem caminhos críticos. Métricas de satisfação substituem aprovado/reprovado binário. Observabilidade completa. | Produção autônoma completa (Rung 5). O modelo operacional do Lab se torna sustentável. |
Fowler chama as propriedades estruturais do Nível 3+ de ambient affordances: propriedades que tornam uma base de código legível para um agente sem instrução adicional. A ausência delas força o agente a inventar estrutura.
O AI Codebase Maturity Model, validado em um projeto real com 91% de cobertura e ciclos de bug-to-fix abaixo de 30 minutos, formulou o achado central de forma direta: "A inteligência de um sistema de desenvolvimento conduzido por IA não reside no próprio modelo de IA, mas na infraestrutura de instruções, testes, métricas e ciclos de feedback que o cercam."
A regra do teto
A prática de engenharia (os Rungs 0 a 5 do framework) é sobre como a equipe trabalha. A maturidade do código (Níveis 0 a 5) é sobre o que o código suporta. Elas estão ligadas:
O nível de maturidade de uma base de código é o teto do Rung de engenharia que pode operar nele de forma confiável.
Uma equipe no Rung 5 implantando agentes em uma base de código de Nível 2 terá as mesmas falhas que uma equipe no Rung 2, só que mais rápido. Os ciclos de feedback que mantêm o Rung 5 honesto não existem. Este é o modo de falha mais comum na adoção de IA em código existente: equipes veem demos do Rung 5 em repositórios greenfield e assumem que o modelo de trabalho se transfere. Não vai, até que o harness seja construído.
A Grade de maturidade do código (Codebase Readiness Grid)
Nove dimensões. Cada uma responde a uma pergunta. Pontue cada uma de 1 a 5. A pontuação mais baixa é o teto do nível de maturidade em que você pode operar de forma confiável; sua dimensão mais fraca é onde os agentes falharão primeiro.
A Grade de maturidade do código (Codebase Readiness Grid), como uma skill para Claude Code. Roda em qualquer repositório, coleta sinais por dimensão e produz um scorecard com uma recomendação de caminho para o Nível 5. Código aberto, licença MIT.
| # | Dimensão | Tipo | Pergunta que responde | Rubrica de pontuação (1–5) |
|---|---|---|---|---|
| 1 | Cobertura de testes e latência de feedback | bloqueadora | Há cobertura significativa nos caminhos de código que mudam com mais frequência? Qual é a velocidade do CI? | 1 = sem testes ou testes mortos. 2 = baixa cobertura, CI lento. 3 = cobertura significativa nos hot paths, CI abaixo de 30 min. 4 = limiar aplicado, CI abaixo de 5 min, falhas localizadas. 5 = cenários comportamentais cobrem caminhos críticos, CI rápido e verde como portão de deploy. |
| 2 | Rigor de tipos | bloqueadora | Os tipos são aplicados no momento da compilação? O any é raro ou pervasivo? | 1 = sem tipos ou tipos desativados. 2 = tipos opcionais, any em todo lugar. 3 = tipos aplicados, algumas escotilhas de escape. 4 = modo strict ativo, any raro e justificado. 5 = strict mode no CI, zero any, contratos em todas as fronteiras. |
| 3 | Tamanho de arquivo e legibilidade de contexto | restritiva | Um agente consegue raciocinar sobre um arquivo sem carregar o resto do sistema? | 1 = god files (2000+ linhas), responsabilidades misturadas. 2 = muitos arquivos de 1000+ linhas, entrelaçados. 3 = a maioria dos arquivos abaixo de 500 linhas, alguns outliers. 4 = a maioria abaixo de 300 linhas, outliers raros e justificados. 5 = cada arquivo dimensionado para uma responsabilidade. |
| 4 | Clareza das fronteiras de módulo | restritiva | Um engenheiro novo (ou agente) consegue descrever o grafo de módulos em 30 minutos? As fronteiras são aplicadas? | 1 = sem estrutura modular. 2 = estrutura no papel, violada na prática. 3 = módulos de alto nível claros, vazamentos ocasionais. 4 = fronteiras aplicadas, contratos estáveis. 5 = o grafo de módulos é um mapa navegável; arquitetura documentada e atualizada. |
| 5 | Diretividade de API | bloqueadora | A chamada HTTP/RPC é visível no local da chamada, ou escondida atrás de camadas de abstração? | 1 = acesso via abstrações opacas (Factory, dynamic dispatch, ORM com queries invisíveis). 2 = abstração significativa, rastreável com esforço. 3 = mistura de direto e abstraído. 4 = chamadas majoritariamente diretas com respostas tipadas. 5 = os locais de chamada mostram o que está acontecendo; sem operações de rede ou banco de dados ocultas. |
| 6 | Intenção documentada | restritiva | O porquê está documentado separadamente do como? As decisões arquiteturais estão registradas? | 1 = sem documentação de intenção; o código é a única verdade. 2 = documentação dispersa, frequentemente desatualizada. 3 = READMEs de módulo, alguns ADRs. 4 = log de ADR atualizado, módulos críticos documentados, CLAUDE.md / AGENTS.md em vigor. 5 = toda decisão não trivial tem uma spec ou ADR; contexto histórico preservado. |
| 7 | Observabilidade | restritiva | Você consegue saber o que o sistema fez para uma determinada requisição? As falhas produzem casos de teste reproduzíveis? | 1 = sem logs estruturados, sem traces, sem métricas, sem rastreamento de erros. 2 = alguns logs, sem tracing. 3 = logs estruturados e métricas básicas; rastreamento de erros em vigor. 4 = telemetria completa com acesso a queries. 5 = produção totalmente observável; erros produzem casos de teste reproduzíveis. |
| 8 | Simplicidade de desenvolvimento e deploy | restritiva | Você consegue configurar o ambiente de desenvolvimento com um único comando? Fazer deploy com um (ou automaticamente)? | 1 = configuração do ambiente leva dias ou exige conhecimento tribal; deploys manuais e frágeis. 2 = com script mas frágil; deploys exigem etapas de runbook. 3 = comandos documentados, deploy confiável. 4 = configuração em um comando; deploy em um comando (ou automático). 5 = ambiente de desenvolvimento, CI e produção arquiteturalmente idênticos. |
| 9 | Atualidade de dependências e runtime | restritiva | O runtime é suportado? Os frameworks estão dentro de 1 a 2 majors da versão atual? Há bibliotecas abandonadas? | 1 = runtime EOL, framework 2+ majors atrás, bibliotecas abandonadas, paradigmas misturados. 2 = runtime atual mas muitas dependências 1+ major atrás. 3 = runtime atual, maioria das dependências dentro de 1 major, padrão legado ocasional documentado. 4 = paradigmas modernos consistentes. 5 = higiene agressiva de dependências; convenções alinham com os padrões atuais da comunidade. |
Notas sobre as dimensões menos autoexplicativas. D1: CI lento é o déficit mais comum em código existente: uma suíte de testes de 72 horas não é um sensor, é um relatório. D3: arquivos pequenos não são uma preferência de estilo, são uma disciplina de janela de contexto; agentes que precisam de três arquivos para entender uma função alucinam as partes que faltam. D5: abstrações opacas não apenas escondem detalhes, elas produzem código confidentemente errado quando o agente adivinha o que UserFactory.resolve() faz. D6: o código se documenta; a intenção não. Este é o déficit mais difícil de corrigir rapidamente. D9: os agentes são treinados nas versões e idiomas atuais das bibliotecas; uma base de código usando padrões de 2 a 3 anos atrás recebe código que contradiz suas próprias convenções.
Como a pontuação funciona
Quatro regras governam como ler o scorecard. Elas se acumulam (todas as quatro se aplicam simultaneamente).
1. O teto é a pontuação mais baixa. Sua dimensão mais fraca define seu nível de maturidade. Uma base de código com oito 5s e um 1 está no Nível 0, não no Nível 4. Os agentes falham no elo mais fraco.
2. Três dimensões são bloqueadoras; seis são restritivas.
- Bloqueadoras (D1, D2, D5): pontuações baixas comprometem fundamentalmente o trabalho do agente. Sem testes, os agentes ficam cegos. Sem tipos, eles alucinam estruturas. Com APIs opacas, produzem código confidentemente errado. Não podem ser compensadas por pontuações altas em outros lugares.
- Restritivas (D3, D4, D6, D7, D8, D9): pontuações baixas degradam a qualidade, mas os agentes ainda conseguem produzir valor. Mais revisão humana por mudança, mais limpeza, mais fricção.
Quando duas dimensões empatam com pontuação baixa, eleve primeiro a bloqueadora. A regra do teto ainda se aplica; essa classificação apenas aguça a prioridade de remediação.
3. Crédito por deferimento: um deferimento intencional e documentado pontua um nível acima do que a mesma lacuna não documentada. Se a observabilidade não está configurada, mas a spec do projeto a adia para uma fase de GA com data e critérios, pontue como 2 em vez de 1. O deferimento é uma decisão; uma lacuna inadvertida não é. Declarações verbais não qualificam: o deferimento precisa estar no repositório.
4. Nunca resuma o scorecard com uma média. O scorecard é um vetor, não um escalar. Duas bases de código com média 3,0 podem estar em situações radicalmente diferentes: uma com D1 em 1 está cega; uma com D7 em 1 é operacionalmente imatura mas utilizável. Médias escondem essa distinção.
O scorecard é um instantâneo. Execute-o novamente a cada trimestre, pois bases de código se movem em ambas as direções.
Como é uma base de código no Nível 5
Uma referência concreta, generalizada a partir de padrões observados. Uma base de código que pontua 5 em todas as nove dimensões tende a ter estas características:
- Spec-first para trabalho não trivial. Contratos de API verificados, cenários de aceitação definidos, decisões documentadas antes do código.
- Tipagem rigorosa aplicada no momento da compilação. Zero
any. Violações de tipo reprovam o CI. - Arquivos pequenos e focados. A maioria abaixo de algumas centenas de linhas. Os arquivos maiores são outliers intencionais, não acumulações acidentais.
- Acesso direto à API e aos dados. Os locais de chamada mostram o que está sendo chamado. Sem factories opacas, sem dispatchers genéricos.
- Dependências mínimas. Poucos pacotes, cada um justificado.
- Convenções explícitas. Estrutura de arquivos e nomenclatura documentadas. Cabeçalho
ABOUTME:em cada arquivo.AGENTS.mdouCLAUDE.mdcom as regras do agente. - Sem conhecimento implícito. A base de código é legível porque diz o que significa, não porque a equipe se lembra.
- Testes como contratos. Mocks simples, asserções de comportamento, nomes legíveis.
- Build em um comando, deploy em um comando. Sem lutar com a infraestrutura para publicar.
- Dependências atuais, runtime suportado. Sem runtimes EOL, sem bibliotecas abandonadas.
Essas não são preferências de estilo. São as propriedades estruturais que permitem que os agentes produzam trabalho confiável, e são as mesmas propriedades que tornam os humanos produtivos. Os dois não estão separados.
Estratégia de construção do harness
Quando a maturidade está abaixo do que sua equipe precisa para trabalhar, sequencie o investimento nesta ordem. Pular etapas produz velocidade sem confiança.
O harness tem duas partes: sensores (testes, CI, observabilidade) verificam o output do agente; guias (tipos, convenções, documentação de arquitetura, intenção documentada) especificam o que produzir. Bases de código brownfield tipicamente têm os guias mas carecem dos sensores: essa é a configuração que publica código confidentemente errado.
Etapa 1: Instale sensores rápidos primeiro. Testes úteis e CI rápido (latência de feedback abaixo de 30 minutos é o critério). Sem sensores, cada mudança subsequente é um palpite e você não consegue verificar se o trabalho posterior no harness está funcionando.
Etapa 2: Torne o código legível. Nomenclatura consistente, tipos aplicados, fronteiras de módulo claras, preocupações transversais centralizadas, exclusão de caminhos mortos. A legibilidade é o que permite que os agentes trabalhem entre módulos sem alucinam estrutura.
Etapa 3: Capture a intenção. Documente decisões arquiteturais. Declare contratos comportamentais nas fronteiras de interface. Para os módulos mais críticos, extraia a especificação implícita: as mil decisões acumuladas ao longo de anos de patches. Os agentes podem documentar o que o sistema faz; distinguir comportamento intencional de acidente histórico continua sendo trabalho humano. Veja a sequência brownfield do Lab de IA para a versão disciplinada.
Etapa 4: Governe com cenários. Converta a intenção em cenários ponta a ponta. Os cenários são mais difíceis para os agentes contornarem do que os testes unitários. O modo de trabalho do Rung 5 se torna viável neste ponto.
Padrões de Paul Duvall em AI Development Patterns que se encaixam nesta sequência: Readiness Assessment (Foundation), Observable Development, Guided Refactoring.
O que fazer quando a pontuação é baixa
Quatro modos se aplicam, cobertos em detalhes em Estratégia de engenharia brownfield: remediar no lugar, migração strangler-fig, reconstrução completa ou isolar e contornar. O modo certo depende da solidez arquitetural da base de código, da disponibilidade de costuras e do valor de negócio restante, não da capacidade da equipe ou de prioridades estratégicas, que ficam fora desta avaliação.
Espelho: maturidade e confiabilidade
Engenharia para Confiabilidade aborda o output de IA como entrada para sistemas. A maturidade do código aborda o inverso: a base de código como entrada para agentes de IA. A mesma incerteza, refletida.
Relacionados
- Estratégia de engenharia brownfield: os quatro modos para bases de código com baixa maturidade
- O Lab de IA: o modo de trabalho do Rung 5 que uma base de código de Nível 5 suporta
- Engenharia para Confiabilidade: o problema espelho
- Padrões de Execução de IA e Guia de Especificação: engenharia de especificação
Fontes
- Mahiou et al. (2026). "AI Codebase Maturity Model (ACMM)." arXiv. arxiv.org/abs/2604.09388
- Fowler, M. (2026). "Harness Engineering for Coding Agent Users." martinfowler.com
- Duvall, P. (2026). "AI Development Patterns." github.com/PaulDuvall/ai-development-patterns
- Google Cloud (2025). "DORA 2025 State of AI-assisted Software Development." dora.dev
- "A Maturity Model for AI-Native Development." (2025). Transcode. blog.transcode.be
- "The State of Generative AI in Software Development." (2026). arXiv. arxiv.org/abs/2603.16975
← Voltar para o início · Estratégia de engenharia brownfield · O Lab de IA · Engenharia para Confiabilidade · Glossário