Routine GitHub-Event: Công cụ đánh giá PR

Vì sao giá trị nằm ở các sự kiện GitHub?

Các routine theo lịch trình là một khởi đầu tuyệt vời, nhưng chúng có một hạn chế lớn: Chúng chỉ chạy đúng giờ, chứ không phải theo nhu cầu. Hầu hết những gì bạn thực sự muốn AI thực hiện - xem xét code, phân loại vấn đề, kiểm tra tài liệu - đều mang tính phản ứng, chứ không phải định kỳ.

Đó là nơi mà các GitHub event trigger (trình kích hoạt sự kiện GitHub) phát huy tác dụng. Bạn thiết lập routine của mình để chạy khi một sự kiện cụ thể xảy ra: Một PR được mở, một vấn đề được gắn nhãn, một commit được đưa vào một đường dẫn cụ thể. Routine sẽ thức dậy, thực hiện công việc của nó, rồi quay lại trạng thái Sleep cho đến khi sự kiện tiếp theo xảy ra.

Trong bài học này, chúng ta sẽ xây dựng một routine phổ biến nhất: Công cụ đánh giá PR (PR reviewer).

Cấu trúc của trigger

Khi chọn GitHub event làm trigger, bạn sẽ thấy:

• Repository - kho lưu trữ mà bạn muốn routine theo dõi
• Event category - Pull request, Issue, Push, Workflow run, Release, v.v...
• Action - các hành động cụ thể trong danh mục đó (đã mở, đã đồng bộ, đã đóng, đã gắn nhãn…)
• Filters - nhánh cơ sở, nhãn, đường dẫn, tác giả

Phần bộ lọc là phần bạn nên dành nhiều thời gian nhất. Đó là sự khác biệt giữa một routine hữu ích và một thảm họa tiêu tốn tài nguyên.

Cạm bẫy của việc bỏ qua bộ lọc

Đây là những gì xảy ra nếu bạn bỏ qua phần bộ lọc:

1. Bạn đặt trigger là "Pull request → đã mở"
2. Bạn lưu routine
3. Kho lưu trữ của bạn nhận được một pull request từ dependabot, một công việc vặt: PR từ đồng đội, một PR nháp từ nhà thiết kế, một PR hoàn tác từ bản phát hành và hai PR chỉ dành cho tài liệu trong giờ tiếp theo
4. Routine của bạn được thực thi 6 lần
5. Bạn đang sử dụng phiên bản Pro, vì vậy giới hạn hàng ngày của bạn là 5
6. Bạn đã sử dụng hết giới hạn trước giờ ăn trưa
7. PR thực sự mà bạn muốn được xem xét lúc 2 giờ chiều vẫn nằm đó

Đây là lỗi phổ biến nhất trong tuần đầu tiên, được trích dẫn trực tiếp từ tài liệu của Anthropic và các báo cáo cộng đồng. Và nó hoàn toàn có thể phòng tránh được.

Nguyên tắc lọc

Đối với routine đánh giá PR, hãy thiết lập các bộ lọc sau:

Trong số đó, thao tác thêm nhánh cơ sở + nhãn giúp loại bỏ 80% nhiễu chỉ với hai cú nhấp chuột. Nếu bạn không làm gì khác, hãy làm hai thao tác đó.

Prompt đánh giá PR

Đây là một prompt đánh giá PR cấp độ sản xuất. Nó dài hơn so với việc phân loại công việc tồn đọng từ bài học 2 vì xem xét PR là một việc lớn hơn - nhưng nó vẫn tuân theo 4 quy tắc từ bài học 2 (truy vấn phạm vi, định dạng cố định, giới hạn cứng, xử lý trạng thái rỗng).

Bạn là một kỹ sư cấp cao đang thực hiện đánh giá code kỹ lưỡng trên một pull request.

Bạn sẽ nhận được sự khác biệt của PR, tiêu đề, mô tả và các vấn đề được liên kết
làm đầu vào. Nhiệm vụ của bạn là đăng một bình luận đánh giá duy nhất với những phát hiện của bạn.

Ưu tiên đánh giá (theo thứ tự):

1. Tính chính xác - code có thực hiện đúng những gì mô tả PR nói không?
2. Bảo mật - bỏ qua xác thực, tấn công SQL injection, XSS, lộ bí mật, giải mã không an toàn
3. Hiệu suất - truy vấn N+1, vòng lặp không giới hạn, các vấn đề hot-path rõ ràng
4. Độ phủ test - các đường dẫn đã thay đổi đã được test chưa? Có nhánh nào chưa được kiểm tra không?
5. Phong cách - chỉ báo cáo các vấn đề về phong cách gây cản trở việc hiểu, không bao giờ soi mói chi tiết

Định dạng đầu ra đánh giá (sử dụng chính xác template này):

## Tóm tắt đánh giá

**Kết luận:** {chấp thuận | yêu cầu thay đổi | nhận xét}

### PR này làm gì
{1-2 câu}

### Phát hiện

{Đối với mỗi phát hiện, hãy sử dụng:}
- **[severity]** `{file}:{line}` — {vấn đề một dòng}
- Tại sao nó quan trọng: {một câu}
- Đề xuất sửa lỗi: {một câu}

Mức độ nghiêm trọng: nghiêm trọng | đáng lo ngại | soi mói

### Test
{Một câu về việc các đường dẫn đã thay đổi có độ bao phủ đầy đủ hay không.}

---

Quy tắc:
- Không bao giờ viết quá 10 phát hiện. Nếu có hơn 10, hãy chọn
10 phát hiện hàng đầu theo mức độ nghiêm trọng và ghi chú rằng còn có những phát hiện khác.
- Không bao giờ đăng các đánh giá chung chung "LGTM". Chỉ đánh giá nếu có phát hiện.
- Nếu PR quá lớn để xem xét một cách có ý nghĩa (>500 dòng thay đổi),
hãy nói rõ điều đó và yêu cầu chia nhỏ.
- Không bao giờ yêu cầu thay đổi chỉ về kiểu dáng.
- Không bao giờ đẩy lên bất kỳ nhánh nào. Chỉ đăng bình luận đánh giá.

Một vài điều cần lưu ý:

• Ưu tiên rõ ràng - prompt cho Claude biết cần tìm kiếm điều gì, theo thứ tự
• Định dạng đánh giá cố định - cùng một template mỗi lần
• Giới hạn cứng về số lượng phát hiện (tối đa 10)
• Quy tắc "không đẩy" rõ ràng - mặc dù nền tảng thực thi quy tắc này, việc nhắc lại trong prompt sẽ ngăn Claude thử
• Giới hạn kích thước rõ ràng - yêu cầu Claude dừng lại nếu PR quá lớn

Mô hình "một phiên cho mỗi PR"

Đây là một chi tiết từ tài liệu mà bạn dễ bỏ sót. Khi một PR trải qua vòng đời của nó - được mở, các commit mới được đẩy lên, bình luận được thêm vào, kết quả CI đến - tất cả đều là các sự kiện GitHub riêng biệt. Nếu bạn cấu hình mỗi sự kiện như một lần chạy routine riêng biệt, bạn sẽ vượt quá hạn mức của mình trước giờ ăn trưa với một PR bận rộn.

Thay vào đó, tài liệu của Anthropic mô tả một mô hình như sau:

Claude mở một phiên cho mỗi PR, liên tục cập nhật (bình luận, kết quả CI) vào phiên đó để theo dõi.

Một phiên. Nhiều cập nhật vào cùng một phiên. Claude ghi nhớ ngữ cảnh PR giữa các sự kiện. Hạn mức của bạn chỉ tính một lần chạy routine, chứ không phải 10 lần.

Để có được hành vi này, hãy cấu hình routine với tùy chọn "cùng một phiên giữa các sự kiện" (nhãn giao diện người dùng chính xác có thể khác nhau - hãy tìm tùy chọn này trong tùy chọn nâng cao của trình kích hoạt GitHub). Nếu không có tùy chọn này, mỗi lần đẩy sẽ kích hoạt một đánh giá mới mà không ghi nhớ phản hồi trước đó.

Hạn chế đẩy nhánh

Một quy tắc bạn không thể ghi đè: Các routine không thể đẩy lên những nhánh được bảo vệ.

Điều này áp dụng cho main, master, bất kỳ nhánh nào bạn đã đánh dấu là được bảo vệ trên GitHub và bất kỳ nhánh nào yêu cầu người đánh giá. Routine có thể:

• Đăng bình luận về pull request (PR)
• Đăng bình luận đánh giá (phê duyệt / yêu cầu thay đổi)
• Đẩy lên nhánh tính năng
• Mở PR mới
• Gắn nhãn, chỉ định, đóng vấn đề

Routine không thể:

• Đẩy trực tiếp lên nhánh chính
• Bỏ qua công cụ đánh giá bắt buộc
• Ép đẩy lên các nhánh được bảo vệ
• Xóa các nhánh không phải của nó

Đây không phải là lỗi. Đây là sự đảm bảo an toàn cơ bản. Nếu bạn muốn Claude đề xuất thay đổi cho nhánh chính, nó phải thông qua một PR mà con người phê duyệt. Đó là tính năng, không phải là hạn chế.

Cấu hình Plug-and-Play: Từng bước một

Danh sách kiểm tra thiết lập cụ thể:

1. Routines → New routine
2. Trigger: Sự kiện GitHub
3. Repository: Chọn kho lưu trữ của bạn (bạn sẽ cần ủy quyền cho GitHub connector một lần)
4. Event category: pull request
5. Action: đã mở + đã đồng bộ (đã đồng bộ = các commit mới được đẩy lên)
6. Base branch filter: main
7. Label filter: needs-review (tùy chọn, nhưng được khuyến nghị)
8. Paths: đường dẫn code của bạn (ví dụ: src/** , lib/**) - bỏ qua docs/** , *.md, lockfile
9. Author exclude: dependabot[bot], renovate[bot]
10. Connectors: Chỉ GitHub
11. Session behavior: cùng một phiên cho mỗi PR
12. Prompt: prompt ở trên
13. Save → mở một PR thử nghiệm → xác minh xem nó có hoạt động không

Mở một PR thử nghiệm để xác nhận các bộ lọc hoạt động. Nếu routine hoạt động khi bạn không muốn, bộ lọc của bạn quá lỏng lẻo. Hãy siết chặt nó lại.

Điểm khác biệt giữa GitHub Triggers và lập lịch

Một bảng so sánh nhanh để làm rõ sự khác biệt:

Nếu công việc của bạn mang tính định kỳ → lập lịch. Nếu công việc của bạn mang tính phản hồi → GitHub Event.

Những điểm chính cần ghi nhớ

• Các GitHub trigger được kích hoạt khi xảy ra các sự kiện - PR, commit, issue, workflow runs
• Luôn thiết lập nhánh cơ sở + bộ lọc nhãn - chúng giúp ngăn chặn việc vượt quá hạn mức
• Sử dụng mô hình một phiên cho mỗi PR để duy trì ngữ cảnh giữa các bản cập nhật
• Các routine không thể đẩy lên những nhánh được bảo vệ, và đó là một tính năng
• Bộ lọc loại trừ phụ thuộc rõ ràng giúp giảm thiểu tối đa sự phức tạp