Cách bàn giao công việc giữa các giai đoạn

"Đã sửa phần xuất dữ liệu, còn phải kiểm tra" - rồi công việc dừng ở đó. Hôm sau, bạn mở project mà không biết những file nào đã thay đổi, dữ liệu xuất được xem trên phiên bản nào, và việc kiểm tra đã dừng ở đâu.

Để tiếp tục mà không phải tìm hiểu lại từ đầu, giai đoạn tiếp theo cần kết quả đã lưu, thông tin về những gì đã kiểm tra và bước gần nhất cần làm. Hãy xem cách bàn giao này qua một nhiệm vụ: một session, nhiều người thực hiện hoặc chính bạn chia làm hai lần đều có thể đảm nhận.

Bàn giao kết quả có thể mở ra xem

Chức năng xuất CSV trong danh sách mua sắm đang bị lỗi. Yêu cầu: file xuất chỉ chứa các mục đang hiển thị và giữ nguyên thứ tự của chúng. Với danh sách trống, thống nhất giữ lại hàng tiêu đề, không có hàng dữ liệu. Không cần thay đổi định dạng cột hay ký tự phân tách.

Thay vì ghi "đã sửa, còn phải kiểm tra", ta để lại một bản ghi giúp tìm ra thay đổi và tiếp tục công việc. Các hash và kết quả bên dưới chỉ là giả định: đây là ví dụ minh họa, không dựa trên lần chạy thực tế nào.

HANDOFF
Mục tiêu: CSV chỉ chứa các mục đang hiển thị theo đúng thứ tự hiện tại.
Phiên bản đầu vào: commit gốc 4f1c2ab.
Trạng thái bàn giao: commit 9d3e740 trên branch fix-export, không có chỉnh sửa bổ sung.
Kết quả: src/export-csv.js - chức năng xuất lấy danh sách sau khi lọc và sắp xếp.
Đã kiểm tra thủ công trên 9d3e740: các mục ban đầu A, B, C; trên màn hình C, A;
  trong CSV có các hàng dữ liệu C, A, không có mục B. Không tính tiêu đề là một mục.
Chưa kiểm tra: danh sách trống; chế độ "chỉ các mục chưa hoàn thành".
Quyết định: không thay đổi định dạng cột và ký tự phân tách.
Bước tiếp theo: session chính kiểm tra hai tình huống còn lại.
Trạng thái nhiệm vụ chung: chưa hoàn tất việc kiểm tra.

Các chữ cái đại diện cho ba mục trong danh sách. Tình huống này kiểm tra đồng thời hai điều: mục B bị ẩn không xuất hiện trong file, và thứ tự C, A khớp với màn hình. Chỉ nhận được hai hàng từ một danh sách vốn chỉ có hai mục thì chưa đủ: chức năng xuất không lọc gì cũng cho ra kết quả như vậy.

Bạn có thể lưu bản ghi vào HANDOFF.md hoặc bổ sung vào tài liệu nhiệm vụ hiện có. Không có quy chuẩn bắt buộc về các trường. Điều quan trọng là người thực hiện tiếp theo có thể mở bản ghi cùng các file liên quan, kể cả khi họ không xem được cuộc trò chuyện trước đó.

Nếu việc kiểm tra được chạy bằng một lệnh, hãy ghi lại lệnh đó cùng kết quả thực tế và phiên bản mã. "12 trên 12 đã đạt" không cho biết hành vi nào được kiểm tra. Với tình huống kiểm tra thủ công, cần có dữ liệu đầu vào, thao tác và điều quan sát được như ví dụ trên.

Đặt điều kiện đầu vào và đầu ra

Bàn giao hữu ích khi giai đoạn tiếp theo biết thông tin nhận được đã đủ chưa. Với nhiệm vụ này, có thể mô tả bằng ba hàng.

Cột quan trọng nhất nằm bên phải. Khi chuyển sang giai đoạn kiểm tra, nó trả lời câu hỏi "đã có thể bắt đầu kiểm tra chưa?". Dù bản sửa được mô tả đầy đủ, nó vẫn có thể sai. Kết quả kiểm tra cũng có thể phát hiện lỗi cần sửa: một báo cáo hữu ích không nhất thiết phải thông báo thành công.

Nếu không ghi phiên bản, trước tiên hãy xác định trạng thái hiện tại của các file. Bạn vẫn có thể kiểm tra, nhưng không thể áp dụng báo cáo cũ cho trạng thái đó mà chưa đối chiếu. Các giai đoạn không cần agent hay tài liệu riêng: một nhiệm vụ nhỏ có thể đi qua cả ba giai đoạn trong cùng một session với một ghi chú.

Lưu trạng thái đã chấp nhận

Khi bàn giao, rất dễ gộp nhầm ba việc khác nhau:

• trạng thái mã đã lưu - một phiên bản cụ thể có thể khôi phục;
• ghi chú tiến độ - đã làm gì, kiểm tra những gì, thống nhất điều gì;
• chấp nhận kết quả - quyết định rằng phần việc đã làm đủ để đạt mục tiêu.

Commit cho biết những file được lưu trong đó. Nhưng nếu sau commit còn thay đổi bổ sung, tham chiếu đó không còn mô tả toàn bộ trạng thái bàn giao: các chỉnh sửa ấy cũng cần được lưu và liệt kê riêng, kể cả file mới. Khi bàn giao một tập hợp thay đổi, hãy nêu cả phiên bản gốc dùng để đối chiếu. Chỉ ghi tên branch là chưa đủ: branch vẫn tiếp tục thay đổi.

Hãy hình dung bản ghi nêu 9d3e740, nhưng file xuất đã được chỉnh sửa sau commit đó. Người nhận thấy hash quen thuộc nhưng sẽ làm việc với mã khác. Trước tiên, họ cần tìm hiểu điều gì đã thay đổi. Nếu chỉnh sửa ảnh hưởng đến việc chọn mục hoặc thứ tự của chúng, lần kiểm tra C, A trước đó không xác nhận được hành vi hiện tại. Nếu chỉ thay đổi nội dung một comment, riêng việc đó không phải lý do để chạy lại tình huống.

Không nhất thiết phải tạo commit sau mỗi bước hoặc gộp chỉnh sửa của bạn và người khác vào một commit. Điều quan trọng là trạng thái bàn giao tồn tại đầy đủ và người nhận có thể truy cập; cách lưu do quy ước của project quyết định. Nếu thiếu file, trước tiên hãy kiểm tra phiên bản đã lưu. Nếu thay đổi chưa được lưu ở đâu, một ghi chú cũng không khôi phục được chúng.

Tiếp tục cuộc trò chuyện không tự đưa các file về phiên bản đã mô tả. Checkpoint chỉnh sửa của Claude Code cũng không bao gồm mọi thay đổi: chỉnh sửa qua Bash không được theo dõi, còn việc khôi phục thay đổi của người thực hiện khác có những giới hạn. Vì thế, bản bàn giao dựa vào các file đã lưu và phiên bản của chúng. Xem thêm: Checkpointing.

Tìm hiểu nguyên nhân công việc bị dừng

"Không thành công" có thể là ít nhất ba tình huống khác nhau.

Lần chạy cục bộ bị gián đoạn. Lệnh chưa chạy xong hoặc việc kiểm tra dừng giữa chừng. Trước tiên hãy tìm hiểu những gì đã chạy và thay đổi. Nếu nguyên nhân đã được khắc phục và chạy lại không lặp lại một thao tác đã hoàn tất, bạn có thể làm lại bước chưa xong. Với ví dụ này, ta thống nhất thử lại một lần; nếu lần đó cũng bị gián đoạn, hãy ghi lại lý do dừng và những gì cần để tiếp tục. Giới hạn tùy thuộc vào thao tác, còn thử lại mãi cũng chẳng giải thích được gì.

Chưa rõ hành vi mong muốn. Chẳng hạn, người thực hiện không biết những mục nào được tính là đang hiển thị khi bật bộ lọc. Trước hết, họ đối chiếu với yêu cầu đã ghi. Nếu yêu cầu không có câu trả lời, họ hỏi người phụ trách yêu cầu. Có thể tiếp tục sửa sau khi nhận được câu trả lời; chạy lại không thể thay thế việc đó.

Thông tin mới bác bỏ quyết định đã chấp nhận. Hóa ra có một chương trình khác đọc CSV. Sau khi làm rõ, mọi người thống nhất bộ cột khác và bỏ yêu cầu về thứ tự. Công việc quay lại bước làm rõ: cần ghi tiêu chí mới, xem lại bản sửa và các bước kiểm tra phụ thuộc vào tiêu chí đó. Tình huống đã kiểm tra trước đây vẫn có thể hữu ích, nhưng không còn xác nhận toàn bộ nhiệm vụ đã cập nhật.

Công việc quay lại bước làm rõ ở đây vì quyết định ban đầu đã thay đổi. Nếu yêu cầu vẫn giữ nguyên mà lỗi nằm ở khâu triển khai, quay lại giai đoạn thay đổi là đủ. Chỉ xem xét lại những kết quả phụ thuộc vào quyết định bị ảnh hưởng.

Tiếp tục từ điểm hiện tại

Khi tiếp tục công việc, hãy làm theo năm bước:

1. đọc toàn bộ bản bàn giao, kể cả phần chưa kiểm tra;
2. đối chiếu trạng thái được bàn giao với các file hiện có và những thay đổi bổ sung;
3. nếu có thao tác bị gián đoạn, tìm hiểu kết quả của thao tác đó;
4. xác định những kết quả trước đây còn hiệu lực;
5. thực hiện bước gần nhất chưa hoàn thành và cập nhật bản ghi.

Quay lại ví dụ ban đầu, trong đó yêu cầu không thay đổi. Session tiếp theo mở bản bàn giao và đối chiếu trạng thái: commit 9d3e740 có sẵn, không có chỉnh sửa bổ sung, dữ liệu và điều kiện kiểm tra vẫn như trước. Tình huống C, A đã hoàn tất, kết quả vẫn áp dụng được. Không cần viết lại bản sửa.

Giờ người nhận kiểm tra danh sách trống. Theo yêu cầu, CSV cần giữ lại hàng tiêu đề và không có dữ liệu. Trong phần tiếp nối giả định của ví dụ này, kết quả đúng như vậy. Chỉ cần bổ sung kết quả vào bản ghi và cập nhật bước còn lại:

Đã kiểm tra thủ công trên 9d3e740: xuất danh sách trống chỉ có hàng tiêu đề.
Tình huống C, A đã kiểm tra trước đó vẫn còn hiệu lực.
Chưa kiểm tra: chế độ "chỉ các mục chưa hoàn thành".
Bước tiếp theo: session chính kiểm tra chế độ này.
Trạng thái nhiệm vụ chung: chưa hoàn tất việc kiểm tra.

Bản bàn giao thay đổi theo tiến độ công việc. Một trong hai tình huống còn lại đã hoàn thành, tình huống kia vẫn được nêu rõ. Kết quả một phần không hoàn tất mục tiêu ban đầu; chuyển việc kiểm tra sang nhiệm vụ khác cần có quyết định riêng về việc thay đổi phạm vi.

Nếu lần chạy bị gián đoạn, có thể cần thực hiện lại tình huống đó từ đầu: không phải công cụ nào cũng tiếp tục được từ giữa chừng. Các bước kiểm tra đã hoàn tất vẫn có giá trị miễn là mã, dữ liệu đầu vào và điều kiện còn phù hợp.

Ai chuẩn bị bản bàn giao

Claude Code có thể thu thập dữ kiện, đối chiếu đầu vào của giai đoạn tiếp theo và thực hiện bước đã thống nhất. Bạn kiểm tra xem bản ghi có khớp với các file và kết quả chạy hay không. Con người hoặc người phụ trách được chỉ định sẽ quyết định các yêu cầu còn tranh luận và việc thay đổi phạm vi; trong quy trình này, người đưa ra quyết định chấp nhận cuối cùng vẫn là con người.

Phiên bản đã lưu giúp tiếp tục công việc, nhưng không mở rộng quyền hạn của người thực hiện. Nếu nhiệm vụ là kiểm tra chức năng xuất, có điểm khôi phục không có nghĩa là được tiện thể thay đổi định dạng cột. Giới hạn của nhiệm vụ vẫn còn hiệu lực sau khi bàn giao.