smart-explore

Tổng quan về skill smart-explore

smart-explore làm được gì

Skill smart-explore là một quy trình khám phá codebase xoay quanh tìm kiếm theo cấu trúc, không phải đọc file thô ngay từ đầu. Nhiệm vụ chính của nó là giúp agent hiểu repository nhanh hơn bằng cách dùng các công cụ dựa trên AST như smart_search, smart_outline và smart_unfold trước khi tải toàn bộ file. Nếu bạn đang cân nhắc smart-explore cho điều hướng mã nguồn, khám phá kiến trúc hoặc debug có mục tiêu, lời hứa cốt lõi rất rõ ràng: lập bản đồ code trước, rồi chỉ đọc đúng những phần thực sự quan trọng.

Ai nên cài smart-explore

smart-explore phù hợp nhất với những người thường xuyên nhờ AI kiểm tra các codebase chưa quen thuộc và muốn giảm token bị lãng phí cũng như bớt cảnh “lướt file” ngẫu nhiên. Đặc biệt hữu ích cho các tình huống:

• review code và phân tích phạm vi ảnh hưởng của thay đổi
• onboard vào repository lớn
• tìm phần triển khai thực sự đằng sau một tên tính năng
• định vị symbol, handler, service và call site nhanh chóng
• giảm các vòng lặp khám phá ồn ào bằng Read/Grep/Glob

Trường hợp khớp nhất là smart-explore for Code Review, nơi việc hiểu cấu trúc và ranh giới symbol quan trọng hơn chuyện đọc từng dòng.

Bài toán thực sự mà smart-explore giải quyết

Phần lớn các lần khám phá repository thất bại vì agent bắt đầu đọc file quá sớm. smart-explore thay đổi hành vi đó. Thay vì “mở file cho tới khi thấy thứ gì có vẻ liên quan”, nó đẩy quy trình theo thứ tự:

1. tìm các symbol khớp trong một thư mục
2. xem outline cấu trúc của file liên quan
3. chỉ unfold đúng symbol bạn thực sự cần

Vì vậy, smart-explore skill không chỉ là một shortcut để tìm kiếm; nó còn là một nguyên tắc ra quyết định về lúc nào không nên đọc cả file.

Điều gì khiến smart-explore khác với một prompt thông thường

Một prompt bình thường có thể bảo model “hãy làm cho hiệu quả”, nhưng smart-explore cung cấp thứ tự dùng công cụ rất cụ thể và một lối thay thế rõ ràng cho thói quen duyệt repository mặc định. Điểm khác biệt không nằm ở việc tài liệu sâu hơn; nó nằm ở việc ghi đè hành vi một cách dứt khoát: dùng smart_search/smart_outline/smart_unfold làm tuyến khám phá chính thay vì Read, Grep, Glob hoặc kiểu tự mò file theo tình huống.

Điều cần quan tâm trước khi cài smart-explore

Câu hỏi lớn nhất trước khi áp dụng không phải là “ý tưởng này có hay không?” mà là “môi trường công cụ của mình có phù hợp không?”. smart-explore chỉ thực sự có ý nghĩa nếu hệ thống của bạn đã expose đúng các MCP tool tương ứng. Bản thân skill này khá nhẹ và chủ yếu dựa vào chỉ dẫn; giá trị thực tế của nó phụ thuộc vào việc agent của bạn có gọi được các công cụ khám phá theo cấu trúc mà skill nhắc tới hay không.

Cách dùng skill smart-explore

Xác nhận dependency công cụ trước

Trước khi thử bất kỳ luồng smart-explore install nào, hãy kiểm tra xem môi trường của bạn có hỗ trợ các MCP tool sau hay không:

• smart_search
• smart_outline
• smart_unfold

Skill này không thay thế các tool đó và cũng không đi kèm chúng. Nó thay đổi chiến lược khám phá của agent. Nếu các tên tool này không có trong client của bạn, smart-explore usage sẽ chỉ dừng ở mức ý tưởng chứ khó triển khai thực tế.

Ngữ cảnh cài đặt và vị trí của skill

Đường dẫn repository của skill này là:

plugin/skills/smart-explore

Mẫu lệnh cài đặt thường dùng cho nhóm repo này ở cấp trang là:

npx skills add thedotmack/claude-mem --skill smart-explore

Vì SKILL.md upstream không có sẵn lệnh cài đặt riêng, hãy xem lệnh trên là điểm vào thực tế để cài skill trong bộ sưu tập này, rồi kiểm tra lại local skill loader và cấu hình MCP của bạn.

Hãy đọc file này trước

Bắt đầu với:

• plugin/skills/smart-explore/SKILL.md

Không có thêm các file README.md, metadata.json, rules/ hay resources/ nào hỗ trợ skill này, nên gần như toàn bộ hướng dẫn hữu ích đều tập trung trong đúng một file đó. Điều này thuận tiện cho việc đánh giá nhanh, nhưng cũng có nghĩa là bạn không nên kỳ vọng có thêm ví dụ sâu hơn hoặc tài liệu cho edge case ở nơi khác.

Mẫu dùng smart-explore cốt lõi

Skill này được xây quanh một workflow 3 lớp:

1. smart_search để tìm file và symbol liên quan
2. smart_outline để xem cấu trúc file mà không cần tải cả file
3. smart_unfold để lấy đầy đủ đúng symbol bạn cần

Đây là phần thực hành cốt lõi của smart-explore guide. Nếu bạn bỏ qua bước 1 và bắt đầu đọc nguyên file ngay, thì thực ra bạn chưa dùng skill theo đúng cách nó được thiết kế.

Prompt đầu tiên nên nêu rõ mục tiêu và phạm vi

Prompt yếu:

“Tìm bug trong auth.”

Prompt tốt hơn:

“Use smart-explore on ./src to find where token refresh is implemented. Start with smart_search for refresh token, outline the top 2 matching files, then unfold the main refresh handler and summarize control flow.”

Vì sao cách này tốt hơn:

• nó nói rõ agent phải kích hoạt hành vi của skill
• nó xác định cụm từ tìm kiếm
• nó thu hẹp đường đi
• nó yêu cầu xem cấu trúc trước khi đọc code đầy đủ

Cách biến một mục tiêu thô thành prompt smart-explore tốt

Để có smart-explore usage mạnh hơn, hãy đưa vào các thông tin sau:

• chủ đề hoặc tên tính năng
• đường dẫn gốc để tìm kiếm
• số lượng kết quả mong muốn
• bạn muốn discovery, review, tracing hay extraction
• nếu tìm thấy thì nên unfold symbol nào

Mẫu:

“Use smart-explore in <path>. Search for <concept>, return up to <n> ranked symbols, outline the most relevant files, then unfold the symbol most likely responsible for <job-to-be-done>. Avoid reading full files unless the outline is insufficient.”

Workflow tốt nhất của smart-explore for Code Review

Khi review code, đừng vội yêu cầu agent “review toàn bộ diff” nếu ngữ cảnh codebase vẫn chưa rõ. Trình tự tốt hơn là:

1. tìm theo tên tính năng, class, endpoint hoặc function mà thay đổi chạm vào
2. outline các file bị tác động để hiểu cấu trúc xung quanh
3. chỉ unfold những symbol đã thay đổi hoặc các symbol liền kề
4. so sánh logic đã thay đổi với interface, validator hoặc caller gần đó
5. chỉ đọc cả file khi ngữ cảnh ở mức symbol vẫn chưa đủ

Cách này giảm nhiễu và giúp người review hiểu phần code thay đổi đang gắn với cấu trúc nào.

Khi nào nên dùng smart_search trước

Dùng smart_search khi bạn biết khái niệm mình cần nhưng chưa biết chính xác file nào. Các truy vấn phù hợp gồm:

• tên tính năng
• tên endpoint
• thông báo lỗi
• thuật ngữ domain
• tên method
• chuyển trạng thái

Skill này khuyên rõ ràng rằng không nên dùng Grep, Glob, Read hoặc find cho bước khám phá ban đầu nếu đã có structural search. Lý do là chất lượng quyết định: các kết quả symbol được xếp hạng thường hữu ích hơn nhiều so với các text hit thô.

Khi nào nên dùng smart_outline tiếp theo

Dùng smart_outline khi bạn đã tìm được một file có khả năng phù hợp nhưng chưa muốn đi vào chi tiết triển khai. Đây là bước đúng khi bạn cần biết:

• trong file có những class hoặc function nào
• symbol mục tiêu có thực sự nằm ở đó không
• cấu trúc top-level bắt đầu và kết thúc ở đâu
• file đó có đáng để đọc toàn bộ hay không

Bước này đặc biệt hữu ích với các file lớn, nơi việc đọc cả file dễ tốn token vô ích.

Khi nào dùng smart_unfold

Dùng smart_unfold sau khi bạn đã xác định được symbol nhiều khả năng chứa đúng logic cần xem. Đây là cách có tín hiệu cao nhất để kiểm tra:

• một handler
• một service method
• một resolver
• một reducer
• một utility function

Nếu unfold quá sớm, bạn có thể bỏ lỡ symbol phù hợp hơn. Nếu unfold quá muộn, bạn lại mất thời gian outline các file vốn đã quá rõ là liên quan.

Ví dụ prompt thực tế giúp cải thiện chất lượng đầu ra

Ví dụ 1:

“Use smart-explore on ./src to locate the shutdown sequence. Search shutdown, outline the top relevant file, then unfold the main shutdown function and identify its dependencies.”

Ví dụ 2:

“Use smart-explore for Code Review on ./app. Search for rate limit, outline matching middleware files, then unfold the enforcement symbol and summarize request flow and likely edge cases.”

Ví dụ 3:

“Use smart-explore to find where email verification is triggered. Search verify email, rank up to 10 results, outline the top 3 files, and unfold the symbol that sends or schedules the verification.”

Câu hỏi thường gặp về skill smart-explore

Có đáng cài smart-explore nếu tôi đã viết prompt tốt rồi không

Có, nếu môi trường của bạn hỗ trợ các tool mà nó cần. Lợi ích của smart-explore không chỉ là cách diễn đạt prompt tốt hơn; nó là một chính sách khám phá mạnh hơn. Nó khiến agent ưu tiên khám phá theo cấu trúc thay vì lang thang file này sang file khác, vốn thường mới là nguồn gốc thực sự của việc tốn thời gian.

smart-explore có thân thiện với người mới không

Ở mức tương đối. Ý tưởng thì đơn giản, nhưng người mới dễ bị chặn nếu chưa hiểu khác biệt giữa khám phá symbol và đọc file, hoặc nếu cài skill khi chưa có MCP tool cần thiết. Nếu bạn mới bắt đầu, hãy thử bằng một truy vấn hẹp cho một tính năng cụ thể thay vì giao cả repository một lúc.

Khi nào không nên dùng smart-explore

Hãy bỏ qua smart-explore khi:

• môi trường của bạn không có smart_search, smart_outline và smart_unfold
• bạn đã biết chính xác file nhỏ và symbol cần kiểm tra
• repository quá nhỏ đến mức đọc cả file còn rẻ hơn việc dựng quy trình theo cấu trúc
• tác vụ của bạn thiên về prose hơn là cấu trúc mã nguồn

smart-explore khác gì so với Grep hoặc Read thông thường

Grep trả về các khớp văn bản. Read trả về nội dung file thô. smart-explore được thiết kế để tìm và kiểm tra cấu trúc code ở cấp symbol trước. Điều đó thường mang lại xếp hạng tốt hơn, ranh giới rõ hơn và ít phải tải nguyên file không cần thiết hơn.

smart-explore có phù hợp với monorepo lớn không

Có, đây là một trong những trường hợp phù hợp nhất, miễn là các tool nền chạy tốt trong môi trường của bạn. Tư duy “lập chỉ mục trước, chỉ lấy khi cần” phát huy tác dụng mạnh nhất khi repo quá lớn để duyệt kiểu ngây thơ.

Tôi có thể chỉ dùng smart-explore for Code Review không

Có. Thực tế, code review là một trong những use case rõ ràng nhất vì reviewer thường cần hiểu các symbol lân cận và cấu trúc lời gọi mà không phải đọc lại toàn bộ mọi file bị chạm tới. smart-explore for Code Review đặc biệt hợp khi câu hỏi review là “thay đổi này đang nối với phần nào của hệ thống?”

Cách cải thiện skill smart-explore

Hãy dùng truy vấn tìm kiếm thông minh hơn, không phải rộng hơn

Chất lượng đầu ra của smart-explore phụ thuộc rất nhiều vào truy vấn đầu tiên. Truy vấn tốt thường kết hợp một thuật ngữ domain với một hành động, ví dụ:

• refresh token
• session revoke
• password reset
• shutdown
• rate limit

Các truy vấn quá rộng như auth hoặc user thường trả về tập symbol nhiều nhiễu và làm yếu cả workflow phía sau.

Luôn kèm phạm vi đường dẫn

Một trong những cách dễ nhất để cải thiện smart-explore usage là chỉ rõ search root, chẳng hạn ./src, ./app hoặc thư mục package. Không có phạm vi, kết quả có thể nhiều nhiễu hơn và chậm hơn, đặc biệt trong các repo lớn.

Yêu cầu xếp hạng và thêm bước ra quyết định

Đừng chỉ bảo agent đi tìm. Hãy yêu cầu nó chọn. Ví dụ:

“Search for invoice export in ./services, rank the top 8 symbols, explain which 2 are most likely relevant, then outline those files before unfolding one symbol.”

Cách này buộc phải có một giai đoạn chọn lọc và giảm tình trạng tool churn mù quáng.

Dùng outline để tránh đọc cả file quá sớm

Một kiểu thất bại phổ biến là quay lại đọc nguyên file ngay sau kết quả tìm kiếm đầu tiên. Để tận dụng smart-explore tốt hơn, hãy nói rõ với agent:

“Do not read full files unless the outline does not provide enough context.”

Như vậy workflow sẽ bám sát lợi thế lớn nhất của skill.

Cải thiện smart-explore for Code Review bằng prompt bám theo thay đổi

Với code review, hãy kết hợp vùng thay đổi với câu hỏi kiến trúc. Ví dụ:

“Use smart-explore on ./src/payments to review the new refund path. Search refund, outline affected files, unfold the entry-point symbol and the main downstream processor, then check for validation, idempotency, and error handling gaps.”

Cách này tốt hơn nhiều so với “review đoạn code này” vì nó hướng việc khám phá theo cấu trúc vào đúng rủi ro cần review.

Theo dõi các kiểu lỗi thường gặp nhất

Những vấn đề dễ gặp nhất là:

• thiếu MCP tool support
• từ khóa tìm kiếm quá mơ hồ
• nhảy thẳng từ tìm kiếm sang kết luận
• unfold nhầm symbol vì chưa từng outline file
• dùng skill trên repo quá nhỏ, nơi cách tiếp cận ưu tiên cấu trúc lại tạo thêm overhead

Các vấn đề này đều sửa được, nhưng chúng quan trọng hơn việc trau chuốt câu chữ trong SKILL.md.

Lặp lại sau kết quả đầu tiên thay vì làm lại từ đầu

Thực hành tốt trong smart-explore guide là thu hẹp dần theo vòng lặp. Sau lần chạy đầu tiên, hãy:

• tinh chỉnh truy vấn bằng một thuật ngữ cụ thể hơn
• thu hẹp đường dẫn
• tăng hoặc giảm max_results
• outline file ứng viên thứ hai
• unfold một symbol lân cận, không chỉ khớp đầu tiên

Thường cách này cho kết quả tốt hơn so với việc bỏ hẳn workflow và quay lại đọc file ngẫu nhiên.

Điều gì sẽ giúp chính skill smart-explore mạnh hơn

Tài liệu smart-explore hiện tại dùng được nhưng còn mỏng. Skill sẽ dễ áp dụng hơn nếu có thêm:

• một mục cài đặt rõ ràng
• một ví dụ cho người mới từ search tới unfold
• một ví dụ cho code review
• một mục ngắn “khi nào không nên dùng”
• một ghi chú làm rõ điều kiện tiên quyết về MCP/tool ngay từ đầu

Những bổ sung đó sẽ giảm việc phải đoán trước khi cài và giúp smart-explore skill dễ được kích hoạt đúng ngay từ lần đầu tiên.