La legibilidad del código para IA mide si una base de código resulta legible para un modelo de lenguaje: si el código lleva información de tipos verificable por máquina y si los archivos caben con holgura en el contexto de trabajo de un modelo. Las mismas propiedades que ayudan a un humano a orientarse en una base de código desconocida ayudan a un modelo — pero para los modelos, los archivos sobredimensionados son una restricción dura y no una mera molestia.
- Categoría: Preparación para IA (15 % dentro de la categoría)
- Peso en el índice general: 0 % — parte de la insignia independiente de Preparación para IA
- Clave de la métrica:
ai_code_legibility nullpara repositorios sin archivos fuente detectables — los proyectos de solo documentación no son penalizados
Cómo se calcula el valor
| Componente | Peso | Criterios |
|---|---|---|
| Código verificable por tipos | 45 | lenguaje con tipado estático → 45 pts; tipado dinámico con configuración de verificación de tipos → 27; ninguno de los dos → 0 |
| Tamaños de archivo manejables | 55 | (1 − sobredimensionados / total) × 55, donde un archivo fuente de más de ~60 KB (~1500 líneas) cuenta como sobredimensionado; se excluyen las rutas de código externo (vendored) y generado |
Por qué estas dos señales
- Los tipos son documentación comprimida. Una firma tipada le dice a un modelo qué acepta y qué devuelve una función sin leer su cuerpo — y un verificador de tipos convierte los malentendidos del modelo en errores inmediatos y mecánicos en lugar de defectos latentes. El crédito parcial para proyectos de tipado dinámico con un verificador (mypy, pyright, tsconfig) refleja que el tipado gradual captura buena parte del beneficio.
- La distribución de tamaños de archivo determina si un modelo puede sostener una unidad de código completa en su contexto. Una base de código de módulos enfocados puede leerse por partes; un archivo de 5000 líneas obliga a truncar, y en el truncamiento es donde se concentran los errores de los agentes.
El código externo (vendored) y el generado se excluyen para que un árbol vendor/ confirmado en el repositorio o unos bindings generados no distorsionen la medición.
Cómo leer el resultado
- La métrica lee estructura, no estilo — los nombres, los comentarios y la arquitectura no se califican (véanse las reglas de honestidad en Preparación para IA).
- El componente de tamaño de archivo es proporcional: un archivo sobredimensionado entre cincuenta cuesta poco; una base de código de monolitos se lee en consecuencia.
Cómo mejorar el valor
- Adoptar un verificador de tipos; en lenguajes dinámicos, incluso una configuración inicial permisiva obtiene el crédito parcial y crea el trinquete.
- Dividir los archivos que se acercan a las ~1500 líneas por sus costuras naturales.
- Mantener el código generado y externo en rutas con nombres convencionales para que quede excluido de la medición.
Relacionado: Bucle de verificación de IA · Interfaces para IA