El contexto para agentes de IA mide si un repositorio proporciona a los agentes de codificación con IA orientación y documentación legible por máquinas. Un agente situado en una base de código desconocida afronta el mismo problema que una persona recién contratada — salvo que lee el material de incorporación en milisegundos, en cada sesión. Los proyectos que dejan ese material por escrito obtienen resultados de agente mediblemente mejores.
- Categoría: Preparación para IA (30 % dentro de la categoría)
- Peso en el índice general: 1.2%
- Clave de la métrica:
ai_agent_context
Cómo se calcula el valor
| Componente | Peso | Evidencia |
|---|---|---|
| Instrucciones para agentes | 45 | CLAUDE.md, AGENTS.md, .cursor/rules, instrucciones de Copilot, GEMINI.md o equivalente; un archivo por debajo de ~200 bytes se registra como esbozo y obtiene crédito parcial |
| Documentación legible por máquinas | 15 | presencia de llms.txt o llms-full.txt |
| Historial de commits legible | 40 | proporción de commits humanos que declaran su intención; puntuación completa a partir del 75% |
Por qué cuenta el historial de commits
La orientación escrita es un archivo que alguien tuvo que decidir crear, y la mayoría de los proyectos nunca lo tienen. El historial de commits es distinto: todo proyecto ya lo produce, y un agente lo consulta antes de modificar código que no conoce — para saber por qué se tomaron las decisiones de alrededor, no solo qué hace el código.
Un commit declara su intención cuando su asunto está estructurado — en forma de commit convencional, o referenciando la incidencia o el pull request detrás del cambio — o cuando su cuerpo explica el cambio en lugar de repetir el asunto. Cualquiera de las dos formas califica, porque exigir solo una sería parroquial: el kernel de Linux no escribe prefijos convencionales y casi siempre se explica, mientras que otros proyectos llevan un historial plenamente convencional con mensajes de una línea. Ambos son legibles; ambos cuentan.
Los commits generados por automatismos quedan excluidos, ya que los asuntos generados por máquina son uniformemente correctos y nada dicen sobre la práctica del propio proyecto.
Qué contiene un buen contexto para agentes
Un archivo de instrucciones eficaz cuenta a un agente lo que el README cuenta a un humano, más lo que solo saben los mantenedores: cómo compilar y probar, qué directorios importan, las convenciones del proyecto y las trampas («el contenedor sirve imágenes compiladas — reconstruir después de editar»). La convención llms.txt lo complementa al ofrecer a los modelos de lenguaje un índice curado de la documentación del proyecto.
La regla del esbozo existe porque las señales de presencia pueden manipularse: un CLAUDE.md vacío creado para obtener la insignia es detectablemente distinto de uno real, y la metodología pondera la sustancia allí donde resulta barato detectarla.
Cómo leer el resultado
- Las señales se basan en la presencia y el tamaño dentro del árbol de archivos; el contenido no se califica — el límite honesto declarado en toda la categoría de Preparación para IA.
- Cualquiera de las convenciones de instrucciones reconocidas cuenta; la metodología es neutral respecto a los proveedores de herramientas para agentes, en línea con la postura agnóstica en cuanto a herramientas de la postura de seguridad.
Cómo mejorar el valor
- Redactar un
CLAUDE.mdoAGENTS.mdsustantivo: comandos de compilación y pruebas, estructura, convenciones y escollos conocidos. Mantenerlo al día — es documentación con una audiencia ejecutable. - Añadir un
llms.txtque indexe la documentación del proyecto para su consumo por modelos de lenguaje. - Referenciar la incidencia o el pull request en el asunto del commit, o explicar el cambio en el cuerpo. Ambas cosas son disciplina de revisión corriente; ambas dejan un historial legible para quien — o para lo que — mantenga el proyecto a continuación.
Relacionado: Bucle de verificación de IA · Preparación para IA