Cung cấp cho một AI agent ngữ cảnh của một repo lớn mà không cần trình lập chỉ mục cục bộ

Một repository lớn không vừa với một cửa sổ ngữ cảnh, và nếu bạn từng hướng một trình lập chỉ mục laptop vào một monorepo thực sự, bạn biết nó cũng không vừa một cách thoải mái ở đó — RAM tăng vọt, lần lập chỉ mục đầu tiên mất một giờ, và agent của bạn vẫn bắt đầu phiên tiếp theo bằng cách đoán file nào quan trọng.

Câu trả lời thông thường là chạy một trình lập chỉ mục bên cạnh editor, và với một repo vừa vặn thoải mái trên một máy, đó là một câu trả lời tốt. Nếu monorepo của bạn đã được lập chỉ mục nhanh trong Cursor và đó là nơi duy nhất bạn cần bản đồ, bài viết này không có gì để bổ sung — hãy bỏ qua nó.

Bài viết này nói về trường hợp khác — khi một agent cần một bản đồ có thể truy vấn của một repo lớn, và bạn không muốn chạy trình lập chỉ mục cục bộ để có được nó.

Khi nào trình lập chỉ mục cục bộ là công cụ sai

Một chỉ mục cục bộ giả định rằng code sống trên máy truy vấn nó, và ở quy mô monorepo thực sự, giả định đó bị căng thẳng ngay cả trong một editor duy nhất. Repo đơn giản là lớn hơn những gì bạn muốn giữ ‘ấm’ trên một laptop: bạn làm việc trong một package trong khi phạm vi ảnh hưởng nằm cách ba thư mục, và lần lập chỉ mục lạnh đầu tiên của một cây hai triệu dòng không phải là điều bạn muốn trải qua hai lần — dù trên máy của chính bạn, hay trên một CI runner chưa bao giờ clone cây đó trước đây. Hoặc một đồng nghiệp trong nhóm nên có thể truy vấn cùng bản đồ với bạn, mà không phải đợi máy của chính họ vật lộn qua cùng một chỉ mục.

Không điều nào trong số này là lý do để vứt bỏ một trình lập chỉ mục editor tốt. Đó là lý do để cũng có một bản đồ được lưu trữ mà bất kỳ agent nào của bạn cũng có thể truy vấn qua MCP.

Và vấn đề quy mô còn sâu hơn ‘quá nhiều file để dán vào’. Trên một cây lớn, câu hỏi thú vị hầu như không bao giờ là ‘cho tôi xem file này’ — mà là file nào, symbol nào, ai gọi nó, test nào. Một agent bắt đầu bằng cách liệt kê src/ và đọc ba kết quả đầu tiên sẽ vui vẻ bỏ lỡ handler trong apps/api và client được tạo ra trong packages/sdk. Điều bạn cần là truy xuất được xây dựng từ toàn bộ cây, sau đó được xếp hạng, sau đó được trích dẫn.

‘Ngữ cảnh của một repo lớn’ thực sự có nghĩa là gì

Đổ các file vào prompt không phải là ngữ cảnh — đó là một bản sao nhỏ hơn, tệ hơn của cây. Điều mà agent của bạn thực sự cần là đặt câu hỏi và nhận lại các câu trả lời được trích dẫn: symbol này được định nghĩa ở đâu và ai gọi nó, cái gì phụ thuộc vào module tôi sắp thay đổi, file test nào bao phủ hành vi này, và cây trông như thế nào ngay bây giờ, không phải quý trước.

Những câu trả lời đó phải đến từ một chỉ mục được xây dựng từ repo của bạn thay vì từ ký ức của model về repo của người khác, và chỉ mục đó phải sống ở một nơi nào đó ngoài cửa sổ ngữ cảnh của agent. Đối với vấn đề này, nó cũng nên sống ở một nơi nào đó ngoài laptop của bạn.

Một điều nữa mà các file hướng dẫn không thể làm cho bạn: CLAUDE.md và AGENTS.md là nơi thích hợp cho các quy ước và hành vi, nhưng chúng không phải là một bản đồ sống, được xếp hạng, có thể truy vấn của một cây hai triệu dòng. Sử dụng quy tắc cho hành vi; sử dụng trí thông minh của repo cho các sự kiện.

Chúng tôi xây dựng bản đồ trên cloud, bạn truy vấn nó từ bất kỳ client nào

Maguyva là một lớp ngữ cảnh codebase MCP từ xa. Bạn kết nối GitHub, chọn các repository của bạn, và có thể rời đi trong khi các pipeline cloud phân tích cây, xây dựng symbol và các cạnh đồ thị, và duy trì một bản đồ được xếp hạng — không bao giờ cần một trình lập chỉ mục cục bộ.

Khi bạn push code, các file đã thay đổi được phân tích theo từng phần, và các lớp đồ thị và xếp hạng được xây dựng lại theo lịch trình: hàng ngày trên gói miễn phí, hàng giờ trên các gói trả phí. Mỗi snapshot có dấu thời gian, để agent của bạn có thể biết phiên bản nào của cây nó đang đọc. Giới hạn trung thực ở đây là công việc cục bộ chưa đồng bộ hóa — một thay đổi chỉ tồn tại trong working tree của bạn, chưa bao giờ được push, vẫn chưa có trong bản đồ được lưu trữ.

Sau đó bạn kết nối bất kỳ client nào bạn đã đang sử dụng bằng cách thêm một khóa API vào cấu hình MCP của nó. Có các hướng dẫn thiết lập cho 24 client MCP đã được ghi chép, và bất kỳ client tương thích MCP nào khác hỗ trợ cấu hình chuẩn cũng có thể kết nối. Nếu Cursor là nơi bạn ở, trang Cursor đi theo con đường đó; cùng một máy chủ trả lời cho Claude Code, VS Code, Windsurf, Codex CLI và những cái khác.

Bạn không đổi editor. Bạn cung cấp cho agent của mình một bề mặt công cụ — 11 công cụ MCP trên khắp tìm kiếm, symbol, phân tích phụ thuộc, truy xuất file và ngữ cảnh repository — với phạm vi bao phủ hơn 279 ngôn ngữ và công nghệ dựa trên văn bản, điều này quan trọng hơn bạn nghĩ trên một monorepo đã ngừng là một ngôn ngữ duy nhất từ nhiều năm trước.

Các câu trả lời trở về có căn cứ, dưới dạng đường dẫn file kèm số dòng. Tìm kiếm ngữ nghĩa, cấu trúc, đồ thị và văn bản được hợp nhất thành kết quả được xếp hạng, để một câu hỏi như ‘cái gì phụ thuộc vào parseConfig’ không cho bạn một bãi đổ grep hay một mảnh ngữ nghĩa đơn lẻ, mà là nhóm nhỏ những địa điểm thực sự quan trọng.

Một hướng dẫn cụ thể

Đừng bắt đầu bằng cách lập chỉ mục toàn bộ công ty. Đây là con đường hiệu quả:

1. Chọn một repository mà bạn đã biết rõ — một package bạn có thể đánh giá bằng tay có giá trị hơn cây lớn nhất bạn có.
2. Bắt đầu miễn phí: 3 repo, 50 nghìn dòng đã lập chỉ mục, tất cả 11 công cụ, không có hạn mức truy vấn hàng tháng. Nếu repo đại diện của bạn lớn hơn thế, trang giá liệt kê các cấp không gian làm việc ($0, $19, $49, $149) theo phạm vi đã lập chỉ mục — không phải theo số lượng chỗ ngồi.
3. Kết nối GitHub và đợi lần lập chỉ mục đầu tiên hoàn tất. Bạn không biên dịch bất cứ thứ gì cục bộ.
4. Kết nối client MCP — vài dòng cấu hình. Maguyva là một máy chủ MCP từ xa, vì vậy không có plugin, không có tiện ích mở rộng, và không có editor thứ hai để áp dụng.
5. Đặt một câu hỏi bạn có thể xác minh. ‘Cái gì phụ thuộc vào parseConfig?’ hoặc ‘Việc hết hạn phiên đăng nhập được xử lý ở đâu?’ Sau đó mở kết quả file.ext:line được trích dẫn và kiểm tra chúng so với cây trước mặt bạn.
6. Chỉ sau khi các trích dẫn đã vượt qua thử thách tiếp xúc đó, bạn mới để agent chỉnh sửa.

Nếu repo đầu tiên phù hợp tốt và cây của bạn lớn, hãy tăng không gian làm việc để khớp với số dòng đã lập chỉ mục và nhịp độ xây dựng lại của bạn. Con người và agent chia sẻ cùng một số lượng người dùng — Maguyva tính phí theo không gian làm việc, không theo chỗ ngồi — vì vậy việc thêm một agent thứ ba vào vòng lặp không tốn gì của bạn.

Bài kiểm tra kích hoạt giống hệt với những gì tài liệu khuyến nghị cho bất kỳ lần chạy đầu tiên nào: lập chỉ mục một repo mà bạn đã biết, đặt một câu hỏi bạn có thể xác minh. Một repo lớn không thay đổi bài kiểm tra; nó chỉ làm cho một file đầu tiên sai trở nên tốn kém hơn.

Những gì cần theo dõi sau khi kết nối

Hãy để mắt đến ba điều. Độ mới: các gói trả phí xây dựng lại hàng giờ, các gói miễn phí hàng ngày, và công việc cục bộ chưa push sẽ không có trong bản đồ — đó là sự đánh đổi bạn chấp nhận. Phạm vi: lập chỉ mục một tập hợp repo đại diện, không phải mọi fork đã lưu trữ; tầng miễn phí được cố tình định cỡ để tìm hiểu xem các câu trả lời có đáng giữ lại hay không. Và xác minh: một bản đồ repo lớn không thể trích dẫn đường dẫn và số dòng chỉ là một cỗ máy đoán chậm hơn, vì vậy hãy để agent của bạn cho thấy vị trí trước khi nó giao bản vá.

Sau đó chạy cùng bài kiểm tra mà bạn sẽ chạy trên một repo nhỏ. Lập chỉ mục một repo mà bạn đã biết. Đặt một câu hỏi bạn có thể xác minh. Nếu bản đồ là thật, agent của bạn sẽ ngừng bắt đầu từ một cây lạnh.

// no laptop got hot building this map.