Một pull request xuất hiện trong hàng đợi của bạn với 340 dòng thay đổi trải trên chín file. Một coding agent viết nó. Diff không cho bạn biết agent được yêu cầu làm gì, đã thử rồi bỏ những hướng nào, đã chạy gì để tự thuyết phục rằng thay đổi này hoạt động, hay chỗ nào nó biết mình đã làm ẩu. Thế là bạn chỉ có hai lựa chọn: đọc lướt rồi approve, hoặc dựng lại toàn bộ thay đổi từ đầu. Cách thứ nhất là con đường để code tồi lọt ra ngoài. Cách thứ hai nghĩa là agent chẳng giúp bạn tiết kiệm được gì.
Review code do AI tạo ra là một công việc khác với review PR của đồng nghiệp, bởi tác giả không thể ngồi cạnh bạn để giải thích lý do của họ. Cách khắc phục là review diff cùng với bằng chứng đi kèm: mục tiêu, các kiểm tra đã chạy, và những giới hạn mà agent đã tự nêu ra. Đó chính là nền tảng mà Sharkly được xây dựng quanh. Sharkly nằm phía trên các coding agent của bạn (Claude Code, Codex, Gemini và những công cụ khác) và lưu giữ mục tiêu, thay đổi, kết quả kiểm chứng, cùng phần review của con người cho mỗi lần chạy trong một Task duy nhất, thay vì rải rác khắp terminal và mô tả PR.
Hướng dẫn này sẽ đi qua mô hình vận hành đằng sau đó: ai giao việc, ai chạy, ai review, ai nghiệm thu, các trạng thái và cổng kiểm soát phân tách phần việc của agent với phần việc của con người, và một ví dụ thực tế từ ticket đến PR đã merge.
Câu trả lời nhanh
Hãy review code do AI tạo ra ở cấp Task, không phải ở cấp diff. Yêu cầu agent đính kèm bản tóm tắt thay đổi, kết quả typecheck/test/build mà nó đã chạy, và mọi giới hạn đã biết vào một Task chung, rồi chuyển Task đó sang trạng thái review. Con người đọc bằng chứng song song với diff, yêu cầu chỉnh sửa hoặc chấp nhận, và đưa ra quyết định merge. Agent tạo ra và kiểm chứng; con người nghiệm thu.
Vì sao chỉ review mỗi diff là thất bại
Đọc code khó hơn viết code. Một thực tế đã được ghi nhận rõ ràng trong code review là người review nắm ít bối cảnh hơn tác giả, và khi tác giả là một agent thì khoảng cách đó là tuyệt đối. Một diff trên GitHub chỉ cho bạn thấy đích đến, chứ không bao giờ cho thấy lộ trình. Bạn không thể thấy rằng agent đã thử một lớp caching trước, gặp race condition, rồi gỡ nó ra. Bạn không thể thấy rằng nó đã chạy bộ test và một test flaky thất bại không liên quan đến thay đổi.
Không có bối cảnh đó, review sẽ sụp đổ thành hai kiểu thất bại. Phê duyệt qua loa (rubber-stamping) là chấp nhận những đoạn code trông có vẻ hợp lý nhưng âm thầm phá vỡ một edge case mà agent chưa từng nghĩ tới. Còn dựng lại toàn bộ thì buộc bạn tự tái tạo lý luận, và đến lúc đó lợi thế tốc độ của agent đã biến mất. Cả hai đều không mở rộng được khi ba agent cùng lúc mở PR. Lối thoát là làm cho công việc của agent có thể review được, chứ không chỉ output của nó.
Bằng chứng ở cấp Task thực sự có nghĩa là gì
Bằng chứng ở cấp Task là bản ghi mà Agent đính kèm vào Task của nó: mục tiêu nó dựa vào, thay đổi nó tạo ra, các kiểm tra nó đã chạy, và những giới hạn mà nó biết. Thay vì một diff trần trụi, bạn nhận được một diff kèm theo dấu vết nguồn gốc.
Trên thực tế, gói bằng chứng gồm bốn thứ:
- Mục tiêu và tiêu chí nghiệm thu, nằm trong mô tả Task, để việc review được đo đối chiếu với điều đã yêu cầu chứ không phải điều trông có vẻ hợp lý.
- Bản tóm tắt thay đổi, bằng chính lời của agent: nó đã chạm vào những gì và vì sao.
- Kết quả kiểm chứng: output của typecheck, test và build mà agent đã chạy trước khi bàn giao.
- Các giới hạn đã biết: những edge case, giả định và việc cần làm tiếp mà agent đã nêu ra thay vì giấu đi.
Tất cả đều quay về Task. Quá trình thực thi, các điểm tắc, kết quả và thảo luận tiếp theo nằm trên một dòng thời gian duy nhất, nên người review chỉ mở một bản ghi thay vì phải ghép lại từ một PR, một luồng Slack và một prompt nhớ mang máng. Đây chính là kỷ luật đằng sau một quy trình từ yêu cầu đến code có thể truy vết: bằng chứng là một phần của sản phẩm bàn giao.
Mô hình vận hành: ai giao việc, ai chạy, ai review, ai nghiệm thu
Review tốt phụ thuộc vào vai trò rõ ràng. Giao kèo rất ngắn: agent nghiên cứu, thực thi, kiểm thử và báo cáo; con người định hướng, trao quyền và nghiệm thu kết quả. Tự động hóa dừng lại ở đúng chỗ cần đến phán đoán của con người.
| Vai trò | Ai | Việc đảm nhiệm |
|---|---|---|
| Người giao việc | Một người (thường là Task Owner) | Mô tả nhu cầu, đặt tiêu chí nghiệm thu, giao Task |
| Bên thực thi | Một Agent, trên một Computer đã kết nối, thông qua một Runtime | Nhận Task, thực thi trong một worktree tách biệt, đính kèm bằng chứng |
| Người review | Một người | Đọc diff đối chiếu với bằng chứng, yêu cầu chỉnh sửa hoặc phê duyệt |
| Người nghiệm thu | Một người (Owner hoặc người phê duyệt được chỉ định) | Đưa ra quyết định nghiệm thu và merge/release cuối cùng |
Sharkly không thay thế Claude Code, Codex hay các công cụ thực thi khác. Nó bổ sung lớp Task, Computer, bối cảnh và review dùng chung bao quanh những công cụ mà đội bạn đã dùng. Runtime viết code; Sharkly quyết định review sẽ rơi vào hàng đợi của ai và bằng chứng nào phải có trước khi con người xem xét. Nếu bạn muốn phiên bản sâu hơn về phía giao việc, hãy xem ai giao việc và ai nghiệm thu công việc của agent.
Trạng thái và cổng review: agent chuyển sang Ready for review, con người chuyển sang Done
Cổng review là một ranh giới trạng thái. Trong Sharkly, mỗi trạng thái task thuộc về một nhóm cố định mang ý nghĩa hệ thống: Backlog (tạm gác), Unstarted (sẵn sàng, chưa bắt đầu), Started (đang thực hiện) và Completed (kết thúc). Nhiều trạng thái hiển thị có thể cùng thuộc một nhóm, nên workflow của một loại task có thể chạy Development và Ready for review như hai trạng thái Started riêng biệt trước khi bất cứ thứ gì chạm tới Completed.
Chính cấu trúc đó khiến cổng review trở nên thực chất. Một Agent có thể đưa Task từ Development sang Ready for review, và có thể để Task chờ con người review. Nó không được phép tự mình chuyển Task sang trạng thái Completed. Nghiệm thu là một bước chuyển do con người thực hiện, theo đúng thiết kế.
| Trạng thái | Nhóm | Ai chuyển đến đây |
|---|---|---|
| Backlog | Backlog | Con người, khi tạm gác công việc |
| Todo | Unstarted | Con người, khi Task đã sẵn sàng |
| Development | Started | Agent, khi nó nhận và xử lý Task |
| Ready for review | Started | Agent, khi bằng chứng đã được đính kèm |
| Done | Completed | Con người, sau khi nghiệm thu |
Hãy cấu hình workflow sao cho bước chuyển vào trạng thái Completed đòi hỏi phải có con người, và bạn có một cổng review vẫn đứng vững ngay cả khi agent tạo ra kết quả nhanh hơn tốc độ bạn theo dõi. Đây là phiên bản cơ học của việc giữ con người trong vòng lặp đối với coding agent, và cũng là nơi bạn quyết định chặn agent lại ở đâu trước khi chúng merge.
Ví dụ thực tế: từ ticket đến PR đã merge
Lấy SH-312: “Thêm rate limiting cho endpoint tìm kiếm công khai, 60 request mỗi phút cho mỗi API key.”
- Một người tạo SH-312 với mục tiêu đó và hai tiêu chí nghiệm thu: các request vượt giới hạn trả về HTTP 429, và giới hạn tính theo key chứ không theo IP. Task bắt đầu ở trạng thái Todo.
- Một Agent nhận Task, chuyển nó sang Development và chạy trong một worktree tách biệt để bản checkout của nó không bao giờ đụng độ với các agent khác đang làm việc trên cùng repo. (Worktree chính là lý do các lần chạy song song vẫn sạch sẽ; xem một checkout cho mỗi task.)
- Agent triển khai một token-bucket limiter, mở một PR và đính kèm bằng chứng vào SH-312: bản tóm tắt thay đổi, kết quả typecheck và unit test đều pass, kết quả build, và một giới hạn đã biết: “Bucket nằm trong bộ nhớ tiến trình, nên giới hạn sẽ reset mỗi lần deploy và không được chia sẻ giữa các instance.”
- Agent chuyển SH-312 sang Ready for review. Nó rơi vào hàng đợi của con người với diff và bằng chứng đi cùng nhau.
- Người review đọc ghi chú về giới hạn đã biết trước tiên, quyết định rằng bucket trong bộ nhớ là ổn trong thời điểm hiện tại, và yêu cầu một thay đổi: trả về header
Retry-Afterkhi gặp 429. Agent thực hiện thay đổi và đính kèm lại output test đã cập nhật. - Người review nghiệm thu, merge PR và chuyển SH-312 sang Done, với một ticket tiếp theo cho limiter dùng chung đã được liên kết sẵn.
Buổi review chỉ mất vài phút vì người review không hề phải dựng lại thay đổi; chính bằng chứng đã làm việc đó. Đây cũng là vòng lặp tương tự như quản lý dự án Claude Code từ issue đến review, với gói bằng chứng giúp review nhanh chóng thay vì trở thành nút thắt cổ chai.
Cách review bằng chứng nhanh, và khi nào nên làm nhẹ
Không phải thay đổi nào cũng cần xử lý đầy đủ. Hãy dùng một quy tắc quyết định.
Hãy làm kỹ khi thay đổi chạm đến auth, billing, migration dữ liệu, API công khai, hoặc bất cứ thứ gì khó rollback: đọc diff từng dòng, tự chạy lại test, và đối chiếu ghi chú giới hạn đã biết với các edge case của chính bạn. Hãy làm nhẹ khi thay đổi chỉ là sửa nội dung, một refactor nội bộ đã được test kỹ, hay một lần nâng cấp dependency với các check đều xanh: đọc bản tóm tắt, lướt qua diff, xác nhận kiểm chứng đã pass, rồi nghiệm thu.
Danh sách kiểm tra nhanh cho review kỹ:
- Diff có thỏa mãn mọi tiêu chí nghiệm thu, chứ không chỉ luồng thuận lợi (happy path) không?
- Agent có thực sự chạy các kiểm tra, hay chỉ nói là đã chạy? Hãy xác minh output được đính kèm.
- Đọc ghi chú giới hạn đã biết. Có giới hạn nào là vấn đề chặn (blocker) chứ không chỉ là việc cần làm tiếp không?
- Thay đổi có nằm trong phạm vi yêu cầu không, hay agent đã chạm vào những file không liên quan?
Nếu bạn đang vận hành nhiều coding agent cùng lúc, đây là quy trình mà Sharkly cho bạn một nơi để quản lý: giao Task, để agent đính kèm bằng chứng, review tại cổng. Bạn có thể tự ghép các mảnh này bằng tay với worktree, template PR và một bảng trạng thái, hoặc Tải Sharkly và có được Task, bằng chứng và cổng review như một hệ thống thống nhất.
Câu hỏi thường gặp
Bằng chứng ở cấp Task cho code do AI tạo ra là gì? Đó là bản ghi mà agent đính kèm vào Task của nó cùng với diff: mục tiêu, bản tóm tắt thay đổi, kết quả typecheck/test/build mà nó đã chạy, và mọi giới hạn đã biết. Review gói thông tin đó vừa nhanh hơn vừa an toàn hơn so với chỉ review mỗi diff.
Một AI agent có thể tự phê duyệt code của chính nó không? Không, và đó chính là mục đích của cổng review. Một agent có thể chuyển Task sang Ready for review, nhưng bước chuyển sang trạng thái Completed là quyết định của con người. Agent tạo ra và kiểm chứng; con người nghiệm thu.
Làm sao để review code AI nhanh hơn mà không phê duyệt qua loa? Hãy cân đối công sức theo mức độ rủi ro. Luôn đọc bằng chứng cho mọi thay đổi, nhưng dành việc review từng dòng và chạy lại test cho những khu vực rủi ro cao như auth và migration. Xem cách năng lực review mở rộng khi agent vượt xa con người.
Tôi có còn dùng pull request không? Có. Agent mở pull request trên GitHub thật; lớp Task bổ sung bằng chứng và cổng review bao quanh chúng để PR không còn là nơi duy nhất lưu giữ bối cảnh.
