Nếu file AGENTS.md có "mùi", code của bạn sẽ không đạt hiệu quả như kỳ vọng

Nếu file cấu hình của tác nhân AI (AI agent) có "mùi", có lẽ đã đến lúc bạn cần dọn dẹp lại các chỉ dẫn của mình. Trong kỹ thuật phần mềm, các mẫu code rủi ro hoặc cấu trúc kém thường được gọi là "code smells" (mùi code). Hóa ra, các chỉ thị trong file cấu hình của coding agents cũng có thể gặp vấn đề tương tự, dẫn đến việc lãng phí token và chất lượng đầu ra kém hơn mong đợi.

Các coding agent phụ thuộc vào các file cấu hình để tóm tắt hành vi mong đợi. Các file này thường được viết bằng định dạng Markdown và đặt tên là CLAUDE.md (đối với các mô hình của Anthropic) hoặc AGENTS.md (đối với hầu hết các nền tảng còn lại).

Vấn đề của việc chỉ dẫn quá chi tiết

Anthropic từng khuyên các nhà phát triển không nên viết quá 200 dòng văn bản trong các file này. Lý do là vì các file dài hơn sẽ tiêu thụ ngữ cảnh của mô hình (model context) và có thể làm giảm tính mạch lạc của mô hình đó.

Tuy nhiên, thực tế cho thấy các nhà phát triển thường mắc phải những sai lầm phổ biến khi thiết lập các file này.

Nghiên cứu về "mùi" cấu hình

Các nhà nghiên cứu thuộc Khoa Khoa học Máy tính của Viện Liên bang Minas Gerais (Brazil) gần đây đã phân tích 532.000 file để xây dựng và đánh giá một tập dữ liệu từ 100 dự án mã nguồn mở phổ biến chứa file AGENTS.md hoặc CLAUDE.md.

Kết quả cho thấy các "mùi" cấu hình (configuration smells) đang rất phổ biến. Các tác giả nghiên cứu nhận định: "Kết quả của chúng tôi cho thấy các mùi cấu hình lan rộng khắp nơi."

Ba loại mùi phổ biến nhất bao gồm:

• Lint Leakage (Rò rỉ Lint): Đây là mùi phổ biến nhất, ảnh hưởng đến 62% các file. Nó xảy ra khi các chỉ dẫn cho agent lặp lại các quy tắc đã được thực thi bởi các công cụ linting, trình kiểm tra định dạng hoặc công cụ phân tích tĩnh. Các quy tắc trùng lặp này lãng phí token bằng cách làm gánh nặng cho mô hình với những hướng dẫn cho một nhiệm vụ đã được xử lý đáng tin cậy bởi các công cụ lập trình.
• Context Bloat (Phình ngữ cảnh): Ảnh hưởng đến 42% các file. Đây là xu hướng chỉ định quá chi tiết hành vi của coding agent. Các tác giả nhận xét rằng: "Các file cấu hình phình to làm tăng tiêu thụ token, nâng cao chi phí và giảm khả năng hiển thị của các chỉ dẫn quan trọng."
• Skill Leakage (Rò rỉ kỹ năng): Ảnh hưởng đến 35% các file. Điều này xảy ra khi các công cụ hoặc phương pháp ít được sử dụng lại được thêm vào file AGENTS.md, vốn được tải trong mọi phiên làm việc của agent. Các chỉ dẫn này tốt hơn nên được đặt trong một file kỹ năng riêng (ví dụ: SKILLs.md) và chỉ tải khi cần thiết.

Các "mùi" khác cần lưu ý

Ngoài ba loại trên, nghiên cứu còn chỉ ra một số vấn đề khác:

• Blind References (Tham chiếu mù): Xảy ra khi file cấu hình tham chiếu đến các tài liệu bên ngoài (ví dụ: qua URL) mà không giải thích khi nào tài liệu đó trở nên liên quan.
• Init Fossilization (Hóa thạch khởi tạo): Các chi tiết cấu hình được thiết lập khi khởi tạo dự án nhưng không còn phù hợp nữa.
• Conflicting Instructions (Chỉ dẫn xung đột): Xảy ra khi các chỉ thị cho agent mâu thuẫn với nhau.

Nghiên cứu phát hiện rằng 91 trong số 100 file AGENTS.md được kiểm tra chứa ít nhất một trong số sáu mùi này.

Bài học: Ít hơn là nhiều hơn

Thông điệp cốt lõi ở đây là nguyên tắc "ít hơn là nhiều hơn" khi nói đến các file cấu hình cho coding agent. Có thể việc không có file cấu hình nào còn tốt hơn việc có một file cấu hình tồi.

Tương tự, một nghiên cứu trước đây của ETH Zurich cũng đã xem xét tác động của các file ngữ cảnh đối với các agent. Họ nhận thấy rằng các chỉ dẫn do nhà phát triển tạo ra làm tăng chi phí nhưng chỉ cải thiện hiệu suất code khoảng 4%, trong khi các chỉ dẫn do LLM tạo ra thậm chí còn có tác động tiêu cực nhỏ (3%) đến code do agent tạo ra.

Họ kết luận rằng: "Các yêu cầu không cần thiết từ các file ngữ cảnh làm cho nhiệm vụ trở nên khó khăn hơn, và các file ngữ cảnh do con người viết chỉ nên mô tả các yêu cầu tối thiểu."