0

Đọc codebase lạ cùng AI: từ chưa biết bắt đầu đâu tới sửa được bug đầu tiên

Ngày đầu nhận một project cũ: vài trăm file, README đúng năm dòng, người viết chính đã nghỉ. Ticket đầu tiên: "khách đổi địa chỉ giao hàng, nhưng email xác nhận vẫn gửi địa chỉ cũ". Mình mở thư mục src, nhìn mấy chục folder, và không biết nên mở file nào trước.

Trước đây việc này thường là vài ngày đọc lan man, mở file này nhảy sang file kia. Giờ có AI, nó nhanh hơn hẳn, nhưng chỉ khi hỏi đúng cách. Lần đầu mình hỏi sai, và câu trả lời dài cả trang mà chẳng giúp sửa được gì. Bài này là cách mình làm lại, từng bước, kèm mẫu prompt dùng ngay.

Sai lầm đầu tiên: bảo AI "giải thích cả project"

Câu đầu tiên mình gõ là "giải thích project này cho mình". AI trả về một bài tóm tắt rất gọn gàng: ứng dụng ASP.NET Core, kiến trúc nhiều lớp, có Controllers, Services, Repositories... Đúng hết, và gần như vô dụng. Mình vẫn không biết bug nằm ở đâu.

Tệ hơn, vài chỗ trong bản tóm tắt là AI đoán từ tên thư mục chứ chưa mở file ra đọc (đúng kiểu bịa mà bài 2 của series đã nói). Thư mục tên Notifications chưa chắc đã chứa code gửi email.

Vấn đề không nằm ở AI. Một câu hỏi rộng như cả project thì chỉ nhận lại được câu trả lời chung chung.

Bước 1: bản đồ trước, chi tiết sau

Thứ mình cần đầu tiên không phải là hiểu hết, mà là biết cách chạy và biết đường đi:

Đọc project này và cho mình:
- Lệnh build, lệnh chạy, lệnh chạy test (đọc từ file cấu hình thật, không đoán)
- Điểm vào của ứng dụng (Program.cs, nơi đăng ký route, job chạy nền)
- Các thư mục chính, mỗi thư mục một dòng mô tả
Đánh dấu [Đã kiểm] cho thứ bạn đọc trực tiếp, [Suy luận] cho thứ bạn đoán.

Xong bước này, việc đầu tiên mình làm là tự chạy thử lệnh build và test AI đưa ra. Chạy được nghĩa là bản đồ đúng ít nhất ở chỗ quan trọng nhất. Chạy không được thì biết ngay phải hỏi lại chỗ nào.

Bước 2: lần theo một luồng, đừng đọc cả kho

Thay vì hiểu cả project, mình hỏi đúng luồng liên quan tới bug:

Lần theo luồng: khách bấm "Đổi địa chỉ" trên trang đơn hàng.
Request đi qua những hàm nào, theo thứ tự, tới lúc email xác nhận được gửi?
Mỗi bước ghi rõ file và tên hàm. Chỗ nào không chắc thì nói không chắc.

Kết quả trông như thế này:

PUT /orders/{id}/address
 → OrdersController.UpdateAddress       Controllers/OrdersController.cs
 → OrderService.ChangeAddressAsync      Services/OrderService.cs
 → phát sự kiện OrderAddressChanged     Domain/Events/OrderAddressChanged.cs
 → SendConfirmationEmailHandler         Handlers/SendConfirmationEmailHandler.cs
      địa chỉ trong email lấy từ order.ShippingAddressSnapshot

Bốn file, thay vì vài trăm. Mình mở từng file kiểm lại, và dòng cuối là chỗ đáng ngờ: email lấy địa chỉ từ ShippingAddressSnapshot, một bản chụp địa chỉ lưu lúc tạo đơn, chứ không phải địa chỉ hiện tại.

Bước 3: hỏi "vì sao", trước khi sửa

Cách sửa nhanh nhất là đổi handler sang đọc địa chỉ hiện tại. Nhưng code lạ thường có lý do ẩn: ai đó tạo ra cái snapshot kia là có ý. Mình hỏi tiếp:

ShippingAddressSnapshot được tạo ra để làm gì? Tìm mọi chỗ đọc và ghi trường này,
và xem git log của các file đó, commit nào nhắc tới snapshot.

Câu trả lời: snapshot được thêm vào để hoá đơn giữ đúng địa chỉ tại thời điểm đặt hàng, vì lý do kế toán. Handler gửi email chỉ dùng nhầm trường đó. Nếu mình sửa thẳng snapshot cho khớp địa chỉ mới, bug email hết, nhưng hoá đơn của các đơn cũ sẽ sai.

Bản sửa đúng: email xác nhận dùng địa chỉ hiện tại, hoá đơn giữ snapshot. Kèm một test cho đúng tình huống "đổi địa chỉ sau khi đặt" (cách viết test đỏ trước, xanh sau ở bài 7).

Bước 4: ghi lại những gì vừa hiểu

Hiểu được luồng này mất công, đừng để nó chỉ nằm trong lịch sử chat. Mình bảo AI ghi vào file hướng dẫn của project (CLAUDE.md hoặc AGENTS.md, như bài 3 đã nói):

## Lệnh
- Build: dotnet build | Test: dotnet test (cần Docker cho database test)

## Bẫy đã gặp
- Order.ShippingAddressSnapshot là địa chỉ lúc đặt hàng, chỉ dùng cho hoá đơn.
  Thứ gì cần địa chỉ hiện tại thì đọc Order.ShippingAddress.

Người tiếp theo nhận project, hay chính AI ở phiên sau, sẽ không phải lần lại từ đầu.

Hỏi AI về code lạ: nên và không nên

Nên hỏi Thay vì
"Lần theo luồng X từ request tới database" "Giải thích cả project"
"Hàm này được gọi ở những đâu, liệt kê đủ" (rồi tự kiểm bằng Find Usages của IDE) "Hàm này dùng để làm gì"
"Vì sao code viết thế này, xem git log" "Code này có sai không"
"Chạy lệnh test rồi báo kết quả" "Project này test bằng gì"
"Chỗ nào bạn đang đoán thì đánh dấu" Tin cả bản tóm tắt

Thử ngay: lần tới nhận một ticket ở phần code bạn chưa từng đụng, đừng hỏi AI về cả project. Hỏi đúng luồng của ticket đó theo mẫu ở bước 2, rồi mở từng file nó liệt kê để kiểm. Bạn sẽ thấy ngay chỗ nào AI đọc thật, chỗ nào nó đoán.

Bài sau: khi đã có một quy trình làm việc với AI chạy tốt, làm sao để khỏi phải dặn lại mỗi lần, bằng cách đóng gói nó thành skill. Bạn có mẹo nào để làm quen nhanh với một codebase lạ không? Comment chia sẻ với mọi người nhé.

P.S. Bước 1 và bước 2 mình giao cho skill explore trong PrimeKit, bộ skill mình tự làm. Skill tìm điểm vào, quy ước, phụ thuộc của một codebase lạ hoặc lần theo một tính năng cụ thể trước khi sửa, và chỉ đưa ra lệnh build, test đã chạy thử được. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:explore kèm luồng bạn muốn lần theo. Nó giúp bạn tìm đúng file nhanh hơn, còn hiểu vì sao code được viết như vậy thì vẫn cần bạn hỏi và đọc.


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí