Khám phá codebase với agent

Trước khi sửa một dự án lạ, bạn cần biết hành vi nằm ở đâu và kiểm chứng nó thế nào. Bài này hướng dẫn dùng agent để tìm hiểu một hành vi trong repo mà không chỉnh sửa gì, và kết thúc bằng bản đồ code liên quan, các tham chiếu tới source và danh sách câu hỏi còn mở.

Agent giúp tìm entry point, lần theo lời gọi giữa các file và tìm test liên quan. Hãy coi lời giải thích của nó là điểm xuất phát để đối chiếu với code, không phải mô tả chính thức của dự án.

Chuẩn bị

• Thiết lập GitHub Copilot.
• Mở repo cần khám phá trong VS Code.
• Chọn một câu hỏi về dự án, ví dụ một yêu cầu (request) được phân quyền thế nào, form lưu dữ liệu ra sao, hay phản hồi (response) của API được ghép ở đâu.

Đọc hướng dẫn bảo mật khi làm việc với agent trước khi tin tưởng hoặc chạy code lạ. Bạn không cần cài dependency hay chạy ứng dụng mới đọc được source.

1. Xác định câu hỏi

Hỏi về một hành vi cụ thể thay vì nhờ agent giải thích cả repo. Câu hỏi có phạm vi rõ giúp bạn dễ kiểm tra lời giải thích đã đủ chưa.

1. Mở Chat view và bắt đầu chat mới.
2. Chọn session target Copilot và vai trò Agent, giữ Manual permissions.
3. Mô tả hành vi muốn hiểu, kèm entry point nếu biết (route, lệnh, phần tử UI).

Ví dụ prompt, bạn chỉnh theo endpoint trong dự án của mình:

Explain how a request to GET /issues becomes a paginated response in
this repository. Start with the route registration and follow the
implementation to the returned response.

Do not edit files, install dependencies, start services, or run project
code. Cite the files and symbols that support your explanation.
Separate facts you verified from assumptions and open questions.

2. Tìm code liên quan

Nhờ agent lập một bản đồ nhỏ gồm entry point, module hiện thực (implement), cấu hình và test liên quan, giải thích vai trò từng file, không tóm tắt thư mục không liên quan và không đọc giá trị bí mật.

Mở các file được nhắc tới trong lúc đọc câu trả lời và kiểm tra:

• Route (hoặc entry point khác) thực sự được đăng ký trong ứng dụng đang tìm hiểu.
• Các hàm được trích dẫn có tồn tại trong bản checkout hiện tại.
• Phần hiện thực là code đang chạy, không phải ví dụ bỏ đi, bản sinh tự động hay test fixture.
• Mọi nhận định về cấu hình chỉ ra nguồn cấu hình mà không lộ credential.

Nếu repo có nhiều ứng dụng hoặc nhiều bản hiện thực, nói rõ bạn muốn cái nào. Thêm các file liên quan làm ngữ cảnh (context) cho chat thay vì bắt agent tìm lại cả repo.

3. Lần theo một đường đi

Chọn một input cụ thể và theo nó từ entry point tới kết quả, ví dụ GET /issues?page=2: tham số được parse và kiểm tra ở đâu, bản ghi được chọn thế nào, phản hồi được tạo ra sao. Yêu cầu agent trích symbol cho từng bước, nêu input/output, đường lỗi, ranh giới database hoặc dịch vụ ngoài, và nói rõ phần nào không kiểm chứng được.

Hãy kiểm tra cả các mối nối, không chỉ từng hàm: caller có truyền đúng giá trị như mô tả không, giá trị trả về có tới được phản hồi không, xử lý lỗi có đi đúng đường agent nói không. Khi lời giải thích bỏ qua một bước, hỏi tiếp có trọng tâm:

You identified the pagination helper, but have not shown how the route
calls it. Find that call site and verify which default page value it
receives. If you cannot find a connection, revise the explanation.

4. Đối chiếu với test

Test cho thấy hành vi mong muốn và lộ ra những trường hợp mà bản tóm tắt bỏ sót. Nhờ agent tìm test cho đường đi vừa lần, liệt kê input và kết quả mong đợi kèm tham chiếu, chỉ ra trường hợp biên chưa được cover, và không được nói test pass nếu chưa chạy trong môi trường này.

So sánh assertion với lời giải thích và tài liệu dự án. Tên test không phải bằng chứng rằng test kiểm tra đúng hành vi đó.

Nếu cần xác nhận lúc chạy, trước hết xem hướng dẫn setup và lệnh test được đề xuất. Chỉ chạy code từ repo bạn tin tưởng. Ghi lại kết quả thật và giới hạn môi trường; dịch vụ không truy cập được hay test chưa chạy không được tính là đã pass.

5. Ghi lại những gì đã kiểm chứng

Nhờ agent tóm tắt ngắn: entry point, đường đi hiện thực, test và lệnh liên quan, câu hỏi chưa giải quyết, mỗi nhận định quan trọng gắn với nguồn, phân biệt test đã đọc với test đã chạy, và không tạo hay sửa file.

Tự đọc lại bản tóm tắt. Bạn cần định vị được phần hiện thực, giải thích được một đường thành công và một đường lỗi hoặc biên, và biết sẽ kiểm chứng thay đổi thế nào. Nếu còn mối nối quan trọng chưa chắc, hãy hỏi maintainer hoặc tìm hiểu thêm trước khi sửa.

Giữ bản tóm tắt đã kiểm chứng cùng tác vụ. Chỉ đưa kiến thức ổn định vào tài liệu chung sau khi đã review, thay vì lưu mô tả kiến trúc do agent sinh ra mà chưa ai kiểm tra.

Bước tiếp theo

• Thêm tính năng vào dự án có sẵn.
• Refactor mà không đổi hành vi.

Nguồn

• Tóm tắt từ https://raw.githubusercontent.com/microsoft/vscode-docs/main/docs/agents/guides/explore-a-codebase.md, giấy phép CC-BY-3.0-US.