Quy trình đưa AI coding agent vào một tác vụ phát triển phần mềm

AI coding agent không phải công cụ "giao việc xong ngồi chờ kết quả". Nếu không có quy trình rõ ràng, agent dễ biến thành nguồn gây nợ kỹ thuật: sửa sai phạm vi, viết test chạy đạt nhưng sai nghiệp vụ, hoặc đụng chạm đến những phần code không ai yêu cầu.

Bài này trình bày một quy trình thực tế để đưa agent vào một tác vụ phát triển phần mềm cụ thể. Ví dụ xuyên suốt: thêm tính năng lọc danh sách test case theo trạng thái (passed, failed, pending, blocked) trong một công cụ QC nội bộ. Mỗi bước gồm bốn phần: đầu vào, việc agent làm, việc con người kiểm tra, và đầu ra mong đợi.

software development workflow

1. Chọn tác vụ phù hợp cho agent

Không phải tác vụ nào cũng nên giao cho agent. Tác vụ đầu tiên nên đủ nhỏ, đủ cô lập, và có tiêu chí đúng/sai rõ ràng.

Ví dụ trong bài: thêm bộ lọc trạng thái vào danh sách test case. Tính năng này:

Chạm đến một module xác định (giao diện danh sách + API trả danh sách).
Có đầu vào/đầu ra rõ: query param status, danh sách trả về đã lọc.
Dễ viết test: kiểm tra số lượng item, giá trị trạng thái, trường hợp lọc kết hợp.

Đầu vào: mô tả ngắn tính năng, phạm vi module, ràng buộc hiện tại.

Việc agent làm: đề xuất cách triển khai, liệt kê file có thể đụng đến, ước tính test cần viết.

Người kiểm tra: xác nhận phạm vi có hợp lý không, agent có đề xuất đụng đến module khác không.

Đầu ra mong đợi: một tác vụ đã được cắt nhỏ, có ranh giới rõ, sẵn sàng để viết yêu cầu chi tiết.

2. Xác định yêu cầu và tiêu chí hoàn thành

Yêu cầu mơ hồ là nguyên nhân phổ biến nhất khiến agent làm sai. Cần viết rõ: chức năng gì, áp dụng ở đâu, hành vi khi không có dữ liệu, và tiêu chí tối thiểu để coi là xong.

Ví dụ trong bài:

Người dùng có thể chọn một hoặc nhiều trạng thái từ dropdown.
API nhận query param status dạng comma-separated, ví dụ status=passed,failed.
Nếu không chọn trạng thái nào, danh sách trả về toàn bộ.
UI hiển thị badge trạng thái tương ứng.
Có test unit cho API, test component cho UI.

Đầu vào: user story hoặc ticket đã được phân rõ, kèm mockup hoặc mô tả giao diện.

Việc agent làm: chuyển yêu cầu thành danh sách sub-task, đề xuất cấu trúc test.

Người kiểm tra: đọc lại danh sách sub-task, đảm bảo không thiếu trường hợp biên (lọc kết hợp, trạng thái không hợp lệ, danh sách rỗng).

Đầu ra mong đợi: ticket/task list với acceptance criteria cụ thể, có thể đo lường được.

3. Chuẩn bị repo, môi trường và quyền truy cập

Agent cần chạy trong một sandbox có giới hạn. Không nên đưa agent vào repo production với quyền write trực tiếp.

Các bước chuẩn bị:

Tạo branch riêng, ví dụ feature/filter-testcase-by-status.
Cấu hình agent chỉ đọc/ghi trong repo đã clone, không được truy cập vào secret hoặc database production.
Cung cấp tài liệu nội bộ: coding convention, cấu trúc module, cách chạy test.
Chuẩn bị dữ liệu test giả lập: danh sách test case với các trạng thái khác nhau.

Đầu vào: repo đã clone, branch sạch, tài liệu hướng dẫn, dữ liệu test.

Việc agent làm: đọc codebase, xác định file liên quan, kiểm tra môi trường chạy test.

Người kiểm tra: xác nhận agent không đọc được file nhạy cảm (.env, key, config production), xác nhận test chạy được trên local.

Đầu ra mong đợi: môi trường sẵn sàng, agent biết cấu trúc code, test baseline chạy xanh.

4. Giao việc cho agent và để agent lập kế hoạch

Giao việc cho agent giống như giao việc cho một dev junior: càng cụ thể càng tốt. Yêu cầu agent trả lại kế hoạch trước khi sửa code.

Prompt mẫu:

"Trên branch feature/filter-testcase-by-status, hãy thêm tính năng lọc danh sách test case theo trạng thái. Phạm vi: component TestCaseList, API endpoint /api/test-cases, và test tương ứng. Trước tiên, liệt kê các file cần sửa, các test cần viết, và các rủi ro có thể gặp. Đợi tôi phê duyệt kế hoạch trước khi sửa code."

Đầu vào: prompt chi tiết, phạm vi rõ ràng, yêu cầu trả kế hoạch trước.

Việc agent làm: phân tích code, đề xuất danh sách file thay đổi, test plan, rủi ro.

Người kiểm tra: duyệt kế hoạch, từ chối nếu agent đề xuất đụng đến kiến trúc hoặc module ngoài phạm vi.

Đầu ra mong đợi: kế hoạch được phê duyệt, agent được phép bắt đầu sửa code.

5. Agent sửa code và chạy test

Đây là giai đoạn agent thực hiện thay đổi. Người giám sát không nên để agent tự ý chạy lệnh nguy hiểm hoặc tự merge.

Ví dụ trong bài:

Agent sửa API để nhận param status và lọc trong query.
Agent thêm dropdown trên UI, cập nhật state khi người dùng chọn lọc.
Agent viết unit test cho từng trạng thái và trường hợp kết hợp.

Đầu vào: kế hoạch đã duyệt, quyền write trên branch feature.

Việc agent làm: sửa code theo kế hoạch, chạy test, sửa lỗi test nếu fail.

Người kiểm tra: theo dõi diff tạm thời, đảm bảo agent không sửa ngoài phạm vi, không đọc dữ liệu nhạy cảm, không chạy lệnh deploy.

Đầu ra mong đợi: code đã sửa, test chạy xanh trên local/agent environment.

code review diff

6. Review diff và quyết định merge

Dù test có xanh, người vẫn phải review. Agent có thể viết test đạt nhưng sai nghiệp vụ, hoặc giải quyết vấn đề bằng cách shortcut.

Các điểm cần review:

Diff có đúng phạm vi đã duyệt không?
Test có kiểm tra đúng nghiệp vụ không, hay chỉ kiểm tra "hàm trả về đúng kiểu dữ liệu"?
Có đoạn code lặp lại, hardcode, hoặc bỏ qua convention không?
Có thay đổi nào ảnh hưởng đến tính năng khác không?

Đầu vào: pull request với diff, kết quả test, mô tả thay đổi.

Việc agent làm: (nếu được yêu cầu) giải thích từng thay đổi, trả lời câu hỏi review.

Người kiểm tra: review từng dòng, chạy thử thủ công nếu cần, yêu cầu sửa nếu phát hiện lỗi.

Đầu ra mong đợi: PR được approve, merge bởi người, không phải bởi agent.

7. Ranh giới quyền hạn: agent không được tự làm gì

Cần phân biệt rõ việc agent được làm và việc bắt buộc phải có người.

Agent KHÔNG ĐƯỢC tự ý:

Thay đổi kiến trúc hệ thống, refactor module ngoài phạm vi.
Sửa code ngoài ticket đã giao.
Đọc file .env, secret, database production, log chứa dữ liệu người dùng.
Tự merge pull request hoặc deploy lên môi trường production/staging.
Chạy lệnh xóa dữ liệu, reset database, hoặc thay đổi quyền truy cập.

Những việc này phải do người thực hiện hoặc phê duyệt. Agent chỉ là công cụ hỗ trợ trong sandbox đã giới hạn.

8. Checklist trước khi giao việc và trước khi merge

Trước khi giao việc

Tác vụ đã được cắt nhỏ, phạm vi rõ ràng.
Có acceptance criteria cụ thể, có thể test được.
Repo đã ở branch riêng, agent không có quyền write lên main.
Dữ liệu nhạy cảm đã được loại khỏi môi trường agent.
Coding convention và hướng dẫn chạy test đã được cung cấp.
Có người được chỉ định để review kết quả.

Trước khi merge

Diff chỉ chứa thay đổi trong phạm vi đã duyệt.
Test chạy xanh và kiểm tra đúng nghiệp vụ.
Không có hardcode, không vi phạm convention.
Đã kiểm tra trường hợp biên: danh sách rỗng, lọc kết hợp, giá trị không hợp lệ.
Không có thay đổi ngầm đối với module khác.
Merge do người thực hiện, không phải agent.

project planning checklist

9. Các lỗi thường gặp

Yêu cầu mơ hồ

"Thêm bộ lọc cho danh sách test case" là chưa đủ. Agent có thể hiểu sai: lọc ở frontend, lọc ở backend, hay lọc trên toàn bộ hệ thống? Cần chỉ rõ vị trí, đầu vào, đầu ra, và hành vi mặc định.

Test chạy đạt nhưng sai nghiệp vụ

Agent có thể viết test kiểm tra "API trả về mảng" nhưng không kiểm tra mảng đó đã được lọc đúng trạng thái chưa. Reviewer phải đọc kỹ nội dung test, không chỉ nhìn màu xanh.

Agent sửa quá nhiều file

Khi gặp lỗi compile hoặc test fail, agent đôi khi đụng đến nhiều file ngoài phạm vi để "làm cho nó chạy". Nếu diff vượt quá kế hoạch, cần dừng lại, xem xét lại nguyên nhân, và quyết định có mở rộng phạm vi hay không.

Bỏ qua dữ liệu nhạy cảm

Agent có thể đọc log, database, hoặc file config để "hiểu ngữ cảnh". Cần giới hạn quyền truy cập ngay từ đầu, không chỉ dựa vào prompt yêu cầu "đừng đọc".

10. Kết luận

Đưa AI coding agent vào workflow phát triển phần mềm không khó, nhưng đòi hỏi kỷ luật. Quy trình đúng là: chọn tác vụ nhỏ, viết yêu cầu rõ, chuẩn bị môi trường an toàn, giao việc có kiểm soát, review diff kỹ, và luôn để người quyết định merge.

Agent giúp tăng tốc việc viết code và test, nhưng không thay thế trách nhiệm của người. Ranh giới quyền hạn, checklist, và review con người vẫn là những lớp bảo vệ quan trọng nhất.