dir2md — genera un plano en Markdown para que la IA pueda leer repositorios de código

🙋 ¿Por qué lo hice?
A medida que los productos SaaS crecen, la base de código se vuelve cada vez más compleja, y
los directorios anidados, los archivos de configuración dispersos y los activos legacy se convierten en obstáculos para entender el contexto, no solo para los desarrolladores sino también para la IA.

De hecho, mientras depuraba una herramienta CLI de IA basada en Claude,
pasé varias veces por la desesperante situación de aplicar correcciones sugeridas a partir de un prompt que pedía "análisis del problema",
y que archivos importantes terminaran eliminados por respuestas que no entendían bien la estructura.

A través de esta experiencia, me di cuenta de que el problema no era la falta de documentación, sino que "la estructura misma no se hacía visible", y eso me llevó a desarrollar dir2md, un generador de mapas en Markdown centrado en la estructura.

🧭 ¿Qué hace?
dir2md escanea todo el proyecto y genera un blueprint en Markdown optimizado para LLM, de modo que tanto las personas como la IA puedan entenderlo fácilmente. La meta no es un simple árbol de archivos, sino crear un "mapa de código (code map)" con significado.

🔑 Funciones principales
▫️Escaneo de directorios basado en .gitignore
▫️Optimización de resúmenes con límite de tokens por archivo + muestreo Head/Tail
▫️Eliminación de duplicados basada en SimHash para remover archivos similares
▫️Soporte básico para enmascarado de secretos (la versión Pro permite patrones avanzados)
▫️Varios modos de salida: árbol completo / resumen inline / solo resumen, etc.
▫️Reproducible en CI/CD: --no-timestamp, --emit-manifest, etc.

✅ Cuándo dir2md es útil
▫️Cuando necesitas entender rápidamente una base de código legacy compleja
▫️Cuando documentas carpetas de investigación o directorios de datos
▫️Cuando quieres dar a un agente de IA información estructural segura
▫️En situaciones donde un prompt para LLM necesita un “resumen completo del proyecto”

🔗Enlaces
▫️GitHub: https://github.com/Flamehaven/dir2md
▫️Demo web (Hugging Face): https://huggingface.co/spaces/Flamehaven/dir2md-demo
▫️Contexto de creación (Medium): https://medium.com/p/227a691a08aa