dir2md — gera um blueprint em Markdown para repositórios de código que a IA consegue ler

🙋 Por que foi criado?
À medida que produtos SaaS crescem, a base de código fica cada vez mais complexa,
e diretórios aninhados, arquivos de configuração espalhados e ativos legados se tornam obstáculos para a compreensão de contexto não só para desenvolvedores, mas também para a IA.

Na prática, enquanto eu depurava uma ferramenta de CLI de IA baseada em Claude,
cheguei a aplicar correções sugeridas a partir de um prompt pedindo “análise do problema”,
e acabei passando várias vezes por situações desesperadoras em que arquivos importantes foram apagados por respostas que não entendiam corretamente a estrutura.

Com essa experiência, percebi que o problema não era a falta de documentação, mas sim o fato de que “a própria estrutura não ficava visível”, e foi assim que desenvolvi o dir2md — um gerador de mapas em Markdown centrado na estrutura.

🧭 O que ele faz?
O dir2md escaneia o projeto inteiro e gera um blueprint em Markdown otimizado para LLMs, para que tanto pessoas quanto IAs possam entendê-lo com facilidade. O objetivo não é criar apenas uma árvore de arquivos simples, mas sim um “mapa de código (code map)” com significado.

🔑 Principais recursos
▫️ Escaneamento de diretórios com base em .gitignore
▫️ Otimização de resumo com limite de tokens por arquivo + amostragem Head/Tail
▫️ Remoção de duplicatas com base em SimHash para eliminar arquivos semelhantes
▫️ Suporte básico a mascaramento de segredos (a versão Pro permite padrões avançados)
▫️ Vários modos de saída: árvore completa / resumo inline / somente resumo etc.
▫️ Reproduzível em CI/CD: --no-timestamp, --emit-manifest etc.

✅ Quando o dir2md é útil
▫️Quando você precisa entender rapidamente uma base de código legada complexa
▫️Ao documentar pastas de pesquisa ou diretórios de dados
▫️Ao fornecer informações estruturais seguras para agentes de IA
▫️Em situações em que um “resumo do projeto inteiro” é necessário em prompts para LLMs

🔗Links
▫️GitHub: https://github.com/Flamehaven/dir2md
▫️ Demo web (Hugging Face): https://huggingface.co/spaces/Flamehaven/dir2md-demo
▫️ Contexto de criação (Medium): https://medium.com/p/227a691a08aa