Mỗi lần bắt đầu việc, AI agent gần như phải làm quen dự án từ đầu. Một cuốn sổ tay ngắn, viết đúng chỗ, giúp nó đỡ đoán mò. Viết gì, bỏ gì, giữ cho đúng ra sao?
Tóm lại: chỉ viết điều AI không tự suy ra được, ngắn và có lý do.
Lưu ý: hai nghiên cứu còn mới và đo hai việc khác nhau. Mình mới đọc phần tóm tắt, chưa đọc kỹ cả hai bài gốc.
AI agent không nhớ gì về dự án của bạn mỗi lần bắt đầu. Một tệp ghi sẵn những điều đó, giống cuốn sổ tay đưa cho đồng nghiệp mới.
Mỗi công cụ từng đọc một tên riêng. AGENTS.md là tên chung được đề xuất khoảng tháng 5/2025.
Đừng coi mọi công cụ đều đọc tên AGENTS.md. Dùng tên mà công cụ của bạn đọc, như dự án này dùng CLAUDE.md.
| Nghiên cứu thứ nhất | Nghiên cứu thứ hai | |
|---|---|---|
| Quy mô | 10 kho mã, 124 PR thật | Bốn agent, hai bộ đề |
| Kết quả chính | Thời gian chạy trung vị giảm khoảng 28,6%, token đầu ra giảm khoảng 16,6% | Chi phí và số bước tăng; tệp do AI sinh hơi tiêu cực, do người viết hơi tích cực |
| Chính tác giả nói | Bước đầu, chưa phải kết luận | Chênh lệch về thành công nhỏ, không có ý nghĩa thống kê |
Dòng trong tệp được đọc ở mỗi lần làm việc. Dòng thừa là chi phí thật.
Dùng lệnh /init tạo bản đầu, rồi tự tay cắt cho gọn.
Chạy cùng một việc có và không có tệp, so thời gian và số lần sửa.
AI có tự suy ra được điều này từ code không? Nếu có thì đừng viết. Nếu không, mà quan trọng, hãy viết.
| Tự suy ra được: đừng viết | Không suy ra được: nên viết |
|---|---|
| "Dự án dùng JavaScript" | Lệnh chạy test đúng và nó chạy gì |
| "Viết code sạch" | "Chữ cho người dùng bằng tiếng Việt, tên hàm bằng tiếng Anh" |
| Danh sách mọi tệp | Quyết định có chủ ý: dùng X, không dùng Y vì Z |
| Lời khuyên chung chung | Điều cấm kèm lý do |
Cài, chạy, build, test, và cả lệnh chạy một test riêng.
Một, hai đoạn: các phần nối với nhau thế nào và vì sao.
Đặt tên, ngôn ngữ của chữ hiển thị, cách xử lý lỗi, kiểu commit.
Lỗi đã từng xảy ra. Mỗi lỗi lặp lại là một dòng.
Thư mục, lệnh, hành động không được làm nếu chưa hỏi.
Có test, đã chạy kiểm tra, có ảnh chụp.
Đọc lướt được trong chưa đầy một phút.
Là gì, lệnh, kiến trúc, mô hình nội dung, kỹ năng.
Nhỏ hơn nhiều so với bốn tệp kỹ năng cộng lại.
Nằm trong bốn tệp kỹ năng riêng, tệp chính chỉ trỏ tới.
Tệp chính ngắn, chi tiết tách riêng.
Thêm danh mục hay lệnh mới thì sửa tệp cùng lúc.
AI đã cố làm vậy sẵn, nên dòng này chỉ tốn token.
Nêu chỗ, lý do và hậu quả nếu làm sai.
Có lý do, AI biết áp dụng tinh thần quy tắc cho các trường hợp tương tự.
Câu mệnh lệnh ngắn tốt hơn đoạn giới thiệu dài.
Khóa, mật khẩu, địa chỉ nội bộ. Tệp nằm trong kho mã và gửi cho mô hình mỗi lần.
AI sẽ làm theo nội dung tệp. Đây là suy luận từ cách tệp hoạt động, không dựa vào một vụ việc cụ thể.
Lời dặn trong văn bản không thay được quyền hạn thật. Giới hạn quyền ở nơi khác.
Điền từng mục bằng câu mệnh lệnh ngắn. Mục nào chưa có gì để viết thì cứ bỏ trống.
Hãy bắt đầu nhỏ, rồi thêm khi AI lặp lỗi.
Vì vậy: ngắn, đúng, có đo. Đừng coi nó là phép màu.
Tối nay hãy mở tệp của bạn và xóa một dòng AI vốn đã biết.