Bản đồ codebase được dựng như thế nào: ký hiệu, tầng, ngân sách token

Parse, không phải đoán

Bản đồ chỉ tốt bằng trình parse của nó. ContextBridge biên dịch mã của bạn bằng tree-sitter — cùng họ trình parse tăng tiến mà các editor dùng — chạy dưới dạng WebAssembly ngay trong tab trình duyệt, hỗ trợ 15 ngôn ngữ. Mọi ký hiệu đều đến từ một cây parse thật, nên dải dòng là chính xác chứ không phải ước lượng.

Sự chính xác này có những giới hạn có chủ đích. Tệp lớn hơn 512 KB bị cắt ngắn, tệp nhị phân bị bỏ qua, cây phụ thuộc, đầu ra build và tệp lock bị tỉa trước khi parse. Trần cứng là 4.000 tệp — được chọn để việc phân tích hoàn tất trong vài giây trên laptop, thay vì vài phút.

Tầng, hub, điểm vào

Trên bảng ký hiệu, bộ phân tích tiến hành phân loại. Các tệp gom thành tầng — API, service, dữ liệu, UI, hạ tầng — suy ra từ đường dẫn, import và cách đặt tên. Những tệp được import nhiều nhất nổi lên thành hub; các bootstrap, hàm main và bảng định tuyến nổi lên thành điểm vào. Đây là bảng phân tầng của một dự án mẫu thật (nhỏ), trích nguyên văn từ bản đồ được sinh ra:

| Layer         | Files | Lines | Notable                               |
|---------------|-------|-------|---------------------------------------|
| Core          | 4     | 60    | order-repo.ts, server.ts              |
| API Layer     | 3     | 53    | orders.ts, customers.ts, routes.ts    |
| Service Layer | 2     | 50    | order-service.ts, customer-service.ts |
| UI Layer      | 2     | 23    | order-list.tsx, format.ts             |
| Data Layer    | 1     | 13    | 001_init.sql                          |
| Test Layer    | 1     | 8     | order-service.test.ts                 |

Ngân sách token quyết định gì được giữ lại

Mọi tạo tác đều được sinh ra theo một ngân sách token bạn chọn, từ phác thảo nhanh đến bản đầy đủ không giới hạn. Bộ xếp hạng chấm điểm tệp theo mức liên quan đến câu hỏi bạn nêu — kèm mở rộng thuật ngữ đa ngôn ngữ, nên câu hỏi bằng tiếng Việt hay tiếng Trung vẫn khớp mã tiếng Anh — và theo tầm quan trọng cấu trúc: hub, điểm vào, và các tệp trên đường import của những ký hiệu đã khớp.

Những gì không vừa không bị âm thầm loại bỏ: tạo tác liệt kê những phần nó bỏ sót và nêu rõ giới hạn của chính nó ở đầu tệp. Một bản đồ có ngân sách, thừa nhận ranh giới của mình, đáng giá hơn — cho bạn và cho mô hình — so với một bản đầy đủ không giới hạn nhưng giấu chúng đi.

Những gì phân tích tĩnh không thể biết

Ở đây sự trung thực quan trọng hơn vẻ ấn tượng. Một bản đồ tĩnh không bao giờ thấy hành vi runtime: triển khai qua dependency injection, phản chiếu, dispatch động, feature flag và cách đấu nối theo môi trường đều vô hình với nó. Nhãn tầng là heuristic, mà heuristic thì có thể sai trong một codebase thích phá vỡ quy ước.

Vì vậy hãy coi bản đồ đúng như bản chất của nó: sự định hướng, không phải chân lý tuyệt đối. Các tạo tác được sinh ra cũng xoay quanh ý tưởng đó — chúng chỉ dẫn mô hình trả lời từ cấu trúc được cung cấp, nêu tên những tệp nó không có, và không bao giờ bịa ra cách triển khai. Một bản đồ được phép nói "tôi không biết" là một bản đồ bạn có thể tin để chỉ cho bạn nơi cần xem tiếp theo.