Handoff brief và luật 3 strikes khi chạy coding agent

Bạn giao một task cho Claude Code hay Codex, diff trả về trông hợp lý nhưng sửa đúng ba file bạn không muốn ai đụng tới. Vài giờ sau bạn gõ "fix it" lần thứ tư, agent trả về đúng lỗi cũ, credit đã bay.

Hai thói quen dưới đây — handoff brief viết trước khi agent chạy, và luật 3 strikes khi nó đã kẹt — nhắm đúng hai điểm gãy đó, và đều là quy trình, không cần tool mới.

Trước khi chạy: handoff brief 7 mục

Theo tác giả bài "The handoff brief": phần lớn agent run đi chệch hướng không gãy ở code mà gãy ở khâu handoff — task nằm trong đầu một người, prompt chỉ mang theo một nửa. Có brief thì review thành phép so sánh: run có làm đúng những gì brief nói, và không làm gì thêm? Brief gồm 7 mục:

• Goal — outcome, không phải cách làm.
• Scope — được sửa gì, ghi theo path hoặc module.
• Off limits — file không được đụng, kể cả khi agent nghĩ nên sửa.
• Checks — đúng các lệnh chứng minh thay đổi chạy được.
• Done — trạng thái quan sát được, đạt thì task kết thúc.
• Report back — summary bắt buộc chứa gì.
• Escalate, don't guess — quyết định thuộc về con người.

Mục cuối làm nhiều việc nhất, theo tác giả: gặp chỗ mơ hồ agent gần như luôn tự quyết, nên liệt kê sẵn để phán đoán âm thầm thành câu hỏi trong report. Đáng cho vào "escalate": thay đổi lộ ra ngoài interface, thêm dependency, chạm secrets, và check không pass nổi nếu không sửa file off-limits.

Khi agent bắt đầu đoán: tách giải thích khỏi sửa

Thói quen thứ hai: ngừng yêu cầu "just fix it" cho tới khi agent giải thích được chuyện gì đang xảy ra — tác giả cho biết riêng thay đổi này cắt được phần lớn vòng lặp của anh. Các tool kiểu Cursor, Lovable, Bolt hay Replit giỏi tạo thay đổi, nhưng kém ở chỗ biết khi nào mình đang đoán. Ba prompt dùng gần như nguyên văn (thay nội dung trong ngoặc vuông):

1. Here's the exact error: [error]. Before you change anything,
   explain what it means, which file, most likely cause.
   Don't edit till I say go.

2. These parts work and must not change: [list]. Only edit files
   related to [the bug]. List the files you plan to change and wait.

3. You said this was fixed, but it isn't. Stop editing. What's the
   cause, what's your evidence, what have you already tried?
   Then suggest something different.

Paste nguyên error thật từ console, terminal hay build log — mô tả kiểu "login hỏng rồi" sẽ đẩy agent đi dạo khắp app. Có ask/plan mode thì dùng cho bước 1.

Luật 3 strikes và chuyện rollback

Sau ba lần fix hỏng cho cùng một bug trong cùng một chat thì dừng, đừng thử lần thứ tư. Quy trình: xin handover note ngắn (vấn đề, error chính xác, đã thử gì, file nào quan trọng — dưới 200 từ, không kèm key hay secret), rollback về bản chạy được, mở chat mới, paste note kèm yêu cầu không lặp lại. Đường rollback từng tool, như bài viết mô tả:

Tool	Cách quay lại	Lưu ý
Cursor	Hover message cũ → Restore Checkpoint	Chỉ khôi phục file; checkpoint local, tách khỏi Git
Lovable	History → Revert về bản chạy được	Chỉ khôi phục code, không undo database, không hoàn credit
Bolt	Version history → Restore this version	Không đụng database Bolt/Supabase; lấy note trước rồi mới /clear
Replit	Agent chat → history → Rollback to here	Mặc định không đổi database; cũng tua lại context của Agent

Cái bẫy còn lại

Luật đúng cho cả bốn tool: rollback khôi phục code, không khôi phục dữ liệu sống. Nếu agent đã chạm database trong loop, kiểm tra riêng — và nên commit một bản chạy được trước khi giao task rủi ro.

Việc đáng làm tuần này: lưu handoff brief thành snippet trong repo, và dán luật 3 strikes vào project knowledge của tool — nơi nó sống sót qua clear context.