Cách dùng agent.md để giảm lỗi lặp lại trong code do LLM tạo

Vì sao cần một file hướng dẫn cho agent

Fabien Sanglard thử dùng LLM để viết code từ giữa năm 2025 nhưng kết quả Rust ban đầu không compile. Đến đầu năm 2026, model đã viết được cấu trúc dữ liệu phức tạp và tìm ra bug khó trong phần IOCP của một crate, nhưng code tạo ra vẫn thiếu cấu trúc, comment và tiêu chuẩn production.

Agentic IDE giúp anh review phần code đang staged và yêu cầu sửa từng điểm. Chất lượng tăng lên, nhưng cùng một góp ý phải lặp trong mỗi session: tránh magic number, giảm indentation, thêm comment ngắn, giữ boundary của abstraction. Sanglard chuyển các yêu cầu lặp lại đó vào agent.md ở root repository để coding harness nạp vào prompt khi bắt đầu phiên.

Các rule chính trong agent.md

File mẫu không cố mô tả toàn bộ codebase. Nó tập trung vào những preference dễ kiểm tra:

• viết ngắn gọn, tránh superlative và lời khen;
• tách magic number hoặc string có ý nghĩa thành constant hay enum;
• dùng early return để giảm indentation;
• dùng enum thay cho boolean parameter;
• thêm khoảng trắng giữa các block logic;
• comment ngắn về việc code làm gì và vì sao;
• không mở rộng visibility nếu chưa được phê duyệt;
• giữ low-level mechanics sau một abstraction rõ ràng;
• không sửa phần code ngoài phạm vi feature;
• chỉ cho mỗi layer gọi layer ngay bên dưới;
• viết failing test trước khi sửa bug;
• giữ commit subject ngắn, ở imperative mood và giải thích lý do trong body.

Các rule này phản ánh một codebase và một maintainer cụ thể. Dev không nên copy nguyên danh sách rồi coi đó là standard chung. Ví dụ giới hạn tên hàm dưới 30 ký tự hoặc luôn dùng brace có thể xung đột với linter và convention hiện hữu.

Biến review lặp lại thành rule có phạm vi

Cách áp dụng thực dụng là bắt đầu từ failure thật:

1. Khi phải viết cùng một review comment lần thứ hai, ghi lại pattern.
2. Nêu scope: ngôn ngữ, thư mục hoặc loại thay đổi nào chịu rule.
3. Viết lý do và một ví dụ ngắn nếu rule dễ hiểu sai.
4. Gắn rule với checker sẵn có khi có thể, thay vì chỉ dùng prose.
5. Xóa hoặc thu hẹp rule nếu nó tạo diff thừa mà không ngăn defect.

Một instruction file quá dài có thể tự làm giảm hiệu quả. Rule nên đủ cụ thể để kiểm tra và đủ ngắn để model tìm thấy khi context lớn.

Hai cách giảm context dilution

Sanglard mô tả hiện tượng model chú ý kém hơn đến instruction nằm giữa context dài. Anh dùng hai biện pháp:

• mở session mới cho từng feature để giữ context ngắn;
• yêu cầu harness nạp lại agent.md khi chất lượng code bắt đầu giảm.

Đây là quan sát vận hành cá nhân, không phải bảo đảm rằng mọi model hoặc harness sẽ phản ứng giống nhau. Team nên đo bằng lỗi review, số vòng sửa và test outcome trên chính repo của mình.

File hướng dẫn không thay thế review

Tác giả nhấn mạnh rằng LLM vẫn hallucinate và anh vẫn phải đọc, kiểm chứng, lặp lại. agent.md chỉ chuyển phần nhắc style lặp đi lặp lại ra khỏi cuộc hội thoại, để review tập trung hơn vào architecture và design.

Một setup tốt nên kết hợp ba lớp:

• instruction ngắn cho convention và boundary;
• tool tự động cho format, lint, type và test;
• human review cho trade-off kiến trúc mà rule không diễn đạt hết.

Nếu một yêu cầu có thể thành test hoặc lint rule, checker thường đáng tin hơn prompt. Phần nên ở lại agent.md là intent, phạm vi và những quyết định mà code hiện tại chưa thể tự chứng minh.