Khi bắt đầu một tác vụ mới cùng AI coding agent, thói quen phổ biến nhất của nhiều người là để mô hình tự do quét qua toàn bộ thư mục dự án để "nắm bắt bức tranh tổng thể".
Đó là cách tự nhiên nhất khi con người làm quen với một codebase lạ. Nhưng với một agent, đó là thao tác đắt đỏ nhất và dễ làm hỏng phiên làm việc nhất mà bạn có thể cho phép diễn ra.
Ở thời điểm tôi viết bài này, cây mã nguồn của website gồm 252 file (các file .ts, .tsx, .css, .md trong các thư mục chính) với tổng dung lượng 2.755.965 byte — tức hơn 2,7 triệu ký tự văn bản. Nếu để agent quét qua toàn bộ cấu trúc đó chỉ để tìm vị trí một hàm tiện ích hay một endpoint API, bạn đang bắt nó nạp một cuốn tiểu thuyết dày hàng nghìn trang vào đầu trước khi kịp gõ dòng lệnh đầu tiên.
Nhưng vấn đề không chỉ dừng lại ở kích thước của một lần đọc.
Cái giá của một lệnh quét cả repo
Cám dỗ lớn nhất của việc để agent tự quét nằm ở cảm giác tiện lợi: bạn không cần nhớ file nằm ở đâu, không cần chỉ rõ đường dẫn, chỉ cần đưa ra một yêu cầu chung chung rồi để agent tự lần mò.
Khi bạn gõ một câu lệnh mơ hồ như "hãy kiểm tra xem hệ thống đang xử lý lỗi thanh toán ở đâu", agent sẽ bắt đầu chạy các lệnh tìm kiếm diện rộng. Nó quét qua danh sách thư mục, mở thử vài file service, đọc lướt qua các route API, rồi lần theo các component giao diện.
Sau năm hoặc mười lượt gọi công cụ, nó có thể tìm ra đúng đoạn mã cần sửa. Trông bề ngoài thì công việc đã hoàn thành êm đẹp: agent tìm ra file, sửa xong lỗi, và bài kiểm thử chạy qua.
Nhưng cái giá thực sự của thao tác đó chỉ bắt đầu xuất hiện ở những lượt tương tác tiếp theo.
Thứ agent đã mở ra sẽ ở lại đến hết phiên
Nguyên lý vận hành của các coding agent hiện đại như Claude Code dựa trên một cửa sổ ngữ cảnh tích lũy liên tục: mọi câu lệnh bạn gửi, mọi kết quả công cụ trả về, và mọi nội dung file mà agent đã đọc đều được giữ nguyên trong lịch sử phiên để duy trì tính nhất quán.
Điều đó có nghĩa là: 40 file mã nguồn mà agent vừa mở ra xem thử rồi thấy không liên quan sẽ không tự biến mất. Chúng nằm lại trọn vẹn trong bộ nhớ của phiên làm việc cho đến khi bạn chủ động đóng phiên.
Trong 27 phiên làm việc thực tế trên repo này (dữ liệu telemetry đóng băng ngày 2026-08-23), tổng lượng token xử lý ở phía đầu vào lên tới 736,7 triệu token. Trong đó, token đọc lại từ bộ nhớ đệm (cache read) chiếm tới 712,9 triệu token — tương đương 96,76%. Token mới mà tôi gõ vào hay file mới nạp thêm chỉ chiếm chưa đầy 3,24%.
Con số 96,76% đó nói lên một sự thật kinh tế rất rõ ràng: một lần quét rộng không bao giờ là chi phí một lần. Bạn không chỉ trả tiền cho 2,7 triệu byte ở đúng lượt quét đó; bạn đang cam kết sẽ trả tiền đọc lại 2,7 triệu byte đó ở lượt thứ mười, lượt thứ hai mươi, và lượt thứ năm mươi của cùng một phiên.
Hơn nữa, khi cửa sổ ngữ cảnh bị pha loãng bởi hàng chục file không liên quan, khả năng chú ý của mô hình bắt đầu suy giảm. Agent dễ bỏ sót các quy định đặc thù, lẫn lộn giữa các phiên bản hàm, và bắt đầu đoán mò logic ở những phần mã nguồn phức tạp.
Để giải quyết bài toán này mà không làm tê liệt khả năng định vị của agent, tôi dùng ba cơ chế thay thế rất cụ thể.
Bản đồ mã nguồn: trả về địa chỉ thay vì nạp nội dung
Cơ chế đầu tiên là dựng một bản đồ mã nguồn tinh gọn (docs/CODEMAP.md).
Sự khác biệt cốt lõi nằm ở ranh giới vận hành:
- Phần nằm thường trú ở đầu mỗi phiên (
CLAUDE.md20.929 byte vàAGENTS.md2.538 byte) chỉ chiếm tổng cộng 23.467 byte — tương đương khoảng 0,85% tổng dung lượng mã nguồn của cả dự án. Đây là phần duy nhất agent nạp sẵn trước khi gõ phím. - 99,15% còn lại của dự án không bao giờ được nạp tự do, mà được chỉ dẫn thông qua bản đồ mã nguồn (21.013 byte) và tài liệu kiến trúc (31.740 byte).
Bản đồ mã nguồn không chứa mã thực thi, không giải thích chi tiết thuật toán, và không sao chép lại nội dung file. Nó chỉ là một bảng ánh xạ hai cột cực kỳ ngắn gọn: cột bên trái là "Mục tiêu thay đổi", và cột bên phải là "Đường dẫn file cần sửa".
Khi cần sửa một luồng xử lý, agent chỉ đọc file bản đồ này. Nó mất vài trăm byte để biết chính xác file mình cần nằm ở đâu, rồi mở thẳng duy nhất file đó. Thay vì nạp 40 file để tìm một hàm, nó đọc một bảng chỉ đường và mở đúng một file duy nhất.
<!-- CUA-BAN-HANG-1 -->
📥 Tải miễn phí
Bộ Khung Repo Cho AI Agent
Để phiên phụ chịu phần bùng nổ ngữ cảnh
Tuy nhiên, thực tế sẽ luôn có những tình huống mà bản đồ mã nguồn không thể bao quát hết: khi bạn gặp một lỗi lạ phát sinh từ chuỗi phụ thuộc ngầm, khi cần rà soát tất cả các nơi đang sử dụng một chuẩn cũ, hoặc khi cần khảo sát cấu trúc của một thư viện bên ngoài.
Trong những trường hợp bắt buộc phải tìm kiếm diện rộng, nguyên tắc của tôi là: không bao giờ thực hiện việc tìm kiếm đó bên trong phiên làm việc chính.
Thay vào đó, tôi giao nhiệm vụ tìm kiếm cho một phiên phụ (subagent hoặc một cửa sổ terminal độc lập). Phiên phụ này có thể chạy các lệnh tìm kiếm phức tạp, mở hàng chục file mã nguồn, và tiêu tốn hàng trăm nghìn token để sàng lọc thông tin.
Toàn bộ sự bùng nổ dữ liệu đó diễn ra và kết thúc hoàn toàn bên trong cửa sổ ngữ cảnh của phiên phụ. Sau khi hoàn thành, phiên phụ chỉ gửi về phiên chính một kết luận ngắn gọn gồm ba dữ kiện: nguyên nhân gây lỗi, danh sách hai file cần sửa, và số dòng cụ thể.
Phiên làm việc chính nhận được kết quả chính xác mà không phải cõng theo một byte dữ liệu rác nào trong lịch sử bộ nhớ đệm của mình.
Khóa danh sách file ngay trong đề bài
Cơ chế thứ ba là thói quen khóa chặt danh sách file ngay từ khi viết yêu cầu giao việc.
Như tôi từng đề cập khi phân tích về cách đề bài sai làm hỏng việc của agent, một bản mô tả công việc chặt chẽ luôn đi kèm danh sách file mục tiêu được chỉ định sẵn. Khi đề bài ghi rõ phạm vi chỉ được tác động vào hai file cụ thể, agent sẽ đi thẳng vào trọng tâm công việc thay vì tốn thời gian và chi phí quét qua những thư mục xung quanh.
Điều tôi nhận ra
Nhìn lại quá trình tối ưu chi phí qua 27 phiên làm việc thực tế, bài học lớn nhất về việc quản trị mã nguồn gói gọn trong ba điều:
Thứ nhất, một bảng chỉ đường ngắn vài kilobyte luôn rẻ hơn việc thả cho mô hình tự do đi lục tung cả dự án.
Thứ hai, việc tìm kiếm diện rộng là cần thiết nhưng phải luôn được cách ly trong một không gian riêng biệt, không để bụi bặm tràn vào không gian làm việc chính.
Thứ ba, sự kiểm soát ở khoảnh khắc quyết định mở file nào là yếu tố then chốt định hình chi phí và độ chính xác của toàn bộ phần còn lại trong phiên làm việc.
Trước khi khép lại, tôi muốn nói rõ về phạm vi của những con số trong bài:
Con số 252 file và 2.755.965 byte là số đo thực tế trên repo này ở thời điểm hiện tại. Tỉ lệ 96,76% token đọc cache được tính toán từ 27 phiên Claude Code đo ngày 2026-08-23 với toàn bộ giá quy đổi về biểu giá Opus 5. Các con số này phản ánh đặc thù cấu trúc và thói quen làm việc của riêng tôi trên một dự án cụ thể.
Hiểu rõ cơ chế tích lũy ngữ cảnh giúp bạn chủ động thiết lập những rào chắn an toàn: giữ cho cửa sổ làm việc luôn gọn nhẹ, hướng agent vào đúng trọng tâm, và bảo đảm chi phí token luôn nằm trong tầm kiểm soát.
<!-- CUA-BAN-HANG-2 -->
Khuôn mẫu bảng chỉ đường CODEMAP và quy tắc phân luồng tìm kiếm cho agent được tôi đúc kết trong bộ Token Efficient Vibe Coding Kit để bạn gắn trực tiếp vào dự án của mình.
