README es más útil de lo que piensas

Introducción

Se me ocurrió lo que parece una idea tonta y obvia, pero vale la pena explorarla:

• ¿Qué pasaría si escribiera READMEs contextuales?
• Si no les digo nada a los agentes de IA, ¿leerían el README o simplemente lo ignorarían?
• ¿Hay alguna forma de depurar esto o al menos medir la tendencia?
• ¿Los diferentes agentes se comportarán de manera consistente?
• ¿Necesito indicarles a los agentes que lean el README?

Configuración de Prueba

Herramientas Utilizadas

• Windsurf IDE v1.9544.1001+next.f2e3d6b002
• Versión de extensión: 1.48.2
• SO: Linux

Detalles Adicionales

• Sin archivos abiertos en el IDE al momento de la ejecución del prompt.
• Se utilizaron diez prompts exactamente idénticos.
• Mismo proyecto.
• En un directorio recién creado.
• Sin historial de git, o carpeta .git.
• Sin configuración de usuario o de projecto (windsurf).
• Sin memorias de Windsurf ni ninguna otra personalización (workflows, habilidades, reglas, etc.).

Justificación Experimental

Asumiendo que los READMEs son estándar en los proyectos y que los agentes de IA están entrenados para buscarlos, las pruebas proporcionan observaciones en lugar de respuestas definitivas, enfocándose en tendencias en el comportamiento de los agentes de IA.

Un tamaño de muestra de 10 intentos fue suficiente para identificar tendencias, ya que una consistencia del 100% en pruebas más pequeñas indica patrones fuertes sin necesidad de escalas mayores.

Estos experimentos destacan el potencial sin explotar de los READMEs para mejorar el desarrollo asistido por IA. Sirven como fuentes de información contextual, proporcionando detalles precisos sobre archivos, contenido, estructuras y subdirectorios. Los READMEs raíz pueden escanear y agregar datos de sub-READMEs con alta fidelidad.

Se eligió el modelo Haiku sobre modelos más avanzados como Sonnet u Opus para probar el rendimiento base; el éxito aquí sugiere que mejores modelos tendrían un mejor desempeño.

Hallazgos

Lógica de Búsqueda

La idea era: Pedirle al modelo que analice una carpeta y que me diga los pasos lógicos para recopilar información de esa carpeta.

Prompt utilizado:

1if I ask you to analyze this folder:
2
3<REDACTED>/subfolder1
4
5tell me your logical steps to gather information from this folder, 
6make me a list of bullets to explain your thinking step by step, 
7respond in chat, do not modify any files.

Resultados

Se marca como “E” si la respuesta es explícita sobre leer el README, “I” si la respuesta es implícita. Interpretación: Conteos más altos de ‘E’ (explícito) e ‘I’ (implícito) indican mejor conocimiento y utilización de los archivos README por parte de los modelos de IA.

Datos Específicos del README

La idea era: pedirle al modelo que encuentre datos específicos de un archivo README, sin indicar que debe buscar un archivo README.

La prueba consiste en que hay un archivo llamado config.yaml dónde se define un key llamado confidence, y el readme en la sub carpeta (no en root), define que significa ese valor en el config.yaml

Esta prueba, en mi opinión, muestra qué tan bien está diseñado un modelo para ser un asistente de IDE y qué tan bien puede entender el contexto antes de intentar responder con conocimiento existente. Se eligió la palabra “confidence” porque es una palabra que se usa en muchos contextos y probablemente el modelo esté tentado a usar su propio conocimiento para responder esta pregunta.

1Could you tell me what confidence is?
2
3And then explain me the logic you use to get the answer, 
4with brief bullets, step by step.

Interpretación: Conteos más altos de ‘T’ (correcto) muestran una mejor capacidad para extraer información específica de los READMEs sin instrucción directa, siendo conscientes de que los estamos invocando desde el IDE.

Los rojos son principalmente respuestas filosóficas o definiciones de diccionario.

README.md es Bueno, pero UN MOMENTO…!

No lo pongas en todas partes, creará mucho ruido. Sugiero usarlo solo cuando agregue valor.

Sí hacerlo:

• configuraciones complejas y no autoexplicativas, conjuntos de datos o variantes: donde no está claro qué significan los valores, o cuando es JSON donde no se permiten comentarios, README es un buen lugar para explicarlo.

• en carpeta examples/ o recipes/: Cada ejemplo concreto se vuelve autocontenido y descubrible; aumenta dramáticamente el valor del directorio de ejemplos para los recién llegados y colaboradores.

• es una carpeta de plugin/extension/adapter: Documenta puntos de integración, esquema de configuración, matriz de compatibilidad, limitaciones conocidas y ejemplo de uso dentro del sistema host; los usuarios a menudo llegan aquí directamente desde enlaces de documentación o búsquedas.

• carpeta de assets: Solo si los assets son complejos o tienen requisitos de licencia específicos.

• carpeta de módulo de característica/dominio (src/features/, src/domains/, src/modules/): Común en bases de código medianas/grandes—proporciona una descripción general rápida de responsabilidades, entidades principales, archivos importantes, preocupaciones transversales o invariantes; reduce el tiempo dedicado a comprender un módulo al entrar en la base de código.

No hacerlo:

• carpeta tests/spec a nivel de paquete: Las pruebas normalmente son autoexplicativas.

• carpetas muy pequeñas/de utilidad de un solo archivo: Cualquier explicación pertenece al README de la carpeta padre para evitar fragmentación.

Las respuestas de los prompts se perdieron - Soy tonto

Hice una de las acciones más tontas de mi vida, eliminé todos los prompts almacenados que tenía, de la manera más estúpida posible. Preparé un proyecto de GitHub para ello, llamé a git clone, y nunca puse la contraseña de la clave, así que se quedó ahí esperando. Copié archivos en esta carpeta, luego lo cancelé (no preguntes por qué) en el prompt de contraseña, a mitad de clonación. Git eliminó la carpeta con todo su contenido, incluyendo los prompts que dejé ahí. Testdisk no es una opción porque es un sistema de archivos btrfs, y en una computadora remota. Horas perdidas. Lección aprendida.