Trước khi cho agent chạm vào codebase, bạn phải dựng lưới an toàn. Nguyên tắc: agent được phép sai, nhưng hệ thống phải bắt được cái sai đó ngay lập tức và tự động. Không có lưới, một agent lỗi có thể phá 200 file trước khi bạn kịp phát hiện.
Bước 1 — Chốt baseline sạch
Baseline là trạng thái "biết chắc đang xanh" để so sánh. Nếu test đã đỏ sẵn từ trước, bạn sẽ không phân biệt được lỗi mới do agent gây ra.
git switch -c migrate/date-fns
npm ci # cài đúng lockfile, không trôi version
npm run build # phải xanh
npm run typecheck # phải xanh
npm test # ghi lại: 428 passed, 3 skipped
Ghi con số baseline (428 passed) vào một file MIGRATION.md. Sau này mỗi lô agent chạy xong, số passed không được tụt.
Bước 2 — Định nghĩa Verify Gate
Verify gate là một lệnh duy nhất trả về pass/fail, agent sẽ chạy sau mỗi thay đổi. Đóng gói nó thành script để không phụ thuộc trí nhớ:
#!/usr/bin/env bash
# verify.sh — cổng kiểm tra bắt buộc sau mỗi lô
set -euo pipefail
npm run typecheck
npm run build
npm test -- --run
echo "VERIFY_OK"
Agent chỉ được coi một lô là "xong" khi thấy VERIFY_OK. Đây là hợp đồng cứng.
Bước 3 — Dựng guardrail (rào chắn)
Guardrail giới hạn vùng agent được phép động vào, tránh "cháy lan":
- Giới hạn phạm vi file: chỉ cho agent sửa
src/**, cấm độngpackage.json,.github/,migrations/trừ khi được yêu cầu rõ. - Không cho tự cài dependency: agent tự thêm package lạ là nguồn rủi ro bảo mật lớn.
- Cấm sửa file test để "làm xanh": nếu test đỏ, phải sửa code chứ không phải sửa test. Ghi rõ trong system prompt.
- Commit nhỏ, thường xuyên: mỗi lô một commit → dễ
git bisect, dễ revert.
Bước 4 — Cơ chế rollback tức thì
Luôn có sẵn nút thoát hiểm:
git reset --hard HEAD~1 # bỏ lô cuối nếu verify đỏ
# hoặc dùng tag mốc an toàn
git tag safe/before-batch-12
Checklist trước khi cho agent chạy
[ ] Branch riêng, không phải main
[ ] npm ci sạch, lockfile khớp
[ ] Baseline build + typecheck + test đều xanh, đã ghi số
[ ] verify.sh chạy được, trả VERIFY_OK
[ ] Guardrail: danh sách file cấm sửa đã ghi rõ
[ ] Có tag/commit mốc để rollback
[ ] CI chạy trên mỗi push (lưới an toàn thứ hai)
Ví dụ hợp đồng cho agent (đưa vào prompt hệ thống)
Bạn refactor trong branch migrate/date-fns.
Sau MỖI file sửa, chạy ./verify.sh.
Nếu KHÔNG thấy VERIFY_OK -> tự sửa, KHÔNG được sửa file test để né lỗi.
Không cài package mới. Không sửa package.json.
Mỗi 5 file làm 1 commit với message rõ ràng.
Nếu kẹt >2 lần ở cùng 1 file -> dừng, báo cáo, để người xử lý.
Sai lầm thường gặp
- Bắt đầu khi test đang đỏ sẵn: không có baseline sạch thì mọi kết quả về sau đều mơ hồ.
- Verify gate quá chậm (chạy full test 20 phút mỗi file): agent sẽ "lười" bỏ qua. Hãy làm verify nhanh (typecheck + test liên quan) cho vòng lặp, full test cho cuối lô.
- Cho agent quyền sửa file test: nó sẽ "làm xanh" bằng cách xóa assertion — thảm họa âm thầm.
- Không giới hạn phạm vi file: agent sửa cả config CI, cả migration DB, gây hỏng lan rộng.
- Không commit nhỏ: khi có lỗi, không bisect được, phải bỏ cả ngày công.