Mỗi khi một coding agent hoàn thành nhiệm vụ, cũng lại xuất hiện khoảng trống quen thuộc. Bạn nhận được một diff cùng câu "xong rồi" đầy hào hứng, nhưng không biết cái gì đã thay đổi, cái gì bị bỏ qua, cái gì đã được kiểm thử, hay agent còn chỗ nào chưa chắc chắn. Thế là bạn lại phải đọc lại diff, tự chạy lại test, và hỏi lại những câu mà agent lẽ ra đã có thể trả lời ngay khi bàn giao. Chạy hai agent thì chi phí đó nhân đôi. Công việc không phải là vấn đề. Vấn đề nằm ở khâu bàn giao: cái gì được truyền từ người yêu cầu sang agent thực hiện, và cái gì được trả về.
Một mẫu bàn giao cho coding agent là cấu trúc cố định cho những gì mà một nhiệm vụ mang theo khi đổi tay: từ người sang agent lúc giao việc, và từ agent về lại người lúc duyệt. Thay vì ứng biến hình dạng của mỗi lần chuyển giao, bạn điền đúng các trường như nhau mỗi lần. Agent biết "xong" nghĩa là gì trước khi bắt đầu, và bạn nhận được cùng một dạng tóm tắt, bằng chứng và câu hỏi mở khi nó dừng lại.
Bài viết này đi qua hai mẫu thực sự trụ vững trong thực tế, dùng Sharkly làm quy trình: lớp nằm trên các coding agent của bạn, giúp giữ context, tiến độ, điểm tắc nghẽn, kết quả và phần duyệt của con người luôn hiển thị từ lúc yêu cầu đến lúc phát hành. Bạn đã có coding agent rồi. Sharkly biến chúng thành một đội, và mẫu bàn giao chính là thứ khiến mỗi lần chuyển giao trở thành một bản ghi thay vì một phỏng đoán.
Mẫu bàn giao cho coding agent là gì
Một mẫu bàn giao là một checklist được cấu trúc hóa. Nó trả lời ba câu hỏi mà một diff trần trụi không bao giờ trả lời được: đã yêu cầu điều gì, đã xảy ra chuyện gì, và giờ đến lượt ai. Khi ba thứ đó đi cùng nhau, người làm bước tiếp theo chỉ cần đọc một bản ghi thay vì phải dựng lại ba mảnh ghép.
Có hai lần bàn giao đáng để làm mẫu, vì chúng chạy theo hai hướng ngược nhau và mang theo những thứ trái ngược:
- Bàn giao khi giao việc (từ người hoặc Agent trưởng đến một Agent): mục tiêu, ranh giới và định nghĩa hoàn thành, được chuyển xuống trước khi bắt đầu làm.
- Bàn giao khi duyệt (từ Agent về lại người): thay đổi, bằng chứng rằng nó hoạt động, và những phần mà con người vẫn phải đánh giá, được chuyển lên khi công việc dừng lại.
Điểm mấu chốt là làm mẫu cho cả hai. Hầu hết các team chỉ viết một ticket sơ sài và không làm mẫu gì ở chiều trả về, nên mọi lần duyệt đều bắt đầu như một cuộc thẩm vấn. Sửa được chiều trả về chính là chỗ tiết kiệm thời gian.
Mô hình vận hành mà mẫu này gói gọn
Một mẫu chỉ tốt bằng mô hình vận hành nằm bên dưới nó. Bốn động từ quyết định ai sở hữu từng đường nối: ai giao việc, ai thực thi, ai duyệt, ai chấp nhậ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à chấp nhận kết quả. Tự động hóa dừng lại ở nơi cần đến phán đoán của team.
Chính giao kèo đó là lý do hai mẫu mang những trường khác nhau. Agent không bao giờ nên đoán mò tiêu chí chấp nhận trông như thế nào, nên mẫu giao việc buộc người yêu cầu phải viết nó ra. Con người cũng không bao giờ nên đoán xem màu xanh có nghĩa là an toàn hay không, nên mẫu duyệt buộc Agent phải trình bày cách nó làm. Dưới đây là mẫu bàn giao khi giao việc dưới dạng khối copy-paste:
## Assignment handoff
Task ID: SH-###
Goal: one sentence, in plain language
In scope: the specific files, endpoints, or behaviors to touch
Out of scope: what to leave alone (auth, billing, public contracts)
Definition of done:
- [ ] observable acceptance criterion 1
- [ ] observable acceptance criterion 2
Constraints: frameworks, patterns, or limits to respect
Assignee: the exact Agent that owns this
Hai dòng "out of scope" và "definition of done" gánh phần việc nặng nhất. Không có chúng, agent sẽ tối ưu cho một diff chạy được, chứ không phải cho kết quả mà bạn thực sự muốn. Có chúng, phần kiểm tra chấp nhận được viết ra trước khi có dù chỉ một dòng code.
Bàn giao khi duyệt: cái gì được trả về
Mẫu chiều trả về là thứ bị hầu hết quy trình bỏ qua, và cũng là thứ cứu cả buổi chiều của bạn. Khi một Agent làm xong, nó không nên chỉ ping bạn với câu "sẵn sàng rồi" kèm một link. Nó nên trả về một cấu trúc đã được điền đầy đủ:
## Review handoff
Task ID: SH-###
Summary: what changed, in 2-3 sentences
Acceptance: each definition-of-done item, checked with how it was verified
Tests: typecheck / unit / build results, pasted or linked
Diff: the PR or worktree branch
Known limits: what this does NOT cover, and any risky assumption
Open questions: decisions left for a human
Hai trường "known limits" và "open questions" chính là thứ phân biệt một lần bàn giao thực thụ với một bức tường toàn dấu tick xanh. Một giới hạn trung thực ("bộ đếm Redis giả định chỉ chạy một vùng") biến một lần merge mù quáng thành một lần merge có hiểu biết. Đây cũng chính là nguyên tắc đằng sau việc duyệt code do AI tạo ra bằng bằng chứng ở cấp nhiệm vụ: người duyệt đọc một lời khẳng định kèm chứng cứ của nó, chứ không phải một diff kèm niềm hy vọng.
Một ranh giới đáng nói thẳng: bàn giao khi duyệt không phải là một yêu cầu merge. Nó là một yêu cầu duyệt. Agent trình bày; con người quyết định. Giữ tách bạch hai hành động đó chính là thứ ngăn công việc chưa được duyệt bị đẩy lên môi trường thật.
Trạng thái và cổng duyệt: nơi mẫu trú ngụ
Một mẫu nằm trong buffer cuộn màn hình là một mẫu không ai đọc. Bàn giao phải được gắn vào một thứ được chia sẻ, và trạng thái chính là chỗ ở tự nhiên. Mỗi Nhiệm vụ đi qua một làn, và mỗi lần đổi trạng thái là một lần bàn giao có mẫu đi kèm:
| Trạng thái | Chủ sở hữu | Mẫu đi kèm |
|---|---|---|
| Todo | Người hoặc Agent trưởng | Bàn giao khi giao việc |
| Đang thực hiện | Agent | (đang làm việc trong một worktree tách biệt) |
| Sẵn sàng để duyệt | Agent | Bàn giao khi duyệt |
| Hoàn thành | Người | ghi chú chấp nhận + quyết định merge |
Quy tắc khiến điều này dễ đọc: Agent đưa Nhiệm vụ sang Sẵn sàng để duyệt; Con người đưa nó sang Hoàn thành. Agent không bao giờ tự đánh dấu công việc của mình là Hoàn thành, và con người không bao giờ phải dựng lại chuyện gì đã xảy ra, vì bàn giao khi duyệt đã nằm sẵn trên Nhiệm vụ. Trong Sharkly, quá trình thực thi, điểm tắc nghẽn, kết quả và thảo luận tiếp theo đều quay về dòng thời gian của Nhiệm vụ, nên khi mười agent đang chạy, bạn đọc bảng điều khiển chứ không phải mười terminal. Đó là khác biệt giữa việc theo dõi những gì agent đã hoàn thành và việc hy vọng rằng commit log sẽ giải thích mọi thứ sau này. Chỗ nào công việc tự động cần phải dừng lại cũng là một lựa chọn thiết kế, được bàn trong nên đặt cổng phê duyệt ở đâu.
Ví dụ minh họa: từ ticket đến PR đã merge
Lấy một Nhiệm vụ có hình dạng thực tế, SH-441: "Thêm xuất CSV cho trang báo cáo." Hãy xem các mẫu được điền vào, chứ không phải code.
Một người mở SH-441 và một Agent trưởng hoàn thành mẫu bàn giao khi giao việc: mục tiêu ("cho phép người dùng tải báo cáo hiện tại về dưới dạng CSV"), trong phạm vi (controller của trang báo cáo và một module xuất mới), ngoài phạm vi (auth, các truy vấn báo cáo hiện có), và một định nghĩa hoàn thành với ba mục kiểm tra được (một nút tải xuống, escape đúng cho dấu phẩy và dấu ngoặc kép, một test với fixture 10k dòng). Assignee là một backend Agent. Không có gì mơ hồ, vì mẫu không cho phép nó mơ hồ.
Backend Agent nhận Nhiệm vụ, làm việc trong một worktree tách biệt để không bao giờ đụng độ với công việc khác, và chạy các mục trong định nghĩa hoàn thành như checklist của chính nó. Khi typecheck, unit test và build đều xanh, nó đưa SH-441 sang Sẵn sàng để duyệt với mẫu chiều trả về đã điền: một tóm tắt ngắn, từng mục chấp nhận được tick kèm cách nó được xác minh, diff, và một giới hạn đã biết ("xuất trên 100k dòng sẽ buffer trong bộ nhớ; chưa triển khai streaming").
Giờ thì bàn giao đổi chiều. Một người đọc một bản ghi, không phải một buffer cuộn. Họ xác nhận test escape, cân nhắc giới hạn bộ nhớ so với kích thước báo cáo thực tế, chấp nhận nó cho hiện tại, và đưa SH-441 sang Hoàn thành, từ đó kích hoạt việc merge. Từ ticket đến PR đã merge, với một mẫu đã điền ở cả hai đầu nối và một bản ghi về việc ai sở hữu phần nào. Đây là con đường từ yêu cầu đến code được làm cho có thể truy vết từ đầu đến cuối.
Khi nào một mẫu là quá mức cần thiết
Mẫu có chi phí của nó, nên đây là cặp quyết định trung thực. Bỏ qua mẫu đầy đủ cho những công việc nhỏ, đã rõ ràng mà một Agent hoàn thành trong một lượt, khi mục tiêu và tiêu chí chấp nhận đã hiển nhiên ngay từ tiêu đề Nhiệm vụ. Hãy dùng đến nó ngay khi công việc vượt qua một đường nối quan trọng: nhiều agent cùng một mục tiêu, một thay đổi ảnh hưởng đến hợp đồng công khai, hoặc bất cứ thứ gì đụng đến auth, billing, hoặc dữ liệu mà bạn không thể dễ dàng thu hồi. Một mẫu là bảo hiểm chống lại việc rơi mất context, và bạn mua bảo hiểm ở nơi mà tổn thất sẽ đau.
Bạn có thể chạy tất cả những điều này bằng tay với một bảng chia sẻ và tính kỷ luật. Cách đó hiệu quả cho đến khi số lượng agent, nhiệm vụ và repository tăng lên, và tính kỷ luật là thứ đầu tiên bị bỏ rơi. Nếu bạn đang chạy vài agent, Sharkly cho bạn một nơi để quản lý nhiệm vụ và kết quả của chúng: các Nhiệm vụ chia sẻ mang theo cả bàn giao khi giao việc lẫn khi duyệt, Assignee theo từng Nhiệm vụ, các worktree tách biệt, và một làn trạng thái nơi Agent đạt đến Sẵn sàng để duyệt và Con người quyết định Hoàn thành. Giữ nguyên những coding agent bạn đang dùng. Tải Sharkly khi các đường nối giữa chúng bắt đầu tốn kém hơn cả công việc.
Câu hỏi thường gặp
Mẫu bàn giao cho coding agent là gì? Đó là một cấu trúc cố định cho những gì một nhiệm vụ mang theo khi đổi tay. Có hai loại: bàn giao khi giao việc (mục tiêu, phạm vi và định nghĩa hoàn thành, từ người sang Agent) và bàn giao khi duyệt (tóm tắt, bằng chứng và những giới hạn đã biết, từ Agent về lại người). Điền đúng các trường như nhau mỗi lần chính là thứ giữ cho context không bốc hơi giữa những người làm việc.
Tại sao phải làm mẫu cho chiều trả về mà không chỉ làm cho ticket? Hầu hết các team chỉ viết ticket và không làm mẫu gì ở chiều trả về, nên mọi lần duyệt đều bắt đầu như một cuộc thẩm vấn. Bàn giao khi duyệt, với phần tóm tắt, các mục chấp nhận đã được tick và những giới hạn đã biết, chính là chỗ mà một mẫu tiết kiệm nhiều thời gian nhất. Xem coding agent có con người trong vòng lặp.
Agent có nên tự đánh dấu công việc của mình là hoàn thành không? Không. Hãy để Agent đưa Nhiệm vụ sang Sẵn sàng để duyệt với mẫu chiều trả về đã điền; để việc chuyển sang Hoàn thành, cùng quyết định merge, cho con người. Tách bạch giữa "đã trình bày" và "đã chấp nhận" chính là thứ ngăn code chưa được duyệt bị đẩy lên môi trường thật.
Mẫu nên được đặt ở đâu? Trên một Nhiệm vụ chia sẻ, gắn với một lần đổi trạng thái, chứ không phải trong một terminal mà chỉ một agent nhìn thấy. Khi bàn giao là một trạng thái có mẫu đi kèm, người làm bước tiếp theo thấy chính xác cái gì đang chờ đợi họ. Điều này cũng giúp việc duyệt không trở thành nút thắt cổ chai khi nhiều agent cùng hoàn thành một lúc.
Tôi có cần một công cụ cho việc này không, hay có thể làm thủ công? Bạn có thể chạy nó với một bảng chia sẻ và tính kỷ luật. Một lớp chuyên dụng sẽ đáng đầu tư khi bạn phải phối hợp nhiều agent trên nhiều repository và việc theo dõi thủ công trở thành chính công việc. Hãy so sánh nó với một trình quản lý nhiệm vụ AI cho công việc của agent đa dụng.
