Các phương pháp tốt nhất (Best Practices)
Coding agent (Codex, OpenCode, Gemini CLI, Hermes, ...) không chỉ sinh code mà còn tự đọc file, chạy lệnh và sửa dự án. Các nguyên tắc dưới đây giúp agent làm đúng việc, và giúp đội không tốn budget vô ích.
1. Viết file hướng dẫn cho agent
Đặt một file hướng dẫn ở thư mục gốc dự án. Agent đọc file này ở đầu mỗi phiên, nên bạn không phải nhắc lại cùng một điều.
| Công cụ | Tên file |
|---|---|
| Codex, OpenCode, Hermes, Cursor và nhiều công cụ khác | AGENTS.md |
| Gemini CLI, Antigravity CLI | GEMINI.md |
Nội dung nên ngắn, chỉ ghi những gì agent không tự suy ra được:
# Dự án: ứng dụng đặt cà phê
- Backend: FastAPI (thư mục api/), frontend: React + Vite (thư mục web/).
- Cài đặt: `uv sync` và `npm install --prefix web`.
- Chạy test: `uv run pytest`. Chạy lint: `uv run ruff check .`.
- Không sửa thư mục migrations/ bằng tay.
- API key đọc từ biến môi trường, không bao giờ ghi vào code.
Khi agent lặp lại một lỗi, thêm một dòng vào file này thay vì nhắc trong chat.
2. Lên kế hoạch trước, code sau
Với tác vụ lớn hơn vài dòng, yêu cầu agent đọc code và đề xuất kế hoạch trước khi sửa. Nhiều công cụ có sẵn chế độ chỉ đọc cho việc này, ví dụ chế độ Plan của OpenCode (nhấn Tab).
- Đọc kế hoạch, sửa chỗ hiểu sai, rồi mới cho agent làm.
- Chia việc thành các bước nhỏ, mỗi bước kiểm tra được. "Thêm API tạo đơn hàng kèm test" tốt hơn "Làm cả ứng dụng đặt cà phê".
- Một phiên cho một việc. Khi chuyển sang việc khác, mở phiên mới để ngữ cảnh gọn và rẻ hơn.
3. Cho agent đúng ngữ cảnh
- Chỉ đích danh file liên quan. Hầu hết công cụ cho gõ
@để đính kèm file, ví dụ "Sửa lỗi trong @api/orders.py, xem cách làm ở @api/users.py". - Dán nguyên thông báo lỗi và lệnh đã chạy, thay vì mô tả lại.
- Nói rõ tiêu chí hoàn thành: "Xong khi
uv run pytestchạy qua hết".
4. Đọc từng quyền agent xin
Trước khi sửa file hay chạy lệnh, agent hiện diff hoặc câu lệnh và hỏi quyền. Đây là chốt an toàn quan trọng nhất.
- Đọc diff trước khi đồng ý. Để ý file bị xoá, thư mục lạ, thay đổi ngoài phạm vi yêu cầu.
- Cẩn thận với lệnh xoá, lệnh
git push, lệnh cài gói, lệnh gọi mạng. - Chỉ chọn "luôn cho phép" với lệnh chỉ đọc hoặc lệnh bạn chạy hằng ngày (chạy test, lint).
- Nội dung agent đọc từ web hoặc file lạ có thể chứa lệnh cài cắm. Nếu agent bỗng muốn làm việc bạn không yêu cầu, từ chối và hỏi lại.
5. Kiểm chứng bằng test, không bằng cảm giác
- Yêu cầu agent viết hoặc chạy test cho mọi thay đổi, và tự sửa đến khi test qua.
- Tự chạy ứng dụng và thử luồng chính trước khi coi là xong.
- Với lỗi: yêu cầu agent viết test tái hiện lỗi trước, rồi mới sửa.
6. Dùng git làm điểm lưu
- Commit trước khi giao việc lớn cho agent, để quay lại được nếu agent làm hỏng.
- Commit nhỏ, mỗi commit một thay đổi có ý nghĩa. Dễ xem lại, dễ hoàn tác.
- Làm việc trên nhánh riêng, không để agent sửa thẳng nhánh chính.
7. Chọn model theo độ khó, theo dõi budget
Mỗi lượt agent đọc file và gọi tool đều tốn token, và một phiên dài có thể tốn gấp nhiều lần một câu hỏi chat.
| Tình huống | Model gợi ý |
|---|---|
| Việc lặt vặt, sửa nhỏ, chạy thử cấu hình | deepseek-flash (rẻ nhất) |
| Phần lớn công việc hằng ngày | gpt-6-luna, gemini-3.5-flash |
| Thiết kế, refactor lớn, lỗi khó | gpt-6.1-sol, deepseek-v4-pro |
- Chỉ đổi sang model đắt khi model rẻ bí thật sự.
- Theo dõi chi tiêu của đội thường xuyên, xem Kiểm tra chi tiêu. Giá từng model ở Bảng giá model.
- Hết budget, mọi công cụ đều báo
429 Budget has been exceeded.
8. Giữ bí mật cho API key
- Đặt key trong biến môi trường (
THUCCHIEN_API_KEY,GEMINI_API_KEY), không ghi vào code hay file cấu hình được commit. - Thêm
.envvào.gitignore. Kiểm tragit difftrước khi commit. - Không dán key vào chat với agent, không chụp màn hình có key.
- Lộ key thì báo ban tổ chức để thu hồi ngay: ai có key đều tiêu được budget của đội.
9. Bạn vẫn là người chịu trách nhiệm
Agent làm nhanh, nhưng không hiểu mục tiêu sản phẩm bằng bạn. Đọc hiểu code nó viết, nhất là phần xử lý dữ liệu người dùng, xác thực và thanh toán. Khi không hiểu một đoạn code, hỏi agent giải thích trước khi chấp nhận.