Understand Anything: Bản Đồ Codebase Dạy Người Đọc, Không Phải Khoe Đồ

Tóm tắt nhanh

• Giải bài toán gì: Đọc 200,000 dòng code mà không có bản đồ. Bạn vừa join team. Senior duy nhất biết chỗ payment flow nằm đâu đã nghỉ hai tháng trước. README chốt commit gần nhất là năm 2023.
• Vì sao đáng quan tâm: Thời gian onboarding rút từ “hai tuần grep” xuống “một buổi chiều bấm chuột”. Nhân số đó với mỗi người mới và mỗi PR review thì ra một con số đẹp.
• Hợp với ai: Dev mới vào team, người sắp refactor một service chưa từng đọc, team ship thư viện mà người dùng cần đi quanh call graph.
• Khác biệt chính: Tree-sitter làm việc parse - đầu vào giống nhau, đầu ra giống nhau. LLM làm việc tree-sitter không làm nổi - tóm tắt bằng tiếng người, gắn layer kiến trúc, map sang business domain. Hai phần cùng nằm trong một file JSON.
• Use case ngon nhất: /understand xong /understand-chat Payment flow chạy ra sao? trên một repo bạn chưa mở bao giờ. Vài phút sau có câu trả lời kèm đúng file và chuỗi gọi.

---

Ngày đầu đi làm. Họ Slack cho bạn một link repo. 200,000 dòng. README sửa lần cuối hồi 2023 - của founder, từ thời còn ngủ ở văn phòng. Người duy nhất biết payment flow nằm đâu đã nghỉ hai tháng trước.

Team nào cũng có một bảo vật giống nhau. Tấm hình chụp whiteboard kiến trúc từ năm 2019, đem dán lên Confluence, kèm ba mũi tên vẽ bằng Sharpie nhìn cong queo, hai cái ô ghi “TBD”. Không ai sửa nữa. Không ai dám chắc còn đúng không. Không ai dám hỏi.

Understand Anything là một plugin Claude Code (chạy luôn Cursor, Codex, Copilot, Gemini CLI, Vibe, Trae - tổng cộng 14 nền tảng) quét codebase bằng một dàn agent, ghi ra duy nhất một file JSON ở .understand-anything/knowledge-graph.json, rồi mở web dashboard cho bạn pan, zoom, search và bấm vô từng node.

Mental model: bản đồ tàu điện cho code

Hãy coi nó như tấm bản đồ metro cho codebase. Không phải bản vẽ kỹ thuật của công trình sư. Là tấm bản đồ du khách - loại in cho người mới đến, chỉ rõ tuyến xanh dương đi từ khách sạn tới bảo tàng, ga chuyển tuyến tên gì, ra khỏi ga thì thấy quán cà phê nào trước. Bạn không cần biết kỹ thuật xây hầm. Bạn cần một tấm bản đồ mà ai đó đủ kiên nhẫn đã ngồi vẽ giúp.

Câu slogan của repo làm hết phần việc giải thích: “Graphs that teach > graphs that impress.” - bản đồ dạy người đọc mới đáng tiền, bản đồ flex thì khỏi. Mấy tool visualize code khác đa số vẽ ra hết mọi dependency tìm được, quẳng cho bạn một cuộn len rối tinh, gọi đó là engineering. Bạn nhìn. Bạn không hiểu gì hết. Cú twist ở đây là cho LLM đi viết nhãn tiếng người cho từng node và xếp tour dạy theo thứ tự mà một senior sẽ dẫn người mới đi.

Bốn câu lệnh là đủ

# Cài (Claude Code)
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

# Quét repo (pipeline đa-agent chạy)
/understand

# Mở dashboard tương tác trên trình duyệt
/understand-dashboard

# Hỏi thẳng cái graph, khỏi grep
/understand-chat Payment flow chạy ra sao?

Bốn câu trên là toàn bộ bề mặt người dùng cần biết trong tuần đầu. Cài, quét, mở, hỏi. Mấy thứ còn lại - diff impact, onboarding guide, business-domain map, ingest knowledge base - đều là một slash command nữa khi nào cần.

Tree-sitter + LLM: vì sao cú lai này thật sự work

Hai lượt quét, hai việc khác nhau, không giẫm chân nhau. Tree-sitter parse từng file thành concrete syntax tree rồi rút ra fact cấu trúc: import, export, function, class, call site, inheritance. Đầu vào giống nhau thì đầu ra cũng giống nhau, mỗi lần chạy. Đó là lý do graph có thể reproduce được.

Rồi LLM đọc lại file đó với cả phần cấu trúc đã có sẵn trong tay. Nó không phải đi rút import từ source lần nữa - cái đó đã được pass vô rồi. Nó rảnh tay để làm thứ nó giỏi: viết tóm tắt ngắn, gán layer kiến trúc, map file vô business domain, chọn file kế tiếp người mới nên đọc.

Pipeline đa-agent

/understand là một cuộc chạy tiếp sức của năm chuyên gia. Mỗi người chuyền cho người sau một thành phẩm giàu hơn một chút.

Agent	Việc
project-scanner	Đi qua cây thư mục. Nhận diện ngôn ngữ và framework
file-analyzer	Parse từng file. Xuất ra node và edge (chạy song song)
architecture-analyzer	Gắn layer cho từng node (API, Service, Data, UI, Util)
tour-builder	Sinh route dạy theo thứ tự dependency
graph-reviewer	Kiểm tra edge nào tồn tại thật. Bắt mấy reference treo lủng lẳng

file-analyzer là chỗ thắt cổ chai - và là chỗ đáng phải thắt cổ chai. Nó chạy năm file song song, hai chục tới ba chục file một batch, và chỉ phân tích lại file nào có fingerprint tree-sitter thay đổi từ lần chạy trước. Chi tiết cuối đó là khác biệt giữa “rerun mất một tiếng” với “rerun bằng một ly cà phê”.

Commit graph vô, đồng đội khỏi quét

Graph chỉ là một file JSON. Commit luôn. Đồng đội clone repo về, mở dashboard, khỏi cần chạy pipeline. Đây là cú move mà README chôn hơi sâu - đa số project coi graph là rác local. Ở đây, nó là hạ tầng có thể ship. README chỉ thẳng tới fork của GoogleCloudPlatform/microservices-demo (Go / Java / Python / Node) đã commit sẵn graph làm ví dụ kinh điển.

14 nền tảng, một câu install

Plugin chạy native trong Claude Code, đồng thời cài skill tự động trong Cursor và VS Code Copilot (auto-discovery), và mười hai chỗ khác qua một câu install: Codex, OpenCode, Antigravity, Gemini CLI, Pi Agent, Vibe CLI, Hermes, Cline, KIMI CLI, Trae, OpenClaw, Copilot CLI. Installer thả symlink vô đúng chỗ tùy nền tảng.

Hợp ở đâu, không hợp ở đâu

Dùng khi:

• Bạn vừa nhận lại repo mà không ai trên team hiện tại từng viết.
• Sắp refactor một service mà bạn chưa hiểu trọn vẹn.
• Doc onboarding của team là hai cái screenshot và một tiếng thở dài.
• Bạn ship thư viện và muốn user đi quanh nó mà không phải đọc từng file.

Bỏ qua khi:

• Codebase chỉ 5,000 dòng. Đọc thẳng luôn. Thật.
• Công ty cấm chạy LLM qua source vì lý do policy.
• Bạn cần “AI giải thích từng dòng code”. Cái đó là tool khác. Cái này là bản đồ, không phải hướng dẫn viên đứng kế bên đọc thuyết minh.

Mấy chỗ còn rít

Lần đầu chạy trên repo 200k dòng thì không nhanh. README ghi 20-30 file mỗi batch với năm worker song song, là engineering hợp lý, nhưng vẫn phải đọc từng file một lần. Tính một tiếng và một ly cà phê. Sau đó incremental chỉ vài chục giây cho commit kích thước thường.

Chất lượng nhãn phụ thuộc bạn chỉ nó đi model nào. Model nhỏ open-weights viết tóm tắt đọc như intern năm nhất đoán mò. Model frontier viết tóm tắt đọc như anh senior đã nghỉ hai tháng trước. Cấu trúc graph thì giống nhau. Tính dễ hiểu thì không.

Nếu không bật --auto-update, graph đã commit sẽ lệch ngay khoảnh khắc ai đó merge mà quên chạy /understand. Cái post-commit hook nằm trong README. Set up ngay ngày bạn commit graph lần đầu, kẻo sau đó bạn rơi vô đúng tình cảnh của cái whiteboard 2019, lần này thì là lỗi của bạn.

Graph lớn hơn 10 MB thì cần git-lfs. README nói thẳng luôn và đưa sẵn mấy dòng .gitattributes. OK thôi, nhưng nó là kiểu “đừng quên” mà nếu quên thì đau ở khoảnh khắc bất ngờ nhất.

Lời cuối

Ngày đầu trên codebase mới hồi xưa nghĩa là khảo cổ Confluence, search Slack kiểu “@deleteduser anyone know where login lives”, và cái quy trình chậm chạp, hơi quê - grep -r chạy qua đám folder mà bạn còn chưa biết đọc tên cho đúng. Hai tuần trôi qua trước khi gõ được dòng code nào mà không phải sửa typo.

Cái graph này không hiểu code giùm bạn. Nó chỉ trải bản đồ ra. Bạn vẫn phải đi tàu. Vẫn phải đi bộ từ ga về. Nhưng bạn không phải đoán mò tuyến nào nữa, và không phải khó xử hỏi manager payment flow nằm đâu - bởi bạn đã bấm vô node tên “payment” rồi và đọc xong những gì hiện ra.

Bản đồ dạy người đọc thắng bản đồ flex đồ. Câu đó trong README làm rất nhiều việc, và sau một tuần xài nó trên codebase thật, câu đó xứng đáng.

---

Lum1104/Understand-Anything · MIT · 33k · docs