dir2md — Tạo bản thiết kế Markdown để AI có thể đọc kho mã nguồn

🙋 Tại sao lại làm ra nó?
Khi sản phẩm SaaS ngày càng lớn, codebase cũng trở nên phức tạp hơn,
các thư mục lồng nhau, các tệp cấu hình rải rác và các tài sản legacy trở thành rào cản trong việc nhận diện ngữ cảnh không chỉ với lập trình viên mà cả với AI.

Trên thực tế, trong lúc gỡ lỗi một công cụ AI CLI dựa trên Claude,
tôi đã vài lần rơi vào tình huống tuyệt vọng khi áp dụng các chỉnh sửa được đề xuất theo prompt yêu cầu "phân tích vấn đề",
và do phản hồi không hiểu đúng cấu trúc, các tệp quan trọng đã bị xóa.

Qua trải nghiệm này, tôi nhận ra vấn đề không nằm ở việc thiếu tài liệu, mà là ở chỗ 'chính cấu trúc không được bộc lộ ra', và từ đó đã phát triển dir2md — trình tạo bản đồ Markdown lấy cấu trúc làm trung tâm.

🧭 Nó làm gì?
dir2md quét toàn bộ dự án để tạo ra một blueprint Markdown được tối ưu cho LLM, giúp cả con người lẫn AI đều dễ hiểu. Mục tiêu không phải là một cây tệp đơn thuần, mà là tạo ra một "bản đồ mã nguồn (code map)" có ý nghĩa.

🔑 Tính năng chính
▫️Quét thư mục dựa trên .gitignore
▫️Tối ưu tóm tắt bằng giới hạn token cho từng tệp + lấy mẫu Head/Tail
▫️Loại bỏ trùng lặp dựa trên SimHash để loại các tệp tương tự
▫️Hỗ trợ che giấu secret cơ bản (bản Pro hỗ trợ pattern nâng cao)
▫️Nhiều chế độ đầu ra: toàn bộ cây / tóm tắt inline / chỉ tóm tắt, v.v.
▫️Có thể tái lập trong CI/CD: --no-timestamp, --emit-manifest, v.v.

✅ Khi nào dir2md hữu ích
▫️Khi cần nhanh chóng nắm bắt một codebase legacy phức tạp
▫️Khi tài liệu hóa thư mục nghiên cứu/thư mục dữ liệu
▫️Khi cung cấp thông tin cấu trúc an toàn cho AI agent
▫️Khi prompt LLM cần “tóm tắt toàn bộ dự án”

🔗Liên kết
▫️GitHub: https://github.com/Flamehaven/dir2md
▫️Web demo (Hugging Face): https://huggingface.co/spaces/Flamehaven/dir2md-demo
▫️Bối cảnh phát triển (Medium): https://medium.com/p/227a691a08aa