Madurez del código
Tu agente de codificación con IA es tan bueno como el andamiaje de tu código. La IA amplifica la estructura existente: un código disciplinado acelera la entrega; uno indisciplinado acelera la entrega de código incorrecto de manera confiable. El andamiaje (Fowler: Agent = Model + Harness) es lo que esta página te ayuda a medir.
Un diagnóstico de nueve dimensiones con una rúbrica de puntuación del 1 al 5 por dimensión. Tres son bloqueantes: las puntuaciones bajas comprometen fundamentalmente el trabajo del agente y no pueden compensarse con puntuaciones altas en otras áreas. Las otras seis son restrictivas. Puntúa cualquier repositorio con un solo comando usando la habilidad gratuita y de código abierto para Claude Code.
Los cinco niveles de madurez
Cada nivel se define por el mecanismo de retroalimentación que agrega. No se pueden saltar niveles; lo que desbloquea el siguiente nivel siempre es otro bucle de retroalimentación, no otra herramienta.
| Nivel | Nombre | Qué está presente | Qué pueden hacer los agentes |
|---|---|---|---|
| 0 | Opaco | Sin tipos impuestos. Poca o ninguna cobertura de pruebas. IC ausente o poco fiable. Documentación desactualizada. Límites de módulo poco claros. | Sugerencias aisladas de función única. Cualquier cosa más allá produce código alucinado sin señal correctiva. |
| 1 | Instrumentado | Tipos impuestos en tiempo de compilación. Algunas pruebas existen. El IC devuelve resultados en minutos. | Generación de función única con confianza básica. Refactorizaciones de alcance reducido. La señal es débil pero está presente. |
| 2 | Validado | Cobertura significativa en las rutas de código que cambian. IC en menos de 30 min (menos de 5 min es mejor). Al menos una ruta de integración de extremo a extremo. | Refactorizaciones de múltiples archivos dentro de un alcance acotado. Correcciones de errores validadas por las pruebas existentes. Nivel mínimo para el Peldaño 3 (desarrollo dirigido). |
| 3 | Legible | Límites de módulo claros. Nomenclatura consistente. Arquitectura documentada. Contratos de comportamiento declarados en los límites de interfaz. | Trabajo entre módulos con resultados predecibles. Los agentes pueden razonar sobre el código sin guías. |
| 4 | Especificado | La intención está capturada en especificaciones, no solo en el código. El trabajo nuevo es spec-first. Las decisiones históricas están documentadas. | Generación autónoma de funcionalidades a partir de spec (Peldaño 4). El humano especifica; el agente construye y prueba. |
| 5 | Gobernado por escenarios | Los escenarios de extremo a extremo cubren las rutas críticas. Las métricas de satisfacción reemplazan el resultado binario. Observabilidad completa. | Producción autónoma completa (Peldaño 5). El modelo operativo del Laboratorio se vuelve sostenible. |
Fowler llama a las propiedades estructurales del Nivel 3 en adelante affordances ambientales: propiedades que hacen el código legible para un agente sin instrucción adicional. Su ausencia obliga al agente a inventar estructura.
El AI Codebase Maturity Model, validado en un proyecto real con un 91% de cobertura y ciclos de corrección en menos de 30 minutos, formuló el hallazgo central sin rodeos: "La inteligencia de un sistema de desarrollo impulsado por IA no reside en el propio modelo de IA, sino en la infraestructura de instrucciones, pruebas, métricas y bucles de retroalimentación que lo rodean."
La regla del techo
La práctica de ingeniería (los Peldaños 0-5 del marco) trata de cómo trabaja el equipo. La madurez del código (Niveles 0-5) trata de lo que el código soporta. Están vinculados:
El nivel de madurez de un código es el techo del Peldaño de ingeniería que puede operar sobre él de manera fiable.
Un equipo en el Peldaño 5 empujando agentes hacia un código de Nivel 2 obtendrá la misma tasa de fallos que un equipo en el Peldaño 2, pero más rápido. Los bucles de retroalimentación que mantienen honesto al Peldaño 5 no existen. Este es el modo de fallo más común en la adopción brownfield de IA: los equipos ven demos del Peldaño 5 en repositorios greenfield y asumen que el modelo funciona igual. No será así hasta que el andamiaje esté construido.
La Cuadrícula de madurez del código (Codebase Readiness Grid)
Nueve dimensiones. Cada una responde a una pregunta. Puntúa cada una del 1 al 5. La puntuación más baja es el techo del nivel de madurez en el que puedes operar de manera fiable; tu dimensión más débil es donde los agentes fallarán primero.
La Cuadrícula de madurez del código (Codebase Readiness Grid), como habilidad de Claude Code. Se ejecuta en cualquier repositorio, recopila señales por dimensión y produce un cuadro de puntuación con una recomendación de Camino al Nivel 5. Código abierto, licencia MIT.
| # | Dimensión | Tipo | Pregunta que responde | Rúbrica de puntuación (1-5) |
|---|---|---|---|---|
| 1 | Cobertura de pruebas y latencia de retroalimentación | bloqueante | ¿Hay cobertura significativa en las rutas de código que cambian con más frecuencia? ¿Qué tan rápido es el IC? | 1 = sin pruebas o pruebas muertas. 2 = poca cobertura, IC lento. 3 = cobertura significativa en rutas calientes, IC en menos de 30 min. 4 = umbral obligatorio, IC en menos de 5 min, los fallos se localizan. 5 = escenarios de comportamiento cubren rutas críticas, IC rápido y verde como puerta de despliegue. |
| 2 | Estrictez de tipos | bloqueante | ¿Los tipos se imponen en tiempo de compilación? ¿Es any raro o generalizado? | 1 = sin tipos o tipos desactivados. 2 = tipos opcionales, any en todas partes. 3 = tipos impuestos, algunas escotillas de escape. 4 = modo estricto activado, any raro y justificado. 5 = modo estricto en IC, cero any, contratos en cada límite. |
| 3 | Tamaño de archivo y legibilidad del contexto | restrictiva | ¿Puede un agente razonar sobre un archivo sin cargar el resto del sistema? | 1 = archivos dios (2000+ líneas), responsabilidades mezcladas. 2 = muchos archivos de 1000+ líneas, enredados. 3 = la mayoría de los archivos bajo 500 líneas, algunos valores atípicos. 4 = la mayoría bajo 300 líneas, los valores atípicos son raros y justificados. 5 = cada archivo dimensionado para una responsabilidad. |
| 4 | Claridad de los límites de módulo | restrictiva | ¿Puede un nuevo ingeniero (o agente) describir el grafo de módulos tras 30 minutos? ¿Se imponen los límites? | 1 = sin estructura modular. 2 = estructura en papel, violada en la práctica. 3 = módulos de alto nivel claros, fugas ocasionales. 4 = límites impuestos, contratos estables. 5 = el grafo de módulos es un mapa navegable; arquitectura documentada y actualizada. |
| 5 | Transparencia de la API | bloqueante | ¿La llamada HTTP/RPC es visible en el punto de llamada, o está oculta tras capas de envoltorios? | 1 = acceso mediante abstracciones opacas (Factory, despacho dinámico, ORM con consultas invisibles). 2 = abstracción significativa, rastreable con esfuerzo. 3 = mezcla de llamadas directas y abstraídas. 4 = llamadas mayormente directas con respuestas tipadas. 5 = los puntos de llamada muestran lo que ocurre; sin operaciones de red ni de base de datos ocultas. |
| 6 | Intención documentada | restrictiva | ¿Está documentado el por qué separado del cómo? ¿Están registradas las decisiones arquitectónicas? | 1 = sin documentación de intención; el código es la única verdad. 2 = documentación dispersa, a menudo desactualizada. 3 = READMEs de módulo, algunos ADRs. 4 = registro de ADRs actualizado, módulos críticos documentados, CLAUDE.md / AGENTS.md en su lugar. 5 = cada decisión no trivial tiene una spec o ADR; contexto histórico preservado. |
| 7 | Observabilidad | restrictiva | ¿Puedes saber qué hizo el sistema para una solicitud dada? ¿Los fallos producen casos de prueba reproducibles? | 1 = sin registros estructurados, sin trazas, sin métricas, sin seguimiento de errores. 2 = algunos registros, sin trazabilidad. 3 = registros estructurados y métricas básicas; seguimiento de errores en su lugar. 4 = telemetría completa con acceso de consulta. 5 = producción completamente observable; los errores producen casos de prueba reproducibles. |
| 8 | Simplicidad de desarrollo y despliegue | restrictiva | ¿Puedes configurar el entorno de desarrollo con un comando? ¿Desplegar con uno (o automáticamente)? | 1 = la configuración del entorno tarda días o requiere conocimiento tribal; los despliegues son manuales y frágiles. 2 = con scripts pero frágil; los despliegues requieren pasos del runbook. 3 = comandos documentados, despliegue fiable. 4 = configuración en un comando; despliegue en un comando (o automático). 5 = desarrollo, IC y producción arquitectónicamente idénticos. |
| 9 | Actualidad de dependencias y tiempo de ejecución | restrictiva | ¿Está soportado el tiempo de ejecución? ¿Están los frameworks dentro de 1-2 versiones principales de la actual? ¿Hay bibliotecas abandonadas? | 1 = tiempo de ejecución EOL, framework 2+ versiones principales atrás, bibliotecas abandonadas, paradigmas mezclados. 2 = tiempo de ejecución actual pero muchas dependencias 1+ versiones principales atrás. 3 = tiempo de ejecución actual, la mayoría de dependencias dentro de 1 versión principal, patrón heredado ocasional documentado. 4 = paradigmas modernos consistentes. 5 = higiene de dependencias agresiva; las convenciones coinciden con los estándares actuales de la comunidad. |
Notas sobre las dimensiones menos evidentes. D1: el IC lento es el déficit brownfield más común: una suite de pruebas de 72 horas no es un sensor, es un informe. D3: los archivos pequeños no son una preferencia de estilo, son una disciplina de ventana de contexto; los agentes que necesitan tres archivos para entender una función alucinan las partes faltantes. D5: las abstracciones opacas no solo ocultan detalles, sino que producen código incorrecto con confianza cuando el agente adivina qué hace UserFactory.resolve(). D6: el código se documenta a sí mismo; la intención no. Este es el déficit más difícil de reparar rápidamente. D9: los agentes están entrenados con versiones e idiomas actuales de las bibliotecas; un código que usa patrones de hace 2-3 años recibe código que contradice sus propias convenciones.
Cómo funciona la puntuación
Cuatro reglas rigen cómo interpretar el cuadro de puntuación. Se combinan: las cuatro aplican simultáneamente.
1. El techo es la puntuación más baja. Tu dimensión más débil establece tu nivel de madurez. Un código con ocho 5s y un 1 está en el Nivel 0, no en el Nivel 4. Los agentes fallan en el eslabón más débil.
2. Tres dimensiones son bloqueantes; seis son restrictivas.
- Bloqueantes (D1, D2, D5): las puntuaciones bajas comprometen fundamentalmente el trabajo del agente. Sin pruebas, los agentes son ciegos. Sin tipos, alucinan formas. Con APIs opacas, producen código incorrecto con confianza. No pueden compensarse con puntuaciones altas en otras áreas.
- Restrictivas (D3, D4, D6, D7, D8, D9): las puntuaciones bajas degradan la calidad, pero los agentes aún pueden producir valor. Más revisión humana por cambio, más limpieza, más fricción.
Cuando dos dimensiones empatan con una puntuación baja, eleva primero la bloqueante. La regla del techo sigue aplicando; esta clasificación simplemente agudiza la prioridad de remediación.
3. Crédito por aplazamiento: un aplazamiento intencional y documentado puntúa un nivel más alto que la misma brecha sin documentar. Si la observabilidad no está configurada, pero la spec del proyecto aplaza esto a una fase GA-Ready con fecha y criterios, puntúa 2 en lugar de 1. El aplazamiento es una decisión; una brecha inadvertida no lo es. Las afirmaciones verbales no califican: el aplazamiento debe estar en el repositorio.
4. Nunca resumas el cuadro de puntuación con un promedio. El cuadro de puntuación es un vector, no un escalar. Dos códigos con promedio de 3,0 pueden estar en situaciones radicalmente distintas: uno con D1 en 1 está ciego; uno con D7 en 1 es operativamente inmaduro pero usable. Los promedios ocultan esa distinción.
El cuadro de puntuación es una instantánea. Ejecútalo cada trimestre: los códigos se mueven en ambas direcciones.
Cómo se ve un código de Nivel 5
Una referencia concreta, generalizada a partir de patrones observados. Un código que puntúa 5 en las nueve dimensiones tiende a compartir estas características:
- Spec-first para el trabajo no trivial. Contratos de API verificados, escenarios de aceptación definidos, decisiones documentadas antes del código.
- Tipado estricto impuesto en tiempo de compilación. Cero
any. Las violaciones de tipo fallan el IC. - Archivos pequeños y enfocados. La mayoría por debajo de unos pocos cientos de líneas. Los archivos más grandes son valores atípicos intencionales, no acumulaciones accidentales.
- Acceso directo a APIs y datos. Los puntos de llamada muestran lo que se está llamando. Sin fábricas opacas, sin despachadores genéricos.
- Dependencias mínimas. Pocos paquetes, cada uno justificado.
- Convenciones explícitas. Estructura de archivos y nomenclatura documentadas. Encabezado
ABOUTME:en cada archivo.AGENTS.mdoCLAUDE.mdcon las reglas del agente. - Sin conocimiento implícito. El código es legible porque dice lo que significa, no porque el equipo lo recuerde.
- Pruebas como contratos. Mocks simples, aserciones de comportamiento, nombres legibles.
- Compilación en un comando, despliegue en un comando. Sin luchar contra la infraestructura para entregar.
- Dependencias actuales, tiempo de ejecución soportado. Sin tiempos de ejecución EOL, sin bibliotecas abandonadas.
Estas no son preferencias de estilo. Son las propiedades estructurales que permiten a los agentes producir trabajo fiable, y son las mismas propiedades que hacen productivos a los humanos. Las dos no están separadas.
Estrategia para construir el andamiaje
Cuando la madurez está por debajo de donde el equipo necesita trabajar, secuencia la inversión en este orden. Saltarse etapas produce velocidad sin confianza.
El andamiaje tiene dos partes: los sensores (pruebas, IC, observabilidad) verifican el resultado del agente; las guías (tipos, convenciones, documentación de arquitectura, intención documentada) especifican qué producir. Los códigos brownfield típicamente tienen las guías pero carecen de los sensores: esa es la configuración que entrega código incorrecto con confianza.
Etapa 1: Instala primero los sensores rápidos. Pruebas útiles e IC rápido (la latencia de retroalimentación inferior a 30 minutos es la puerta). Sin sensores, cada cambio posterior es una suposición y no puedes verificar que el trabajo posterior de andamiaje esté dando resultados.
Etapa 2: Haz el código legible. Nomenclatura consistente, tipos impuestos, límites de módulo claros, centralización de las preocupaciones transversales, eliminación de rutas muertas. La legibilidad es lo que permite a los agentes trabajar entre módulos sin alucinar estructura.
Etapa 3: Captura la intención. Documenta las decisiones arquitectónicas. Declara contratos de comportamiento en los límites de interfaz. Para los módulos más críticos, extrae la especificación implícita: las miles de decisiones que se acumularon a lo largo de años de parches. Los agentes pueden documentar lo que el sistema hace; distinguir el comportamiento intencional del accidente histórico sigue siendo humano. Ver la secuencia brownfield del Laboratorio de IA para la versión disciplinada.
Etapa 4: Gobierna con escenarios. Convierte la intención en escenarios de extremo a extremo. Los escenarios son más difíciles de eludir por los agentes que las pruebas unitarias. El modo de trabajo del Peldaño 5 se vuelve viable en este punto.
Patrones de Paul Duvall AI Development Patterns que encajan en esta secuencia: Readiness Assessment (Foundation), Observable Development, Guided Refactoring.
Qué hacer cuando la puntuación es baja
Cuatro modos aplican, cubiertos en detalle en Estrategia brownfield: remediar en el sitio, Strangler-fig, reconstrucción completa o aislar y evitar. El modo correcto depende de la solidez arquitectónica del código, la disponibilidad de costuras y el valor de negocio restante, no de la capacidad del equipo o las prioridades estratégicas, que están fuera de esta evaluación.
Espejo: madurez e infiabilidad
Ingeniería para la fiabilidad aborda el resultado de la IA como entrada a los sistemas. La madurez del código aborda lo inverso: el código como entrada a los agentes de IA. La misma incertidumbre, reflejada.
Relacionado
- Estrategia brownfield: los cuatro modos para códigos con baja madurez
- El Laboratorio de IA: el modo de trabajo del Peldaño 5 que un código de Nivel 5 soporta
- Ingeniería para la fiabilidad: el problema espejo
- Estándares de ejecución con IA y Guía de especificación: ingeniería de especificaciones
Fuentes
- 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
← Volver al inicio · Estrategia brownfield · El Laboratorio de IA · Ingeniería para la fiabilidad · Glosario