Cẩm Nang Điều Phối AI Agent: Làm Chủ Quy Trình Viết Code Tự Động

Khi làm việc với các AI Coding Agent, sự khác biệt giữa một đoạn mã “chạy được” và một sản phẩm phần mềm chất lượng nằm ở quy trình. Tài liệu hướng dẫn này thiết lập các tiêu chuẩn để AI lập kế hoạch, thực thi, xác minh và sửa lỗi trong môi trường codebase thực tế.

1. Nguyên Tắc Hoạt Động Cốt Lõi

Trước khi bắt đầu bất kỳ dòng code nào, AI Agent cần tuân thủ 5 nguyên tắc vàng:

1. Chính xác hơn Thông minh: Ưu tiên các giải pháp nhàm chán nhưng dễ đọc và dễ bảo trì hơn là các đoạn mã thông minh nhưng phức tạp.
2. Thay đổi nhỏ nhất có thể: Giảm thiểu “phạm vi ảnh hưởng” (blast radius). Không tái cấu trúc code xung quanh trừ khi nó thực sự giảm rủi ro.
3. Tận dụng khuôn mẫu có sẵn: Tuân theo quy ước của dự án trước khi giới thiệu các thư viện hay mô hình trừu tượng mới.
4. Chứng minh nó hoạt động: Không chấp nhận cảm giác “có vẻ đúng”. Mọi thứ phải được xác thực bằng test, lint, build hoặc quy trình tái hiện thủ công.
5. Rõ ràng về sự không chắc chắn: Nếu không thể xác minh điều gì, hãy nói rõ và đề xuất cách kiểm tra an toàn nhất.

2. Quy Trình Điều Phối Công Việc

Để giải quyết các tác vụ phức tạp, AI Agent nên tuân theo quy trình 7 bước sau:

Chế Độ Lập Kế Hoạch

Đối với bất kỳ tác vụ không tầm thường nào (trên 3 bước, thay đổi nhiều file, hoặc ảnh hưởng đến kiến trúc), AI bắt buộc phải vào “Chế độ lập kế hoạch”.

• Viết một bản mô tả ngắn gọn (spec) về đầu vào/đầu ra và các trường hợp biên.
• Bao gồm các bước xác minh ngay trong kế hoạch.
• Quy tắc dừng: Nếu có thông tin mới làm hỏng kế hoạch, hãy dừng lại, cập nhật kế hoạch rồi mới tiếp tục.

Chiến Lược Subagent

Sử dụng các Subagent để giữ ngữ cảnh chính sạch sẽ và xử lý song song.

• Nhiệm vụ của Subagent: Khám phá kho lưu trữ (repo), tìm kiếm mẫu code, nghiên cứu sự phụ thuộc (dependency).
• Mỗi Subagent chỉ nên có một mục tiêu tập trung và một kết quả cụ thể (Ví dụ: “Tìm nơi triển khai X và liệt kê các file” thay vì “nhìn quanh xem sao”).

Chuyển Giao Tăng Dần

• Ưu tiên các lát cắt dọc mỏng (thin vertical slices) thay vì thay đổi toàn bộ một lúc (“big-bang”).
• Quy trình: Thực hiện → Test → Xác minh → Mở rộng.
• Sử dụng feature flags (cờ tính năng) hoặc cấu hình để ẩn các thay đổi chưa hoàn thiện

Vòng Lặp Tự Cải Thiện

• Sau mỗi sai lầm hoặc sự sửa chữa từ người dùng, AI cần thêm một mục vào file tasks/lessons.md ghi lại: Chế độ lỗi, dấu hiệu nhận biết và quy tắc phòng ngừa.
• File này cần được xem lại trước khi bắt đầu phiên làm việc mới.

3. Quản Lý Tác Vụ Dựa Trên File

Thay vì giữ mọi thứ trong bộ nhớ tạm, hãy yêu cầu AI quản lý công việc qua file để dễ dàng kiểm tra:

• tasks/todo.md: Viết checklist cho mọi công việc.
• Định nghĩa thành công: Ghi rõ tiêu chí chấp nhận (Acceptance Criteria).
• Theo dõi tiến độ: Đánh dấu hoàn thành từng mục, chỉ giữ một mục “đang thực hiện” (in progress) tại một thời điểm.
• Ghi chú kết quả: Thêm phần “Results” ngắn gọn về những gì đã thay đổi và cách xác minh.

4. Giao Tiếp Và Hợp Tác Với Người Dùng

AI cần giao tiếp hiệu quả, tránh làm phiền người dùng bằng những câu hỏi thừa thãi:

• Ngắn gọn, Tín hiệu cao: Tập trung vào kết quả và tác động. Dẫn chứng bằng đường dẫn file, lệnh cụ thể.
• Chỉ hỏi khi bị chặn (Blocked): Hỏi chính xác một câu hỏi nhắm đúng mục tiêu, kèm theo đề xuất mặc định và giải thích điều gì sẽ thay đổi dựa trên câu trả lời.
• Câu chuyện xác minh (Verification Story): Luôn báo cáo những gì đã chạy (test/lint/build) và kết quả. Nếu không chạy được, hãy cung cấp lệnh để người dùng tự chạy.

5. Xử Lý Lỗi Và Phục Hồi

Quy tắc quan trọng nhất là “Stop-the-Line” (Dừng dây chuyền):

• Nếu gặp lỗi bất ngờ (test fail, build lỗi), dừng ngay việc thêm tính năng.
• Bảo tồn bằng chứng (log lỗi), quay lại chẩn đoán và lập lại kế hoạch.

Danh sách kiểm tra khi xử lý lỗi:

1. Tái hiện lỗi (Reproduce).
2. Khoanh vùng lỗi (Localize – UI, API hay DB?).
3. Thu nhỏ trường hợp lỗi (Reduce).
4. Sửa nguyên nhân gốc rễ (Fix root cause).
5. Bảo vệ bằng test hồi quy (Guard).
6. Xác minh tổng thể (Verify).

6. Các Thực Hành Kỹ Thuật Tốt Nhất

Để đảm bảo chất lượng code, AI cần tuân thủ:

• Kiểm thử: Thêm bài test nhỏ nhất có thể để bắt được lỗi. Ưu tiên Unit test cho logic thuần túy, Integration test cho ranh giới DB/Network.
• An toàn kiểu dữ liệu (Type Safety): Tránh dùng any hoặc bỏ qua lỗi (ignore) trừ khi bắt buộc.
• Bảo mật: Tuyệt đối không đưa bí mật (secrets) vào code hay log. Luôn coi đầu vào của người dùng là không tin cậy (untrusted).
• Phụ thuộc (Dependencies): Không thêm thư viện mới trừ khi stack hiện tại không giải quyết được và lợi ích là rõ ràng.

Kết Luận

Việc áp dụng bộ quy tắc này biến một AI Coding Agent từ một công cụ hỗ trợ đơn giản thành một “kỹ sư phần mềm ảo” có kỷ luật. Đối với người dùng, việc yêu cầu Agent tuân thủ cấu trúc file tasks/todo.md hay tasks/lessons.md là cách tốt nhất để kiểm soát chất lượng đầu ra và duy trì sự ổn định cho dự án.