Một đợt migration lớn không kết thúc ở "agent chạy xong". Nó kéo dài nhiều ngày, tốn tiền token, có lúc agent đi chệch, và cuối cùng phải bàn giao cho team review + merge. Bài này gói ghém khía cạnh vận hành để đợt migration cán đích an toàn và có thể kiểm toán.
Giám sát tiến độ qua manifest + dashboard tối giản
Manifest (Bài 3) là nguồn sự thật. Sinh báo cáo tiến độ từ nó bất cứ lúc nào:
jq -r '.batches[] | "\(.status)\t\(.scope)"' manifest.json | sort | uniq -c
# 18 done
# 2 in_progress
# 9 todo
# 1 escalated
Metric đáng theo dõi mỗi ngày: số lô done, số escalated (agent bó tay), số dòng diff, và xu hướng grep mục tiêu (grep -rc moment src phải giảm dần về 0).
Kiểm soát chi phí token
Agent tốn tiền theo token; một đợt lớn có thể đắt bất ngờ. Ba đòn bẩy:
- Đẩy việc cơ học sang codemod (Bài 1): mỗi chỗ codemod xử lý là token tiết kiệm.
- Chỉ nạp context cần thiết: đưa agent đúng file trong scope, đừng "dán cả repo".
- Giới hạn vòng tự sửa (
max_fix, Bài 6): cắt vòng lặp đốt tiền ở lô khó.
Ước lượng thô: chi phí ≈ số lô x (token đọc scope + token sinh diff + token verify-fix)
Theo dõi chi phí/lô; nếu một lô đắt bất thường -> nhiều khả năng nó "khó", nên chuyển sang review người.
Phát hiện agent đi chệch giữa chừng
Dấu hiệu cảnh báo (nên tự động cảnh báo trong runner):
- Diff phình to bất thường ở một lô (sửa file ngoài scope).
- Xuất hiện
@ts-ignore,.skip, xóa assertion (Bài 5). - Số test passed tụt so với baseline.
- Cùng một lô escalate lặp lại nhiều lần.
- Cài package mới ngoài dự kiến (guardrail Bài 2 phải chặn).
Phục hồi khi có sự cố
Nhờ commit nhỏ (Bài 2) và branch riêng (Bài 4), phục hồi rẻ:
git bisect start # tìm commit gây regression
git bisect bad HEAD
git bisect good safe/before-batch-12
# ... git tự khoanh vùng ...
git revert <commit-lô-hỏng> # gỡ đúng lô, giữ phần còn lại
Nếu đã dùng feature flag (Bài 7), phục hồi còn nhanh hơn: tắt cờ, không cần revert.
Bàn giao cho team: PR chia nhỏ, review được
Đừng gộp cả đợt migration thành một PR 300 file — không ai review nổi. Bàn giao theo PR-per-batch hoặc theo pha:
- Mỗi lô = một PR nhỏ, mô tả rõ khuôn mẫu áp dụng + link characterization diff.
- Đính kèm bằng chứng verify (log
VERIFY_OK, diff golden rỗng). - Reviewer tập trung vào các lô escalated / khó, lướt nhanh các lô cơ học đã có characterization.
- Merge tuần tự, verify trên main sau mỗi merge (Bài 4).
- Chỉ chạy pha CONTRACT (Bài 7) sau khi mọi PS MIGRATE đã merge và ổn định.
Checklist đóng một đợt migration
[ ] Manifest: 100% lô done, 0 escalated còn treo
[ ] grep mục tiêu = 0 trên toàn repo
[ ] verify.sh xanh trên main sau lần merge cuối
[ ] Số test passed >= baseline (Bài 2)
[ ] characterization diff rỗng / chỉ chứa thay đổi có chủ đích
[ ] Đã dọn worktree, branch tạm, feature flag chết
[ ] MIGRATION.md ghi lại quyết định + ca đặc biệt (bàn giao tri thức)
[ ] CONTRACT (xóa cái cũ) chỉ làm sau khi mọi caller đã chuyển
Sai lầm thường gặp
- Gộp cả đợt thành một PR khổng lồ: review qua loa, lỗi lọt lưới, khó revert.
- Không theo dõi chi phí: đốt token gấp nhiều lần dự tính mà không biết ở đâu.
- Bỏ qua tín hiệu agent đi chệch: merge nhầm code "ép xanh gian lận".
- Không có nhật ký bàn giao: team tiếp quản không hiểu vì sao xử lý ca lạ theo cách đó.
- Chạy CONTRACT khi chưa chắc cái cũ đã chết: gây sự cố production ngay lúc tưởng đã "xong".
Tổng kết cả khóa
Refactor/migration quy mô lớn bằng agent là sự kết hợp của: chọn đúng việc cho agent (Bài 1), dựng lưới an toàn + verify gate (Bài 2, 5), chia lô độc lập (Bài 3) để chạy song song bằng worktree (Bài 4), gói thành vòng lặp tự vận hành có escalation (Bài 6), dùng expand–migrate–contract khi buộc đổi hành vi (Bài 7), và vận hành–giám sát–bàn giao kỷ luật (Bài 8). Sợi chỉ đỏ xuyên suốt: agent nhân bản phán đoán, còn máy móc — không phải niềm tin — mới bảo chứng cho tính đúng đắn.