Cách tạo chỉ mục codebase trong Cursor

Bạn đã bao giờ rơi vào cảnh bất lực khi Cursor AI đưa ra những đoạn mã mẫu chung chung, hoàn toàn "lệch pha" với cấu trúc dự án của mình chưa? Sự khác biệt giữa một câu trả lời ngớ ngẩn và một giải pháp lập trình hoàn hảo nằm ở việc AI có hiểu toàn bộ mã nguồn của bạn hay không. Tính năng Codebase Indexing chính là chìa khóa vàng giúp Cursor "thấu thị" mọi mối quan hệ giữa các tệp tin, hàm và module trong dự án.

Bài viết này sẽ hướng dẫn bạn quy trình 7 bước lập chỉ mục codebase trong Cursor chi tiết nhất, giúp bạn làm chủ sức mạnh của lệnh @codebase, tối ưu tốc độ quét cho dự án lớn và sửa tận gốc các lỗi Indexing thường gặp. Cùng khám phá ngay theo hướng dẫn dưới đây nhé.

Tóm tắt nhanh quy trình hướng dẫn

Để lập chỉ mục codebase trong Cursor, thực hiện theo 7 bước sau:

1. Mở Cursor và đăng nhập tài khoản

2. Vào File → Open Folder

3. Chọn thư mục dự án cần lập chỉ mục

4. Nhấn Select Folder để tải project vào Cursor

5. Chờ Cursor tự động quét và lập chỉ mục toàn bộ file

6. Mở AI Chat panel và đặt câu hỏi về codebase để kiểm tra

7. Nếu AI phản hồi chính xác về code trong project, lập chỉ mục đã hoàn tất

Toàn bộ quá trình mất từ vài giây đến vài phút tùy quy mô dự án.

Chuẩn bị trước khi bắt đầu

• Cursor đã cài đặt và đăng nhập: Tải phiên bản mới nhất tại cursor.com. Đăng nhập bằng tài khoản Cursor hoặc GitHub.

• Project folder đã sẵn sàng trên máy: Cursor index từ local folder, không phải từ URL hay cloud storage. Nếu project đang trên GitHub, hãy clone về máy trước (git clone [URL]).

• Ổ cứng còn trống: Với dự án lớn, Cursor lưu dữ liệu index cục bộ. Thông thường không đáng kể, nhưng với monorepo hàng chục nghìn file thì cần vài trăm MB.

• Biết cần loại trừ file nào: Thư mục node_modules, .venv, dist, build, các file data lớn không cần đưa vào index - chúng chỉ làm chậm quá trình mà không giúp ích cho AI. Xem phần Tối ưu indexing để biết cách cấu hình.

Hướng dẫn chi tiết các bước lập chỉ mục codebase trong Cursor

Bước 1: Mở Cursor và đăng nhập tài khoản

Khởi động ứng dụng Cursor. Nếu chưa đăng nhập, nhấn vào Sign in ở góc dưới bên trái và hoàn tất xác thực. Bạn cần đăng nhập để Cursor lưu trạng thái index và cài đặt cá nhân hóa.

Bước 2: Vào File và chọn Open Folder

Nhấn vào menu File ở thanh công cụ phía trên, sau đó chọn Open Folder từ danh sách thả xuống. Hoặc ở ngay trên màn hình chính như ở dưới đây.

Hoặc bạn có thể thao tác nhanh hơn bằng cách nhấn tổ hợp phím Cmd+O (macOS) hoặc Ctrl+K, Ctrl+O (Windows/Linux) để mở hộp thoại chọn thư mục ngay lập tức.

Trong hộp thoại chọn thư mục, điều hướng đến nơi chứa project của bạn. Hãy chọn thư mục gốc của project (root folder) - tức là thư mục chứa file package.json, requirements.txt, Cargo.toml, hay bất kỳ file cấu hình nào là "gốc" của dự án.

Lưu ý: Không nên mở một thư mục con của project. Cursor cần nhìn thấy toàn bộ cấu trúc từ gốc để lập chỉ mục chính xác các mối quan hệ giữa module. Miễn sao đường dẫn trong thanh địa chỉ của hộp thoại trỏ đến đúng thư mục gốc project là được.

Bước 3: Nhấn Select Folder để tải project

Sau khi điều hướng đến đúng thư mục, nhấn nút Select Folder (hoặc Open tùy hệ điều hành) để xác nhận lựa chọn và tải project vào Cursor.

Cursor sẽ đóng hộp thoại và mở giao diện editor với cây thư mục của project hiển thị ở sidebar bên trái.

Kiểm tra: Sidebar bên trái hiển thị cây thư mục với tên project ở trên cùng.

Bước 4: Chờ Cursor tự động lập chỉ mục

Ngay sau khi mở folder, Cursor tự động bắt đầu quét và lập chỉ mục toàn bộ file trong project. Bạn không cần làm gì thêm ở bước này - chỉ cần chờ.

Thời gian chờ ước tính:

• Dự án nhỏ (< 100 file): gần như tức thì

• Dự án vừa (vài trăm đến vài nghìn file): 30 giây đến 2 phút

• Dự án lớn (hàng chục nghìn file): 5-15 phút lần đầu; những lần sau nhanh hơn vì Cursor chỉ cập nhật file thay đổi

Bạn có thể kiểm tra trạng thái indexing ở thanh trạng thái dưới cùng - thường có biểu tượng vòng tròn xoay hoặc chữ "Indexing..." khi đang xử lý.

Bước 5: Mở AI Chat và đặt câu hỏi thử nghiệm

Nhấn Cmd+L (macOS) hoặc Ctrl+L (Windows/Linux) để mở panel AI Chat. Trong ô nhập liệu, gõ @codebase để báo cho Cursor biết bạn muốn hỏi về toàn bộ codebase, sau đó đặt một câu hỏi cụ thể về project.

Ví dụ câu hỏi thử nghiệm tốt:

• @codebase Hàm xử lý authentication nằm ở file nào?

• @codebase Dự án này dùng những dependencies chính nào?

• @codebase Có bao nhiêu API endpoint trong project này?

Kiểm tra hiệu quả: AI trả lời đúng tên file, đúng tên hàm hoặc đúng thông tin về cấu trúc project - không phải câu trả lời chung chung.

Bước 6: Xác nhận codebase đã sẵn sàng

Nếu AI Chat ở bước trên phản hồi chính xác và có thể trỏ đến đúng file hoặc dòng code trong project của bạn, codebase indexing đã hoàn tất thành công. Từ thời điểm này, tất cả các tính năng AI của Cursor - từ code completion, đến Chat, đến Agent Mode - đều hoạt động trong ngữ cảnh đầy đủ của project.

Kiểm tra cuối: Gõ @codebase giải thích cấu trúc tổng thể của project này và nhận được mô tả chính xác.

Kiểm tra indexing hoạt động đúng chưa

Ngoài cách thử qua Chat như trên, bạn có thể xác nhận trạng thái indexing trong Settings → General → Codebase indexing. Tại đây Cursor hiển thị số lượng file đã được lập chỉ mục và trạng thái của index (đã hoàn tất hay đang xử lý).

Nếu số file được index thấp hơn nhiều so với tổng số file thực tế trong project, rất có thể Cursor đang gặp vấn đề với một số file - xem phần Lỗi thường gặp bên dưới.

Lập chỉ mục codebase là gì và tại sao quan trọng?

Khi bạn mở một file riêng lẻ trong Cursor và hỏi AI về đoạn code đó, AI chỉ "nhìn thấy" những gì đang hiển thị trên màn hình. Nhưng code thực tế không tồn tại độc lập: một hàm gọi đến module khác, một component phụ thuộc vào config chung, một service kết nối với nhiều repository khác nhau.

Lập chỉ mục (indexing) là quá trình Cursor quét toàn bộ file trong project của bạn, chia nhỏ code thành các đơn vị có nghĩa (hàm, class, module), chuyển đổi chúng thành vector embedding cho tìm kiếm ngữ nghĩa, và xây dựng một bản đồ mối quan hệ giữa các thành phần trong codebase. Khi indexing hoàn tất, AI trong Cursor không còn chỉ "đọc file đang mở" - nó hiểu toàn bộ dự án.

Theo nghiên cứu nội bộ của Cursor công bố đầu năm 2026, semantic search được bổ trợ bởi codebase indexing giúp tăng độ chính xác câu trả lời AI lên 12,5% và tăng tỷ lệ người dùng giữ lại code AI đề xuất trong codebase thực tế. Đây không phải là tính năng tùy chọn - đây là nền tảng để mọi tính năng AI khác của Cursor hoạt động đúng.

Tối ưu indexing cho dự án lớn

Với các dự án lớn hoặc monorepo, indexing đầy đủ có thể chậm và một số thư mục không có giá trị gì cho AI. Giải pháp là tạo file .cursorignore ở thư mục gốc của project với cú pháp giống .gitignore:

node_modules/
   .venv/
  dist/
  build/
  .next/
  coverage/
  *.log
  *.lock

File .cursorignore nói với Cursor những thư mục và file nào cần bỏ qua khi lập chỉ mục. Với dự án có node_modules hàng chục nghìn file, thêm thư mục đó vào .cursorignore có thể giảm thời gian indexing từ vài phút xuống còn vài giây.

Ngoài ra, từ phiên bản 2026, Cursor hỗ trợ thêm .cursor/rules/ - thư mục chứa các file quy tắc giúp AI hiểu conventions của project (cách đặt tên, công nghệ ưu tiên, pattern code). Đây là bước nâng cao giúp Cursor không chỉ biết code nằm ở đâu mà còn hiểu cách code được tổ chức theo quy ước của team bạn.

Lỗi thường gặp và cách xử lý

• Indexing chạy mãi không xong: Thường do có quá nhiều file không cần thiết (như node_modules). Tạo file .cursorignore và loại trừ các thư mục lớn, sau đó restart Cursor và thử lại.

• @codebase không trả lời đúng về project: Có thể indexing chưa hoàn tất hoặc bạn đang hỏi về file chưa được lập chỉ mục. Vào Settings kiểm tra trạng thái, đợi indexing hoàn tất hoàn toàn rồi thử lại.

• Cursor không nhận ra file mới vừa thêm: Cursor cập nhật index theo cơ chế incremental (chỉ quét file thay đổi), nhưng đôi khi cần vài giây. Nếu file mới vẫn không được nhận sau vài phút, thử nhấn Command Palette → "Cursor: Resync Index".

Câu hỏi thường gặp (FAQ)

Cursor có lưu dữ liệu index lên server của họ không?

• Có, theo cơ chế mặc định, Cursor lưu embedding của code lên server để hỗ trợ tính năng đám mây. Nếu làm việc với code nhạy cảm, bạn có thể bật Privacy Mode trong Settings - khi đó Cursor xử lý indexing hoàn toàn cục bộ.

Mỗi lần mở project có phải chờ indexing lại từ đầu không?

• Cursor lưu cache index trên máy, cho nên những lần mở sau chỉ cập nhật file đã thay đổi, nhanh hơn rất nhiều so với lần đầu tiên.

Cursor có thể index repository trên GitHub mà không cần clone về không?

• Không. Cursor cần file ở local để lập chỉ mục. Hãy clone repository về máy trước khi mở trong Cursor.

File index có bị xóa khi cập nhật Cursor không?

• Thông thường không. Cursor giữ nguyên cache index qua các lần cập nhật. Tuy nhiên nếu gặp vấn đề sau khi update, thử xóa cache index thủ công trong thư mục cấu hình của Cursor.