Coding Agent Human-in-the-Loop: Quy trình đánh giá

Agent lập trình human-in-the-loop thường được mô tả như một thiết lập: chế độ mà công cụ hỏi trước khi chỉnh sửa. Đó là một vòng lặp, và là vòng lặp nhỏ nhất. Nó chỉ chạy trong terminal của một lập trình viên, cho một phiên làm việc, rồi biến mất khi phiên kết thúc. Một nhóm tưởng rằng mình đang có sự giám sát của con người chỉ vì ai cũng để Claude Code ở chế độ Manual thì thực ra chỉ đang giám sát từng thao tác gõ phím, chứ không phải kết quả.

Bài hướng dẫn này trình bày quy trình review dưới dạng năm cổng kiểm soát, từ lời nhắc cấp quyền bên trong runtime cho đến quyết định nghiệm thu trên hồ sơ dùng chung, đồng thời nói rõ ai là người quyết định ở từng cổng và quyết định đó được ghi lại ở đâu. Các cổng ở cấp runtime lấy từ tài liệu chính thức của công cụ. Các cổng ở cấp nhóm dùng Sharkly, vì Sharkly ghi chúng trên Task thay vì để chúng trôi mất trong lịch sử cuộn màn hình của ai đó. Nếu bạn muốn nắm định nghĩa của phương pháp này trước, bài hướng dẫn về quản lý dự án với AI agent của chúng tôi sẽ nói về vòng lặp mà quy trình này nằm trong đó.

TL;DR

Một quy trình review human-in-the-loop cho agent lập trình có năm cổng: chế độ cấp quyền của runtime, xác nhận kế hoạch trước khi công việc trở thành Task, ranh giới thực thi quyết định thời điểm một lượt chạy được phép bắt đầu, tín hiệu cần chú ý để định tuyến việc review đến một người cụ thể, và nghiệm thu được ghi nhận bằng thay đổi trạng thái do chính người đó thực hiện. Chỉ có cổng đầu tiên là thiết lập của công cụ. Bốn cổng còn lại là quyết định của nhóm, và chúng cần một hồ sơ dùng chung thì mới thành hiện thực. 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ả.

Cổng 1: Chế độ cấp quyền bên trong runtime

Mọi agent lập trình nghiêm túc đều có sẵn một nút chỉnh mức phê duyệt. Chế độ cấp quyền của Claude Code trải từ default, được gắn nhãn Manual, chế độ hỏi trước khi chỉnh sửa, chạy lệnh shell và truy cập mạng, qua acceptEdits, plan và auto, trong đó một mô hình thứ hai gọi là bộ phân loại sẽ review hành động thay bạn, cho tới bypassPermissions chỉ dành cho các container biệt lập. Chuyển đổi bằng Shift+Tab hoặc --permission-mode. Codex thể hiện cùng ý tưởng đó qua lệnh /permissions, nơi bạn đặt thời điểm nó được phép sửa tệp hoặc chạy lệnh mà không cần hỏi.

Cổng này là cần thiết nhưng chưa đủ. Nó chỉ tồn tại theo từng phiên và từng lập trình viên, nó bảo vệ cái máy chứ không bảo vệ yêu cầu, và nó không để lại bản ghi nào để đồng đội đọc được. Trên các gói Pro, Max và Team, Claude Code hiện khởi động ở chế độ auto theo mặc định, một lựa chọn hợp lý chính vì bộ phân loại nhanh và nhất quán hơn một con người đang mệt mỏi bấm "yes" liên tục. Bài học không phải là chống lại nút chỉnh đó. Mà là đừng coi nút chỉnh đó chính là việc review.

Cổng 2: Xác nhận kế hoạch

Cổng đầu tiên ở cấp nhóm diễn ra trước khi có bất kỳ dòng code nào. Trong Agent chat của Sharkly, chế độ Plan cho phép Agent đề xuất các hành động để bạn review, và Task cùng các sub-task dự kiến chỉ được tạo sau khi có người xác nhận đề xuất đó. Bạn có thể xác nhận mà không khởi chạy, hoặc xác nhận và khởi chạy luôn.

Đây là nơi phạm vi công việc được chốt, và cái giá phải trả rất rẻ: sửa một sub-task được đề xuất chỉ tốn một phút, còn review một đợt refactor không ai yêu cầu thì tốn cả buổi chiều. Hãy giữ lựa chọn Explore khi bạn chỉ muốn phân tích. Dùng Crew khi cần một leader diễn giải mục tiêu và huy động các Agent thành viên khác; dùng một Agent đơn lẻ và bỏ qua phần nghi thức đó khi chỉ một vai trò là đủ đảm nhiệm công việc. Bài hướng dẫn chat với AI agent hoặc giao một Task của chúng tôi nói rõ về ba chế độ này.

Cổng 3: Ranh giới thực thi

Một Task được giao cho Agent sẽ không khởi chạy khi vẫn còn nằm trong Backlog. Việc chuyển nó sang một trạng thái thuộc nhóm sẵn sàng làm việc mới là thứ khởi động lượt chạy, còn các nhóm completed, canceled và duplicate thì không bao giờ kích hoạt lượt chạy đầu tiên. Nhóm trạng thái vì thế chính là một cổng do con người chủ động vận hành, và nó hiển thị rõ trên bảng.

Có hai điều khiến cổng này không chỉ là thủ tục hình thức. Mỗi lượt chạy có một thư mục biệt lập, và những lượt chạy gắn với repository sẽ chuẩn bị một worktree mới, nên một lượt chạy đã được duyệt không thể làm hỏng một lượt chạy chưa ai duyệt. Và lượt chạy mang theo mô tả Task, các bình luận gần đây, cùng Workflow của Task — thứ giới hạn những trạng thái mà Agent được phép chọn. Agent không thể tự đánh dấu công việc của mình là đã nghiệm thu nếu Workflow không cấp cho nó trạng thái đó. Bài viết của chúng tôi về Git worktree với AI coding agent giải thích rõ hơn về cơ chế biệt lập này.

Cổng 4: Tín hiệu cần chú ý

Agent kết thúc một lượt chạy ở một trong hai điểm hữu ích: có kết quả, hoặc có câu hỏi. Sharkly đặt tên cho cả hai. Agent có thể để một Task ở trạng thái chờ con người trả lời hoặc chờ con người review, còn công việc thất bại hay bị chặn sẽ nổi lên thành một mục cần chú ý. Những tín hiệu đó đổ về Inbox, ở mục Primary, dành cho người chịu trách nhiệm, và các lượt chạy thất bại sẽ đến tay người được giao chứ không gửi cho tất cả người theo dõi.

Cổng ở đây là việc định tuyến, và đây chính là cổng mà nhiều nhóm vô tình làm sai nhất. Việc review mà đổ về một channel thì chẳng đến tay ai cả. Việc review đến tay người được giao là con người, ngay trên Task, với execution log chỉ cách một cú nhấp chuột, mới là review đến tay một người mà sau này ta còn có thể hỏi lại. Bài hướng dẫn về inbox của AI agent của chúng tôi nói rõ về cơ chế hàng đợi này.

Trả lời cũng chính là cách công việc tiếp diễn. Một bình luận của thành viên trên Task có người được giao là Agent đang ở trạng thái sẵn sàng có thể đưa một lượt chạy mới vào hàng đợi, nhờ đó phản hồi review tiếp nối chính công việc đó thay vì mở ra một quy trình thứ hai. Việc mention một người, hay dùng mention tất cả, tự nó không khởi động Agent, nhờ đó một cuộc trao đổi giữa người với người không đánh thức Agent dậy.

Cổng 5: Nghiệm thu trên hồ sơ

Nghiệm thu là việc một con người thay đổi trạng thái Task sau khi đọc bằng chứng. Hãy đọc theo thứ tự sau: tiêu chí nghiệm thu trong phần mô tả, bình luận của Agent nêu rõ những kiểm tra đã chạy và những điểm còn chưa chắc chắn, execution log, rồi mới đến diff. Log ghi lại lý do lượt chạy được đưa vào hàng đợi, thời điểm bắt đầu và kết thúc, các lệnh gọi công cụ và sự kiện Runtime, nguồn kích hoạt, cùng chi tiết lỗi; nó là khác biệt giữa việc review một thay đổi và việc review một câu chuyện kể về thay đổi đó.

Hai quy tắc bảo vệ cổng này. Việc merge một pull request được liên kết không làm thay đổi trạng thái Task, nên một lần merge không bao giờ bị nhầm là nghiệm thu. Và một lượt chạy Automation ở trạng thái completed chỉ mô tả chính lượt chạy đó, chứ không phải lời hứa rằng mọi kết quả phía sau đều đúng. Cả hai đều lấy trực tiếp từ tài liệu sản phẩm, và cả hai tồn tại vì các nhóm cứ mãi nhầm lẫn giữa "đã xong" và "đã đúng".

Toàn bộ quy trình trong một bảng

Khi nào nên mở rộng các cổng

Không phải Task nào cũng đáng đi qua năm chốt, và giả vờ rằng task nào cũng đáng chính là cách biến việc review thành màn trình diễn. Công việc chỉ đọc như rà soát repository chỉ cần cổng 1 và cổng 5. Công việc có thể đảo ngược trong một worktree biệt lập, ví dụ cập nhật dependency kèm test, có thể bỏ qua bước xác nhận kế hoạch. Với các Automation chạy theo lịch, phần hướng dẫn của chúng nên nêu rõ khi nào cần con người review hoặc quyết định, và nên chạy thủ công rồi kiểm tra kỹ trước khi để bất kỳ ai phụ thuộc vào lịch đó; bài hướng dẫn về Automation trong Sharkly của chúng tôi nói rõ về việc này.

Hãy giữ đủ cả năm cổng cho bất cứ thứ gì thay đổi giao diện công khai, động đến dữ liệu, hoặc không thể hoàn tác chỉ bằng một lệnh. Và hãy giữ một quy tắc ở mọi nơi: mỗi Task dành cho Agent đều phải có một người được giao cụ thể. Sharkly tách biệt trách nhiệm của con người và phần thực thi của Agent một cách có chủ đích, nên một Task có thể vừa có người được giao vừa có Agent được giao cùng lúc. Trách nhiệm giải trình không thể ủy thác, và hồ sơ phải cho thấy ai đang nắm nó.

Human-in-the-loop không phải là gì

Nó không phải là một người ngồi nhìn chằm chằm vào terminal. Nó không phải là một lời nhắc cấp quyền với một người review đã kiệt sức phía sau. Và nó cũng không phải một trạng thái ghi là Completed. Automation dừng lại ở đúng chỗ cần đến phán đoán của nhóm và trả về một sản phẩm bàn giao với đầy đủ ngữ cảnh cùng bằng chứng có thể kiểm tra được. Câu đó đã gói trọn cả quy trình; các cổng chỉ là nơi nó được thực thi. Sharkly không thay thế Claude Code, Codex hay các công cụ thực thi khác; nó là lớp ghi lại những quyết định này.

Câu hỏi thường gặp

Chế độ auto trong Claude Code có loại bỏ con người khỏi vòng lặp không? Nó loại bỏ con người khỏi lời nhắc cấp quyền. Bộ phân loại review các hành động dựa trên yêu cầu của bạn; nó không review xem kết quả có đáp ứng đúng yêu cầu hay không. Các cổng từ 2 đến 5 vẫn thuộc về con người.

Làm sao để dừng một Agent đang chạy giữa chừng? Một lượt thực thi đang trong hàng đợi hoặc đang chạy đều có thể bị hủy. Chuyển Task sang trạng thái Canceled hoặc Duplicate cũng dừng các lượt chạy đang hoạt động; còn chuyển sang Completed thì không, nên hãy hủy trước nếu Agent vẫn đang làm việc.

Ai nên là người review? Người được giao là con người trên Task. Sharkly gửi tín hiệu chờ review và tín hiệu thất bại đến đúng người đó, đó là lý do mỗi Task dành cho Agent đều nên nêu tên một người. Bài hướng dẫn về Agent trong Sharkly của chúng tôi giải thích hai vị trí giao việc này.

Phản hồi review có thể quay lại Agent mà không cần tạo Task mới không? Được. Một bình luận trên Task có thể đưa một lượt chạy tiếp theo vào hàng đợi cho Agent được giao, và các bình luận gửi liên tiếp nhanh sẽ được gộp lại để không tạo ra những lượt chạy trùng lặp.