RepoFit
ProductoBuenas prácticasLa rúbricaPreciosEscanear un repo
EntrarAnaliza tu repo
Buenas prácticas

Cómo dejar un repositorio listo para agentes.

Cinco prácticas, en el orden en que más cambian las cosas. Cada una dice qué hacer, por qué ahorra tokens y errores, y qué medimos para saber si ya está.

Lo que cambia cuando el repositorio está listo.

No es que el agente sea más rápido. Es que deja de necesitarte para lo que puede averiguar y verificar solo.

  • Sesiones nuevas sin miedo

    Abrir una sesión limpia deja de ser empezar de cero: el contexto vive en el repositorio y no en el historial de tu chat. Se acabó el arrastrar una conversación de cien mensajes solo para no perder lo que ya explicaste.

  • Dejas de escribir el mismo prompt

    Las convenciones, las rutas y las reglas del negocio están escritas donde el agente las busca. No hay que dictárselas otra vez, ni acordarse de cuáles eran.

  • El mismo resultado, sin importar quién pregunte

    Dos personas, dos agentes distintos, el mismo repositorio: las reglas escritas son las mismas para todos. El resultado deja de depender de quién armó mejor el prompt.

  • El agente cierra el ciclo y tú apruebas

    Con comandos que se descubren y tests que afirman algo, puede intentar, verificarse y corregirse antes de pedirte revisión. Tú apruebas el resultado, no cada paso.

Por qué esto no es obvio

Porque casi nadie lo tiene hecho. Medimos más de 100 repositorios públicos —proyectos vivos, famosos y bien mantenidos— y la mediana saca 67 de 100: la mitad no tiene una sola instrucción para agentes y casi nueve de cada diez esconden archivos que no caben cómodos en una ventana de contexto. No es descuido: es que hasta ahora nadie medía esto, porque hasta ahora el que leía el código era una persona.

+100repositorios públicos medidos

67/ 100 · el score mediano

Documentación· 25 puntos

Escribe el mapa una vez, no en cada prompt.

Por qué te conviene

Un agente que no encuentra dónde vive una responsabilidad la busca, y buscar es leer. La documentación es el único contexto que se escribe una vez y sirve en todas las sesiones, para toda la gente y para todos los agentes — y a diferencia de un prompt, se revisa en un pull request.

Qué hacer

  • Una ficha por módulo que diga qué hace y dónde se toca
  • Un README de raíz con qué es el proyecto y cómo se corre
  • Un índice navegable, no archivos sueltos
  • Actualizarla al cerrar el cambio, no “después”

Qué medimos

  • Cobertura de la documentación15
  • Documentación al día5
  • README de la raíz3
  • Documentación navegable2
Instrucciones para agentes· 14 puntos

Deja las instrucciones donde el agente las busca.

Por qué te conviene

Los archivos de instrucciones son lo primero que abre cualquier agente. Si están vacíos, si se contradicen entre herramientas o si sus links están muertos, cada sesión arranca adivinando tus convenciones — y adivina distinto cada vez, que es la razón por la que el mismo pedido da dos resultados.

Qué hacer

  • Un adaptador por herramienta, todos apuntando a la misma documentación
  • Punteros, no copias: el conocimiento duplicado se desincroniza
  • Links vivos, porque uno muerto manda al agente a explorar
  • Dos o tres hechos innegociables, no un manual

Qué medimos

  • Instrucciones para agentes4
  • Coherencia entre adaptadores3
  • Enlaces de la doc vivos3
  • Contexto siempre activo2
  • Cómo verificar, dicho al agente2
Ejecutabilidad· 26 puntos

Que el agente pueda correr y verificarse solo.

Por qué te conviene

Si los comandos no se descubren, el agente los adivina o te pregunta. Si los tests no afirman nada, no puede saber si lo que hizo funciona, y el único verificador disponible eres tú, en cada cambio. Con tests que afirman, el ciclo intentar → verificar → corregir pasa a ocurrir sin ti.

Qué hacer

  • Los comandos declarados donde se buscan: scripts, Makefile o un README
  • Lockfile y versión de runtime fijadas, para que instale igual dos veces
  • Un `.env.example` con lo que el código lee de verdad
  • Tipado estricto y lint: dos verificadores más que no cuestan tu tiempo

Qué medimos

  • Volumen de tests3
  • Integración continua4
  • Amplitud de los tests4
  • Instalación reproducible4
  • Comandos descubribles4
  • Variables de entorno declaradas4
  • Verificador estricto3
Historia· 20 puntos

Cuida los archivos donde siempre se rompe.

Por qué te conviene

Los archivos que concentran los arreglos son los que un agente va a romper: son los que más han cambiado y los que menos perdonan. La historia de git dice cuáles son sin que nadie tenga que opinar, y también dice qué áreas las sabe una sola persona — que es donde el agente no tiene de dónde aprender.

Qué hacer

  • Partir los archivos que acumulan arreglos, no solo los grandes
  • Documentar las áreas que sabe una sola persona
  • Mensajes de commit que digan qué cambió y por qué
  • Cerrar o marcar las áreas que nadie toca desde hace un año

Qué medimos

  • Archivos de riesgo7
  • Conocimiento concentrado5
  • Áreas abandonadas3
  • Trazabilidad de los commits2
  • La doc acompaña al trabajo3
Estructura· 15 puntos

Que quepa en una ventana de contexto.

Por qué te conviene

Cambiar tres líneas de un archivo de 900 obliga a cargarlo entero, y una carpeta de 80 archivos obliga a listarla para encontrar uno. Nada de eso aparece en tu factura como “estructura”: aparece como tokens.

Qué hacer

  • Ningún archivo de código gigante, y menos un bundle commiteado
  • Nada de dependencias versionadas dentro del repo
  • Un árbol navegable, sin carpetas-cajón ni código suelto en la raíz
  • Una sola librería por rol: dos clientes HTTP obligan a adivinar cuál

Qué medimos

  • Archivos gigantes5
  • Dependencias commiteadas3
  • Navegabilidad del árbol4
  • Librerías con el mismo rol1
  • Archivos duplicados2

Lo que sí tenemos medido

En repositorios públicos de distintos lenguajes y tamaños, un agente real (Claude Opus 5) intentó verificar contra el código lo que su documentación afirmaba. Cuanto mejor documentado el repositorio, más de lo que dice resistió la verificación: 81 de cada 100 afirmaciones en el tercio mejor documentado, contra 51 en el peor. Mirando solo aplicaciones, 80 contra 59.

Cobertura de la documentaciónLo que el agente pudo verificar
  • El tercio peor documentado46 · 51
  • El tercio del medio68 · 66
  • El tercio mejor documentado95 · 81

Repositorios públicos de varios lenguajes, medidos con juez real. Es una relación observada: un repositorio bien documentado suele estar mejor mantenido en todo lo demás. El tamaño explica mucho menos que la documentación.

RepoFit

Y cómo te lleva RepoFit ahí

Cada práctica de esta página es un grupo de checks de la rúbrica. El diagnóstico te dice en cuál estás parado, con la evidencia al lado y el costo en puntos de cada cosa que falta. Y cada check reprobado no devuelve solo su resta: devuelve su playbook, adaptado a tus convenciones, para que tu agente lo ejecute y tú apruebes el cambio.

Analiza tu repo gratisEscanear un repo público
La rúbricaProducto
Analiza tu repo gratisEscanear un repo público

Sin tarjeta. Tu código no sale de tu máquina.