Tóm tắt nhanh
- Bản đồ README phân cấp giúp Claude Code tìm file theo nội dung, thay vì phải dò lại toàn bộ cây thư mục.
- XDA ghi nhận một truy vấn giảm từ 260 xuống 9 giây; tổng thời gian của tám truy vấn giảm từ 382 xuống 79 giây. Đây là phép thử cá nhân, không phải mức tăng tốc mặc định.
- README chứa mô tả và đường dẫn, còn CLAUDE.md hướng dẫn agent cách sử dụng chỉ mục; cả hai không thay thế việc kiểm tra file thật.
- Nên bắt đầu trong thư mục ít nhạy cảm và đặt giới hạn truy cập trước khi quét, vì lời nhắc không phải cơ chế bảo mật cưỡng chế.
Claude Code có thể tìm đúng một file ngay cả khi tên file chẳng nói lên nội dung, nhưng cái giá là nhiều lượt mở thư mục và đọc thử. Trong phép thử cá nhân do XDA công bố, một bản đồ README giúp thời gian tìm chương trình assembly giảm từ 260 xuống 9 giây. Phần đáng áp dụng nằm ở cách chuẩn bị đường đi cho agent, không nằm ở lời hứa rằng AI sẽ luôn tìm nhanh hơn 96%.
Thay vì đổi tên hoặc sắp xếp lại tài liệu, cách làm này thêm một lớp mô tả bên trên cấu trúc hiện có. Nó phù hợp với người còn nhớ mình từng làm gì nhưng không nhớ đã lưu ở đâu, đặc biệt khi tên bài tập, bản xuất hoặc ảnh chụp màn hình quá chung chung.
README giúp agent biết nên tìm ở đâu trước khi đọc file
Chỉ mục hữu ích phải bổ sung được ý nghĩa mà tên file không thể hiện. Một danh sách đường dẫn vẫn buộc agent đoán xem tài liệu nào liên quan, còn mô tả bằng ngôn ngữ tự nhiên có thể nối nhu cầu tìm kiếm với đúng thư mục. Chẳng hạn, chương trình menu ATM trong phép thử mang tên labtask4.asm: phần mở rộng cho biết đó là mã assembly, nhưng tên không nói gì về chức năng rút hay gửi tiền.
Bản đồ phân cấp giải quyết việc này bằng một README gốc đóng vai trò mục lục, dẫn đến README chuyên biệt trong từng khu vực. Agent đọc mục lục để chọn nhánh, đọc mô tả ở nhánh đó rồi mới mở file ứng viên. Điều cần tránh là chép toàn bộ cây thư mục vào một tài liệu khổng lồ, vì như vậy chỉ chuyển công việc dò tìm từ hệ thống file sang một khối văn bản khác.
Trong cấu trúc XDA công bố, Claude tạo bảy README cùng một CLAUDE.md ở gốc; kết quả kiểm tra sau khi sửa lỗi là 309 liên kết và tham chiếu tên file hợp lệ. Các mục lục nhỏ bao phủ Desktop, Downloads, Documents và một số thư mục bài tập, thay vì tạo README cho mọi thư mục bất kể mức độ cần thiết.
Giá trị nằm ở phần mô tả quan hệ giữa tài liệu. Khi một file SQL nằm trong thư mục mang tên môn assembly, cách tổ chức vật lý dễ gây hiểu nhầm; chỉ mục có thể ghi rõ nội dung thực tế và dẫn từ chủ đề phù hợp đến file ấy mà không cần di chuyển nó. Cách này giữ nguyên đường dẫn cũ, tránh làm đứt các liên kết mà ứng dụng hoặc dự án đang sử dụng.
CLAUDE.md chỉ đường, không tự biến README thành bộ nhớ
README và CLAUDE.md cần đảm nhiệm hai việc khác nhau: một bên lưu mô tả tài liệu, bên kia đặt quy tắc điều hướng. Nếu chỉ tạo các README mà không yêu cầu agent dùng chúng, những phiên sau vẫn có thể quay lại tìm kiếm toàn ổ đĩa. Ngược lại, đưa mọi mô tả file vào CLAUDE.md sẽ làm phần chỉ dẫn luôn phải mang theo quá nhiều nội dung ít liên quan.
Theo tài liệu Anthropic, Claude Code nạp CLAUDE.md và CLAUDE.local.md trong thư mục làm việc cùng các thư mục cha khi bắt đầu phiên; các file chỉ dẫn trong thư mục con được nạp khi Claude đọc, ghi hoặc chỉnh sửa file ở khu vực đó. README thông thường không có cùng cơ chế tự nạp chỉ vì mang tên README. Agent phải được hướng dẫn đọc mục lục khi cần tìm tài liệu.
Quy tắc điều hướng nên ngắn và kiểm chứng được: bắt đầu từ mục lục gốc, đi theo nhánh liên quan, sau đó xác nhận đường dẫn tồn tại và nội dung file khớp yêu cầu. Anthropic khuyến nghị giữ mỗi CLAUDE.md dưới 200 dòng; việc tách phần mô tả chi tiết ra khỏi file chỉ dẫn phù hợp với mục tiêu tránh tiêu tốn ngữ cảnh cho thông tin không dùng đến.
Về kỹ thuật, chỉ mục có thể giúp giảm số lượt quét và lượng nội dung phải đưa vào cửa sổ ngữ cảnh, tức phần văn bản mô hình đang xử lý trong phiên. Nhưng giảm thời gian không tự động đồng nghĩa giảm chi phí theo cùng tỷ lệ. Phép thử này không công bố số token hay hóa đơn, và bản thân việc tạo, đọc, cập nhật README cũng có chi phí.
Đây cũng không phải hệ thống tìm kiếm dùng cơ sở dữ liệu vector. Các mô tả Markdown tạo đường dẫn bằng văn bản để agent lựa chọn bước tiếp theo; chất lượng tìm kiếm vì thế phụ thuộc vào cách viết chỉ mục, độ chính xác của liên kết và việc mô hình có tuân thủ quy trình hay không.
Mức giảm 96,5% thuộc một truy vấn khó, không đại diện mọi lần tìm
Chênh lệch lớn nhất xuất hiện khi agent phải suy ra nội dung từ một tên file ít thông tin. XDA so sánh hai phiên Claude Code dùng cùng mô hình Claude Sonnet 5.5 và bật --safe-mode để loại ảnh hưởng của các tùy chỉnh như CLAUDE.md, skills, hooks, plugin. Một phiên được yêu cầu đọc README, phiên kia bỏ qua toàn bộ README và dùng công cụ tìm file thông thường.
Điều này quan trọng vì kết quả đo trực tiếp lợi ích của hệ thống README khi có chỉ dẫn rõ ràng, chứ không chứng minh rằng CLAUDE.md tự nạp đã làm phiên thử nghiệm nhanh lên. Ở truy vấn menu ATM, cả hai phiên đều tìm ra cùng file trong thư mục DOS; khác biệt nằm ở quãng đường đi đến kết quả.
| Phép thử, thời gian hoàn tất hiển thị (giây, thấp hơn tốt hơn) | Claude Code dùng chỉ mục README | Claude Code bỏ qua README |
|---|---|---|
| Tìm chương trình assembly có menu ATM | 9 | 260 |
| Tổng tám truy vấn tìm file | 79 | 382 |
Số liệu: XDA Developers, hai phiên cùng mô hình Claude Sonnet 5.5 trên máy cá nhân của tác giả; thời gian lấy từ hiển thị hoàn tất của Claude Code.
XDA ghi nhận mức giảm 96,5% ở truy vấn ATM, còn mức giảm tổng thời gian của tám truy vấn vào khoảng 79%; phiên dùng README nhanh hơn ở bảy truy vấn và hòa ở truy vấn còn lại. Hai tỷ lệ trả lời hai câu hỏi khác nhau. Tổng thời gian giảm 79% không phải trung bình cộng mức giảm phần trăm của từng bài thử, và bài ATM chậm bất thường đóng góp phần lớn chênh lệch.
Ở cách tìm không có chỉ mục, riêng một lượt dò trong thư mục home được ảnh kết quả trên XDA ghi nhận mất 176,8 giây. Điều đó cho thấy phạm vi quét có thể ảnh hưởng lớn đến kết quả: README không khiến lệnh tìm kiếm chạy nhanh hơn, mà giúp agent tránh phải chạy một lượt tìm rộng như vậy ngay từ đầu.
Vẫn còn giới hạn cần giữ khi đọc con số. Đây là thử nghiệm trên một tập tài liệu cá nhân, chưa phải đánh giá lặp lại trên nhiều máy; bảng tổng hợp cũng không công bố thời gian riêng của toàn bộ tám truy vấn. Với file có tên rõ và nằm đúng nơi dự đoán, lợi ích có thể nhỏ hơn nhiều. Không có cơ sở để chuyển mức giảm này thành cam kết cho mọi máy hoặc mọi loại tài liệu.
Giới hạn quyền đọc phải có trước bản kế hoạch tạo README
Rủi ro đáng quan tâm nhất xảy ra khi agent khám phá thư mục, trước cả lúc tạo chỉ mục. Yêu cầu không đưa giấy tờ cá nhân vào README vẫn chưa đủ nếu agent đã đọc chúng trong quá trình khảo sát. Với máy dùng chung cho công việc và việc riêng, lựa chọn an toàn hơn là cấp quyền cho một thư mục tài liệu đã chọn, thay vì bắt đầu từ toàn bộ thư mục home.
Prompt trong phép thử có yêu cầu bỏ qua cache, dependencies và dữ liệu ứng dụng ẩn, đồng thời không di chuyển, đổi tên hay xóa file gốc. Trước khi chấp thuận tạo README, người dùng còn yêu cầu loại hoàn toàn file mật khẩu CSV, hồ sơ visa, thanh toán và giấy tờ định danh khỏi việc kiểm tra cũng như tham chiếu. Đây là phạm vi loại trừ cụ thể hơn nhiều so với câu “đừng đọc thông tin nhạy cảm”.
Tuy nhiên, chính tài liệu Anthropic phân biệt rõ CLAUDE.md là ngữ cảnh hướng dẫn, không phải cấu hình cưỡng chế. Muốn chặn hành động bất kể mô hình quyết định thế nào cần cơ chế kiểm soát ở công cụ, chẳng hạn hook PreToolUse; tài liệu cũng nêu các thiết lập từ chối quyền truy cập cho đường dẫn hoặc lệnh. Không nên coi một đoạn prompt là hàng rào duy nhất bảo vệ thông tin cá nhân.
Ngay cả tên file và mô tả ngắn cũng có thể tiết lộ dữ liệu. Một README không chép nội dung hợp đồng nhưng ghi tên khách hàng, loại giao dịch và vị trí tài liệu vẫn chứa thông tin cần bảo vệ. Với hồ sơ công việc, cần xem cả nội dung chỉ mục sẽ được lưu, chia sẻ hoặc đồng bộ đến đâu, thay vì chỉ kiểm tra xem file gốc có bị thay đổi hay không.
Câu lệnh “không tải dữ liệu lên mạng” cũng không tự chứng minh rằng việc xử lý hoàn toàn ở máy người dùng. Chặn agent dùng công cụ mạng khác với việc xác định dịch vụ mô hình đang xử lý nội dung ở đâu. Vì vậy, nên áp dụng cách này trước cho tài liệu ít nhạy cảm, có phạm vi truy cập rõ ràng và phù hợp chính sách dữ liệu của nơi làm việc.
Với tài liệu tiếng Việt, chất lượng mô tả đáng ưu tiên hơn số lượng README
Góc áp dụng đáng giá cho người dùng Việt Nam là bổ sung những từ thường dùng khi nhớ lại công việc, thay vì chỉ sao chép tên file. Một chỉ mục có ích cần phản ánh cách chủ sở hữu gọi dự án, nội dung và loại tài liệu; nếu tên file dùng tiếng Anh nhưng truy vấn thường bằng tiếng Việt, có thể yêu cầu mô tả song ngữ ở những mục liên quan. Đây là cách thiết kế chỉ mục nên thử, chưa phải kết quả đã được đo trong phép thử trên.
Cũng không cần lập tức phủ toàn bộ máy. Nên bắt đầu ở một thư mục bài tập hoặc một dự án đã hoàn tất, nơi có thể kiểm tra mô tả bằng tay và biết trước một số kết quả đúng. Yêu cầu agent trình kế hoạch trước khi ghi file, bảo toàn README hiện có và đánh dấu mục chưa hiểu thay vì tự đoán. Một mô tả sai có thể làm agent đi thẳng đến đáp án sai nhanh hơn.
Để biết có đáng duy trì hay không, cần thử trong phiên mới với cùng các câu hỏi và kiểm tra file kết quả, không chỉ nhìn thời gian phản hồi. Nên có cả câu hỏi không tìm thấy đáp án để xem agent có thừa nhận không biết hay suy diễn từ chỉ mục. Việc mở lại file thật phải là bước cuối bắt buộc, bởi đường dẫn hợp lệ chỉ chứng minh file tồn tại, không chứng minh nội dung đúng hoặc còn mới.
Chỉ mục hết hạn sẽ làm tốc độ trở thành vấn đề độ tin cậy
Phần khó dài hạn là giữ mô tả khớp với file sau mỗi lần di chuyển hoặc thêm tài liệu. Một liên kết có thể còn tồn tại nhưng trỏ đến phiên bản cũ; ngược lại, tài liệu mới sẽ không được tìm thấy nếu agent tin rằng README đã liệt kê đầy đủ mọi thứ. Cấu trúc gọn lúc khởi tạo chưa đảm bảo việc tìm kiếm vẫn đúng về sau.
Cách duy trì hợp lý là cập nhật theo vùng có thay đổi, không quét lại cả máy sau mỗi thao tác. Người dùng có thể yêu cầu bổ sung README khi kết thúc một dự án, ghi rõ phạm vi và thời điểm kiểm tra, rồi xác thực lại liên kết của nhánh đó. Đây là đề xuất tổ chức công việc, không phải tính năng tự động đã được triển khai trong phép thử XDA; vấn đề bảo trì ở thử nghiệm vẫn chưa có lời giải hoàn chỉnh.
Auto memory của Claude Code cũng không nên bị hiểu thành dịch vụ tự lập chỉ mục mọi tài liệu. Theo Anthropic, cơ chế này lưu những ghi chú Claude rút ra từ tương tác, với phần đầu MEMORY.md được nạp theo giới hạn 200 dòng hoặc 25 KB, tùy ngưỡng nào đến trước. Nó khác hệ thống README do người dùng chủ động xây dựng và không đảm bảo mọi file mới được phản ánh trong bản đồ.
Với kho tài liệu ổn định nhưng đặt tên khó nhớ, README phân cấp là một cách đáng thử để giảm việc tìm lại từ đầu mà không xáo trộn file gốc. Còn với Downloads thay đổi liên tục hoặc hồ sơ nhạy cảm, phạm vi quyền đọc và khả năng giữ chỉ mục đúng cần được giải quyết trước. Tìm nhanh chỉ có ích khi đường dẫn cuối cùng vẫn dẫn đến đúng tài liệu cần dùng.
Nguồn tham khảo: XDA Developers, Tài liệu Claude Code của Anthropic
