Bài 7 — Cấu hình ngữ cảnh & vận hành an toàn

Công cụ mạnh mà không cấu hình ngữ cảnh và không có rào an toàn thì tạo ra nợ kỹ thuật nhanh hơn cả tạo ra giá trị. Bài này là phần "vận hành".

Vì sao ngữ cảnh quyết định chất lượng

Agent chỉ tốt bằng thông tin nó có. Cùng một model, một agent biết "dự án dùng pytest, đặt tên theo snake_case, không được sửa thư mục legacy/" sẽ cho kết quả khớp quy ước hơn hẳn agent không biết gì.

Các cách cung cấp ngữ cảnh

• File hướng dẫn dự án: nhiều công cụ đọc một file quy ước ở gốc repo (ví dụ mô tả stack, lệnh test, quy ước commit, vùng cấm sửa). Viết một lần, agent dùng mọi lần.
• Chọn file đúng trọng tâm: dùng @file (Cursor) hoặc thêm file vào phiên (Aider) thay vì để agent tự đoán.
• Rule/ignore: loại trừ file build, secret, dữ liệu lớn khỏi ngữ cảnh.

# Ví dụ nội dung file hướng dẫn dự án
Stack: Python 3.11, FastAPI, pytest.
Lệnh test: pytest -q
FormAT: black + ruff.
Commit: Conventional Commits.
KHÔNG sửa: thư mục legacy/, file migrations đã chạy.

Vận hành an toàn: rào chắn bắt buộc

• Version control là bắt buộc: luôn làm trên nhánh riêng, commit sạch trước khi chạy agent.
• Kiểm soát quyền chạy lệnh: với agent CLI/tự chủ, cân nhắc chế độ hỏi trước khi chạy lệnh nhạy cảm (xóa, push, deploy).
• Bảo vệ secret: đảm bảo .env, khóa API nằm trong ignore; không để agent đọc/ghi bí mật.
• Review là chốt chặn cuối: đọc git diff hoặc PR trước khi merge, như review một junior dev.

Quy trình vận hành mẫu

• Tạo nhánh: git checkout -b feature/x.
• Đảm bảo working tree sạch.
• Giao task kèm tiêu chí thành công.
• Cho agent chạy; theo dõi lệnh nó gọi.
• git diff toàn bộ thay đổi.
• Chạy lại test/lint độc lập để xác nhận.
• Mở PR, review, rồi mới merge.

Khung tư duy: Blast Radius (bán kính ảnh hưởng)

Trước khi giao việc, hỏi: nếu agent làm sai hoàn toàn, hậu quả lan tới đâu?

• Bán kính nhỏ (nhánh riêng, có test, dễ rollback) -> cho tự chủ cao.
• Bán kính lớn (chạm thanh toán, migration, prod) -> giảm tự chủ, tăng review, hoặc không giao cho agent.

Checklist an toàn trước khi chạy agent

• [ ] Đang ở nhánh riêng, working tree sạch?
• [ ] Secret đã nằm ngoài ngữ cảnh (ignore)?
• [ ] Có file hướng dẫn/quy ước cho dự án?
• [ ] Có tiêu chí thành công + lệnh kiểm chứng?
• [ ] Đã xác định vùng cấm sửa?
• [ ] Có kế hoạch review diff trước khi merge?

Sai lầm thường gặp

• Chạy agent thẳng trên nhánh main/prod: một lệnh sai là sự cố thật.
• Không viết file quy ước: agent tạo code không khớp chuẩn team, review mệt hơn tự viết.
• Cho phép chạy mọi lệnh không kiểm soát: rủi ro với lệnh phá hủy (rm, drop, push --force).
• Để secret trong ngữ cảnh: nguy cơ rò rỉ khóa API/mật khẩu.
• Bỏ review vì "AI chắc đúng": đây là nguồn bug âm thầm nguy hiểm nhất.

<!--les-append-->

File hướng dẫn dự án: viết gì để nó thật sự hữu ích

Phần lớn file hướng dẫn được viết quá chung ("code phải sạch, dễ đọc") nên không thay đổi gì. File hữu ích chứa những thứ agent không thể suy ra từ code:

Mục cuối là mục ít ai viết và có giá trị cao nhất: mỗi lần agent mắc cùng một lỗi lần thứ hai, hãy viết nó vào file. Sau vài tuần, file này trở thành tài sản — và nó cũng hữu ích cho người mới vào đội, không chỉ cho AI.

Nguyên tắc chọn ngữ cảnh: ít mà đúng

Trực giác sai phổ biến: đưa càng nhiều file càng tốt. Thực tế, ngữ cảnh quá rộng làm chất lượng giảm — tín hiệu quan trọng bị loãng giữa hàng nghìn dòng không liên quan.

Ba file thường là đủ cho hầu hết việc:

• File cần sửa
• Một file mẫu làm việc tương tự (đây là file quan trọng nhất)
• File test liên quan

File số 2 là đòn bẩy lớn nhất và hay bị bỏ. Nói "làm giống file này" hiệu quả hơn ba đoạn mô tả quy ước bằng lời.

Rào an toàn, theo thứ tự quan trọng

• Luôn làm trên nhánh riêng. Rào quan trọng nhất và rẻ nhất.
• Commit sạch trước khi giao việc. Đây là nút hoàn tác duy nhất đáng tin.
• Không cho quyền vào production. Không khoá API production, không quyền ghi vào database thật.
• Đọc diff trước khi merge, mọi lần. Không có ngoại lệ cho "việc nhỏ".
• Giữ diff nhỏ để điều 4 khả thi. Điều 4 và 5 đi cùng nhau: diff 800 dòng nghĩa là bạn sẽ không thực sự đọc.

Cách nợ kỹ thuật hình thành với agent

Nó không hình thành từ code xấu — code agent viết thường trông ổn. Nó hình thành từ ba chỗ:

• Trùng lặp. Agent không biết dự án đã có hàm làm việc đó, nên viết hàm mới. Sau sáu tháng bạn có bốn hàm định dạng ngày tháng.
• Không nhất quán. Mỗi phiên agent chọn một cách xử lý lỗi khác.
• Lý do bị mất. Không ai biết vì sao code đó ở đó.

Cách chặn: file hướng dẫn cho hai vấn đề đầu, và hai dòng lý do trong mỗi PR cho vấn đề thứ ba.

Làm ngay

Viết file hướng dẫn cho dự án của bạn với năm mục trong bảng đầu — mất khoảng 30 phút. Rồi mỗi lần agent mắc lỗi lặp lại, thêm một dòng vào mục "cạm bẫy đã biết". Đó là khoản đầu tư có lợi tức cao nhất trong toàn bộ khoá này. <!--/les-append-->