Claude Code trong codebase lớn: cách nó hoạt động và bắt đầu từ đâu

Claude Code đang chạy trong production ở những codebase quy mô thật: monorepo nhiều triệu dòng, hệ thống legacy hàng chục năm tuổi, kiến trúc phân tán trải trên hàng chục repo, ở các tổ chức có hàng nghìn engineer và cả những ngôn ngữ ít được coi là "thân thiện với AI" như C, C++, C#, Java, PHP. Điều khiến nó hoạt động được ở quy mô đó không phải bản thân model, mà là cái harness dựng quanh model — và mức độ bạn làm cho codebase của mình "đọc được" với một agent.

Bài này tóm tắt ba thứ: Claude Code điều hướng code bằng cách nào, những lớp mở rộng nào tạo nên harness, và bắt đầu từ đâu nếu bạn muốn triển khai trong một codebase lớn.

Vì sao Claude Code không index codebase của bạn

Cách tiếp cận thường thấy với codebase lớn là index trước: embedding toàn bộ repo, lưu vào vector database, rồi truy hồi các đoạn liên quan tại thời điểm hỏi — tức là RAG. Claude Code không làm vậy. Nó dùng agentic search: duyệt hệ thống file ngay tại chỗ, grep theo nội dung, glob theo pattern, đọc file cụ thể, lần theo reference — đúng cách một engineer điều hướng code. Không có index trung tâm nào cần dựng hay duy trì.

Đáng chú ý: các bản Claude Code thời đầu có dùng RAG với vector DB cục bộ, nhưng nhóm phát triển nhận thấy agentic search cho kết quả tốt hơn một cách nhất quán — đủ bất ngờ để chính họ ghi nhận lại. Lý do nằm ở chi phí ẩn của việc index ở quy mô lớn:

• Lỗi thời và trôi lệch. Khi hàng nghìn engineer commit liên tục, pipeline embedding không đuổi kịp. Index dễ trả về một hàm đã đổi tên tuần trước hoặc một module vừa bị xóa.
• Rủi ro bảo mật. Index phải nằm ở đâu đó — một bản sao của toàn bộ code, trở thành trách nhiệm pháp lý và bề mặt tấn công mới.
• Chi phí bảo trì. Index là một hệ thống nữa phải nuôi: tái dựng, đồng bộ, theo dõi.

Agentic search né được cả ba, vì mỗi phiên làm việc trực tiếp trên code sống. Cái giá phải trả là token và độ trễ — nó đọc nhiều file hơn cho mỗi tác vụ. Với phần lớn workflow lập trình, đánh đổi này là xứng đáng. Hệ quả kéo theo cũng quan trọng không kém: nếu agent điều hướng code như một con người, thì một codebase khó cho người mới cũng sẽ khó cho agent. Làm codebase dễ đọc trở thành điều kiện tiên quyết, không phải tùy chọn.

Harness: bảy điểm mở rộng

Phần lớn khác biệt giữa "Claude Code dùng được" và "Claude Code dùng tốt ở quy mô lớn" nằm ở bảy điểm mở rộng dưới đây. Mỗi điểm giải một bài toán riêng, và mỗi điểm có một sai lầm phổ biến đi kèm.

1. CLAUDE.md — nạp mỗi phiên

File context Claude tự đọc khi bắt đầu mỗi phiên. Dùng cấu trúc phân lớp: file gốc cho bức tranh lớn, file ở thư mục con cho quy ước cục bộ. Lỗi thường gặp: nhồi vào đây những chuyên môn tái sử dụng lẽ ra nên nằm trong skill, khiến mọi phiên đều nặng lên.

2. Hooks — kích theo sự kiện

Tự động hóa hành vi nhất quán xuyên suốt các phiên: ép lint và format một cách tất định, nạp context theo module khi khởi động, đề xuất cập nhật CLAUDE.md khi context còn tươi. Lỗi thường gặp: dùng prompt cho những việc đáng lẽ phải tự động hóa bằng hook.

3. Skills — nạp khi cần

Đóng gói chuyên môn chuyên biệt mà không làm phình mọi phiên, theo cơ chế progressive disclosure — chỉ nạp khi liên quan, và có thể giới hạn theo đường dẫn. Ví dụ: skill review bảo mật chỉ kích hoạt khi đang đánh giá lỗ hổng. Lỗi thường gặp: dồn tất cả vào CLAUDE.md thay vì tách thành skill.

4. Plugins — luôn sẵn sàng sau khi cài

Gói skill, hook và cấu hình MCP thành một package cài được, để phân phối một bộ thiết lập đã chạy tốt ra toàn tổ chức qua marketplace có quản lý. Lỗi thường gặp: để những thiết lập tốt nằm yên trong đầu vài người thay vì chia sẻ.

5. Language Server Protocol (LSP)

Cho Claude khả năng điều hướng ở cấp ký hiệu như IDE của lập trình viên: "go to definition", "find all references", phân biệt hai hàm trùng tên. LSP lọc hàng nghìn match không liên quan trước khi Claude phải đọc file — đặc biệt quan trọng với codebase đa ngôn ngữ và C/C++ ở quy mô lớn. Lỗi thường gặp: tưởng LSP tự cấu hình sẵn.

6. MCP servers

Nối Claude tới công cụ nội bộ, nguồn dữ liệu và API: tài liệu nội bộ, hệ thống ticket, nền tảng analytics. Các đội tiến xa còn phơi bày tìm kiếm có cấu trúc thành tool gọi được. Lỗi thường gặp: dựng kết nối MCP trước khi những thứ cơ bản chạy được.

7. Subagents — khi được gọi

Những instance Claude tách biệt với cửa sổ context riêng. Một subagent read-only đi khảo sát một subsystem rồi trả findings về cho agent cha; agent cha mới chỉnh sửa với bức tranh đầy đủ. Mô hình này cho phép làm song song và tách phần khám phá khỏi phần chỉnh sửa. Lỗi thường gặp: chạy khám phá và chỉnh sửa trong cùng một phiên, để ngõ cụt và thử-sai chất đống làm nhiễm context.

Làm codebase dễ điều hướng ở quy mô lớn

Các đội triển khai thành công có một điểm chung: họ đầu tư trước để làm codebase legible — dễ đọc — với Claude, thay vì kỳ vọng model tự xoay sở. Những việc cụ thể:

• Giữ CLAUDE.md mỏng và phân lớp. Vì nó nạp ở mọi phiên bất kể tác vụ, mỗi dòng thừa là một khoản thuế đánh lên mọi lần chạy.
• Khởi tạo ở thư mục con, không phải ở gốc repo. Claude tự đi ngược lên cây thư mục và nạp mọi CLAUDE.md trên đường, nên context gốc không bao giờ mất — còn quy ước cục bộ thì ở đúng chỗ của nó.
• Scope lệnh test và lint theo thư mục con. Chạy nguyên bộ test của cả repo cho một thay đổi nhỏ gây timeout và nhét đầy context bằng output không liên quan. Khai báo lệnh áp riêng cho từng phần.
• Dùng .claudeignore (quản lý qua .claude/settings.json) để loại file sinh tự động, build artifact và code bên thứ ba.
• Viết bản đồ codebase bằng markdown khi cấu trúc thư mục không tự nói lên tổ chức.
• Triển khai LSP cho các ngôn ngữ có kiểu, để tìm theo ký hiệu thay vì khớp chuỗi.

Cấu hình cũng cần bảo trì

Một mẫu hình lặp lại ở các đội duy trì hiệu quả lâu dài: rà lại CLAUDE.md mỗi 3–6 tháng. Model tiến hóa, và những luật viết cho model cũ có thể trở thành xiềng cho model mới.

Ví dụ điển hình: một quy tắc "chia mọi refactor thành các thay đổi một-file-một-lần" — hợp lý cho model thế hệ trước — về sau lại chặn những chỉnh sửa xuyên file mà model mới làm tốt hơn. Tương tự, một skill dựng ra chỉ để bù cho một điểm yếu cụ thể của model sẽ thành gánh nặng khi điểm yếu đó được khắc phục. Cấu hình AI nên được đối xử như code: review định kỳ, và xóa thứ đã hết tác dụng.

Ai sở hữu nó: từ DRI đến "agent manager"

Ở quy mô tổ chức, nút thắt thường không phải kỹ thuật mà là quyền sở hữu. Các công ty triển khai tốt thường có một đội nhỏ — đôi khi đúng một người — đứng ra nối tooling, dựng plugin và viết quy ước CLAUDE.md chung trước khi mở rộng. Nhờ vậy, trải nghiệm đầu tiên của lập trình viên là một thứ chạy được ngay, và việc dùng lan ra tự nhiên.

Phiên bản tối giản là một DRI (Directly Responsible Individual): một người sở hữu cấu hình Claude Code, chính sách quyền hạn, marketplace plugin và quy ước CLAUDE.md, đồng thời có trách nhiệm giữ mọi thứ luôn cập nhật. Một số tổ chức đã hình thức hóa thành vai trò mới — agent manager, nửa PM nửa engineer — thường trực thuộc Developer Experience hoặc Developer Productivity.

Bắt đầu từ đâu

Một lộ trình theo từng giai đoạn, đi từ nền tảng tới năng lực nâng cao:

1. Nền tảng. Viết CLAUDE.md mỏng, phân lớp; khởi tạo ở các thư mục con. Scope lệnh test/lint. Thêm .claudeignore cho file sinh ra và code bên thứ ba.
2. Điều hướng. Bật LSP cho các ngôn ngữ có kiểu. Viết bản đồ codebase ở nơi cấu trúc thư mục không tự rõ.
3. Tự động hóa và chia sẻ. Thêm hook cho lint/format. Tách chuyên môn thành skill. Đóng gói thành plugin và phân phối qua marketplace.
4. Kết nối. Thêm MCP server tới doc, ticket, analytics — sau khi những lớp trên đã chạy.
5. Quản trị. Lập nhóm liên chức năng (engineering, infosec, governance) để định nghĩa skill/plugin được duyệt, quy trình review, giới hạn quyền truy cập ban đầu rồi mở rộng dần khi đủ tự tin. Chỉ định một DRI.

Phạm vi và giới hạn

Những thực hành trên giả định một môi trường kỹ thuật phần mềm khá quy ước: engineer là người đóng góp chính, dùng Git, cấu trúc thư mục tiêu chuẩn. Một số bối cảnh cần thêm việc: game engine với khối tài sản nhị phân lớn, hệ thống version control không quy ước, codebase có hàng trăm nghìn thư mục và hàng triệu file, hoặc nơi người không phải engineer cũng đóng góp.

Điểm đáng lưu ý cuối: phần lớn công sức ở đây không phải "tối ưu cho máy". Làm codebase dễ đọc với một agent gần như trùng khít với làm nó dễ đọc cho một người mới vào team. Ngay cả khi bỏ AI ra khỏi phương trình, một CLAUDE.md mỏng, lệnh test scope đúng chỗ và một bản đồ kiến trúc rõ ràng vẫn là khoản đầu tư có lãi.