Bài 1 — Vì sao refactor/migration quy mô lớn cần Agent, và giới hạn của nó

Refactor một hàm 20 dòng thì bạn tự làm nhanh hơn agent. Nhưng khi phải đổi tên một API dùng ở 800 file, migrate từ moment.js sang date-fns trên toàn repo, hay nâng framework từ Vue 2 lên Vue 3 với 300 component, công việc trở thành lặp lại, cơ học, nhưng vẫn cần phán đoán ngữ cảnh ở từng vị trí. Đây chính xác là vùng đất của agent: nó không mệt, không bỏ sót file, và có thể áp dụng cùng một khuôn mẫu quyết định hàng trăm lần.

Khác biệt giữa script và agent

Một sed regex thay chuỗi được cả 800 file trong 2 giây — nhưng nó mù ngữ cảnh: nó thay cả trong comment, trong string literal, trong test giả. Agent đọc hiểu code, biết import moment khác với chữ "moment" trong log message, biết một số chỗ cần đổi kèm cả cách gọi hàm. Đổi lại, agent chậm và tốn token, nên nguyên tắc vàng là:

> Việc nào regex/codemod làm được chính xác thì đừng để agent làm. Chỉ dùng agent cho phần cần phán đoán.

Ví dụ cụ thể: migrate 800 lời gọi API

Giả sử bạn đổi fetchUser(id) (trả Promise) thành getUser({ userId }) (trả Result object). Có 800 lời gọi. Phân loại:

• ~600 chỗ đơn giản: gọi thẳng, đổi tham số → codemod jscodeshift làm được, agent chỉ review.
• ~150 chỗ trung bình: có xử lý .catch(), cần chuyển sang kiểm tra result.error → agent xử lý theo khuôn mẫu.
• ~50 chỗ khó: lồng trong Promise.all, có retry logic riêng → agent xử lý từng cái, có thể cần người review.

Chỉ riêng việc phân loại trước này đã giúp bạn không đốt token vào 600 chỗ máy móc.

Khung tư duy: "Agent-Suitability"

Trước mỗi đợt lớn, chấm điểm công việc trên 4 trục:

[ ] Lặp lại nhiều (>50 lần)?          -> càng cao càng đáng dùng agent
[ ] Cần đọc hiểu ngữ cảnh từng chỗ?   -> nếu KHÔNG, dùng codemod
[ ] Có cách verify tự động (test/build/typecheck)? -> BẮT BUỘC phải có
[ ] Rủi ro nếu sai một chỗ?           -> càng cao, chia càng nhỏ, review càng kỹ

Nếu ô "có cách verify tự động" trống, dừng lại — không có verify thì agent chỉ đang tạo ra rủi ro hàng loạt.

Các bước khởi động một đợt migration

• Định nghĩa "xong" bằng máy kiểm được: ví dụ "npm run build xanh, npm test xanh, grep -r 'fetchUser' trả về 0 kết quả".
• Đo phạm vi: đếm số file/lời gọi bị ảnh hưởng (grep -rl), đây là baseline để chia nhỏ.
• Tách phần cơ học ra codemod, để lại phần cần phán đoán cho agent.
• Dựng lưới an toàn: đảm bảo test/build chạy được cục bộ trước khi cho agent động vào.
• Migrate thử 5–10 file làm mẫu, chốt khuôn mẫu, rồi mới nhân rộng.

Giới hạn thật của agent

• Cửa sổ ngữ cảnh hữu hạn: không nhét cả repo vào một lần được → phải chia nhỏ (Bài 3).
• Ảo giác thay đổi "trông đúng": code chạy được nhưng sai ngữ nghĩa → phải verify bằng test, không tin mắt (Bài 5).
• Trôi dạt khuôn mẫu (pattern drift): xử lý file thứ 300 khác cách file thứ 3 → cần khuôn mẫu chốt cứng.

Sai lầm thường gặp

• Giao cả repo cho agent trong một prompt và mong nó "tự lo": chắc chắn hết context, kết quả không nhất quán.
• Không có test/build xanh trước khi bắt đầu: bạn sẽ không phân biệt được lỗi do agent hay lỗi có sẵn.
• Dùng agent cho việc regex làm được: đốt tiền, chậm, mà độ chính xác không hơn.
• Coi "code biên dịch được" là "đã xong": biên dịch được không có nghĩa hành vi đúng.

Kết bài: agent là công cụ nhân bản phán đoán, không phải phép màu. Hai bài tiếp theo sẽ dựng nền tảng an toàn và chiến lược chia nhỏ để nhân bản đó không biến thành thảm họa hàng loạt.