Sổ tay cho AI (AGENTS.md): viết thế nào cho ngắn, đúng và có ích

Dành cho người làm việc với AI agent trong dự án, kể cả người mới. Thuật ngữ nào cũng đi kèm lời giải thích bằng ví dụ đời thường.

Số liệu lấy từ nghiên cứu và bài viết công khai ở cuối bài. Hai nghiên cứu chính chưa được kiểm chứng độc lập, và nghiên cứu về chủ đề này còn rất mới. Ví dụ "từ dự án này" là dữ liệu thật của chính kho mã blog này.

---

Tóm tắt nhanh#

• AGENTS.md (hay CLAUDE.md, tên khác của cùng ý tưởng) là một tệp văn bản trong dự án để dặn AI những điều nó không tự suy ra được. Có thể hình dung như cuốn sổ tay trên bàn của người mới vào nhóm.
• Hiệu quả thì trái chiều: một nghiên cứu thấy AI chạy nhanh hơn và tốn ít token hơn, một nghiên cứu khác thấy tốn nhiều bước và nhiều chi phí hơn. Đừng tin một phía, hãy tự đo.
• Nguyên tắc rút ra: ngắn, do người viết, và chỉ ghi điều AI không đọc ra được từ code.
• Sáu mục đáng có: lệnh chạy, bức tranh tổng thể, quy ước, chỗ dễ nhầm, điều cấm, và "xong là thế nào".
• Tệp này là tài liệu sống: thêm một dòng khi AI lặp lại lỗi, xóa dòng khi lỗi thời.
• Về an toàn: không dán bí mật vào tệp, và đọc kỹ tệp này trong kho mã lạ vì AI sẽ làm theo nó.

---

Từ khó, nói dễ#

---

1. AGENTS.md là gì, và vì sao có nhiều tên#

Mỗi lần bắt đầu một việc, AI agent không nhớ gì về dự án của bạn. Nó phải đọc lại code, đoán cách chạy, đoán quy ước. Một tệp ghi sẵn những điều đó giúp nó đỡ phải đoán, giống như đưa cuốn sổ tay cho một đồng nghiệp mới vào.

Theo các bài viết công khai, ý tưởng AGENTS.md xuất hiện khoảng tháng 5/2025, khi các lập trình viên phàn nàn rằng mỗi công cụ đọc một tệp riêng như CLAUDE.md hay GEMINI.md. AGENTS.md đề xuất một tên chung. Theo một bài báo cáo, định dạng này nay do Agentic AI Foundation thuộc Linux Foundation đứng ra điều phối (nguồn này yếu, hãy kiểm tra lại). Nhiều nguồn nói có hơn 20.000 kho mã trên GitHub dùng, và Codex là công cụ được nêu tên rõ nhất đã hỗ trợ. Mình chưa tìm được nguồn xác nhận về từng công cụ khác, nên đừng coi mọi công cụ đều đọc tên AGENTS.md.

Cách làm thực tế: nếu công cụ bạn dùng đọc một tên khác, hãy dùng tên đó (dự án này dùng CLAUDE.md), hoặc tạo AGENTS.md và để công cụ trỏ tới nó.

---

2. Nó có thật sự có ích không?#

Hai nghiên cứu mới, đi theo hai hướng.

Hai nghiên cứu đo hai việc khác nhau trên hai bộ đề khác nhau, nên chưa thể coi cái nào là câu trả lời cuối. Mình mới đọc bản tóm tắt, chưa đọc kỹ cả hai bài gốc.

Cách đọc an toàn cho công việc:

1. Tệp ngữ cảnh có thể tốn chi phí. Mỗi dòng trong tệp được đọc ở mỗi lần làm việc. Dòng thừa là chi phí thật.
2. Do người viết có vẻ tốt hơn do AI sinh ra. Hãy dùng công cụ sinh tệp khởi đầu (ví dụ lệnh /init), rồi cắt tỉa tay.
3. Đo trước và sau. Chạy cùng một việc với và không có tệp, so thời gian, số lần sửa và lỗi. Cách ghi nhật ký đo ở bài ba tiếng làm việc với AI agent.

---

3. Viết gì, không viết gì#

Câu hỏi để lọc từng dòng: AI có tự suy ra được điều này từ code không? Nếu có, đừng viết. Nếu không, và nó quan trọng, hãy viết.

Viết bằng câu mệnh lệnh ngắn thay vì đoạn văn giới thiệu. "Chạy npm test trước khi báo xong" tốt hơn "Dự án này có một bộ test khá đầy đủ".

---

4. Sáu mục nên có#

1. Lệnh. Cài đặt, chạy, build, test, kiểm tra. Ghi lệnh chạy một test, vì AI hay phải chạy riêng một test.
2. Bức tranh tổng thể. Một đến hai đoạn về cách các phần nối với nhau và vì sao. Đây là thứ phải đọc nhiều file mới hiểu.
3. Quy ước. Đặt tên, ngôn ngữ của chữ hiển thị, cách xử lý lỗi, kiểu commit.
4. Chỗ dễ nhầm. Những lỗi đã từng xảy ra. Mỗi lỗi lặp lại là một dòng.
5. Điều cấm. Thư mục, lệnh hoặc hành động không được làm nếu chưa hỏi.
6. Xong là thế nào. Điều kiện để báo hoàn thành: có test, đã chạy kiểm tra, có ảnh chụp.

Không có mục nào cần dài. Mục tiêu là người đọc lướt trong một phút vẫn nắm được.

---

5. Ví dụ thật: CLAUDE.md của dự án này#

Dự án blog này có một tệp CLAUDE.md, 49 dòng, 5 mục, khoảng 5 KB. Cấu trúc:

Những thứ không có trong tệp: danh sách từng bài viết, giải thích cú pháp Markdown, nội dung chi tiết của các bộ hướng dẫn (chúng nằm trong tệp riêng, tệp chính chỉ trỏ tới).

Phần chi tiết hơn được tách ra bốn tệp hướng dẫn trong thư mục riêng, tổng cộng 327 dòng, và AI chỉ đọc khi việc liên quan. Cách tách này giữ tệp chính ngắn. Nhiều dòng trong các tệp đó sinh ra từ một lỗi thật đã xảy ra, ví dụ "mascot cần overflow: visible" hay "mọi chữ nhìn thấy phải qua cơ chế dịch", đúng vòng lặp ở mục 7.

---

6. Hai ví dụ trước và sau#

Dòng mơ hồ

Hãy viết code sạch và theo các thực hành tốt nhất.

AI đã cố làm điều này sẵn, nên dòng này chỉ tốn token.

Dòng cụ thể

Chữ hiển thị cho người dùng nằm trong site/i18n.mjs và luôn có đủ ba ngôn ngữ vi, en, ja. Không gõ chữ trực tiếp trong template.

Dòng này nêu chỗ cụ thể, lý do, và hậu quả nếu làm sai.

Điều cấm kèm lý do

Không sửa tay thư mục dist/. Nó được sinh lại mỗi lần chạy npm run build và mọi thay đổi sẽ mất.

Có lý do thì AI biết áp dụng tinh thần của quy tắc cho các trường hợp tương tự.

---

7. Giữ cho tệp luôn đúng#

Tệp này hỏng theo thời gian nếu không ai chăm. Một vòng lặp nhỏ:

1. Khi AI lặp lại cùng một lỗi lần thứ hai, thêm một dòng. Dòng nên nêu điều cần làm và lý do, không chỉ nêu lỗi.
2. Khi một dòng lỗi thời, xóa. Lệnh đã đổi, thư mục đã dời, quy tắc đã bỏ.
3. Khi một dòng không bao giờ giúp, xóa. Thử bỏ nó đi và xem AI có làm sai không.
4. Duyệt thay đổi của tệp như duyệt code. Nó ảnh hưởng đến mọi lần AI làm việc.
5. Mỗi quý đọc lại từ đầu. Nếu bạn không đọc lướt nhanh được, tệp đã quá dài.

Hai thói quen giúp tệp ngắn: tách phần chi tiết ra tệp riêng và chỉ trỏ tới (nhiều công cụ cho phép nhập một tệp từ tệp khác), và để sở thích cá nhân vào tệp riêng không đưa vào kho mã (một số công cụ gợi ý tên như CLAUDE.local.md và đưa vào danh sách bỏ qua của git).

---

8. An toàn#

• Đừng dán bí mật vào tệp. Khóa, mật khẩu, địa chỉ nội bộ. Tệp này nằm trong kho mã và được gửi cho mô hình ở mỗi lần làm việc.
• Đọc tệp này trong kho mã lạ. AI sẽ làm theo nội dung của nó, nên một tệp do người khác viết có thể chứa những dòng dặn AI làm điều bạn không muốn. Đây là suy luận từ cách các tệp này hoạt động, không dựa trên một vụ việc cụ thể mà mình đã kiểm. Trước khi cho agent chạy trong một kho mã bạn không tin, hãy mở tệp ra đọc.
• Giới hạn quyền ở nơi khác. Đừng trông chờ tệp này là hàng rào: lời dặn trong văn bản không thay được quyền hạn thật (xem vụ việc Replit ở bài vì sao không nên tin AI tuyệt đối).

---

9. Bản mẫu để chép#

Cắt bớt cho vừa dự án của bạn. Giữ nó dưới một trang.

# Dự án: <tên>

## Là gì
<Hai câu: dự án làm gì, dùng gì, lựa chọn có chủ ý nào cần nhớ>

## Lệnh
- Cài: <lệnh>
- Chạy: <lệnh>
- Test toàn bộ: <lệnh>
- Test một file: <lệnh>
- Kiểm tra trước khi báo xong: <lệnh>

## Bức tranh tổng thể
<Một đến hai đoạn: các phần chính và chúng nối với nhau thế nào>

## Quy ước
- <Đặt tên>
- <Ngôn ngữ của chữ hiển thị>
- <Cách xử lý lỗi>

## Chỗ dễ nhầm
- <Điều đã từng làm sai và cách làm đúng, kèm lý do>

## Điều cấm
- Không <hành động> nếu chưa hỏi, vì <lý do>

## Xong là thế nào
- Có test, đã chạy <lệnh kiểm tra>, đã đọc lại diff

---

10. Nhìn cân bằng#

Bằng chứng về hiệu quả của các tệp này còn mỏng và trái chiều, nên đừng coi nó như phép màu. Một tệp dài, viết vội, hoặc do AI sinh ra mà không cắt tỉa có thể làm AI chạy chậm và tốn kém hơn. Một tệp ngắn, do người viết, cập nhật theo lỗi thật thì có vẻ có lợi, nhưng điều này nên tự kiểm chứng trên dự án của mình.

Điều chắc hơn là một lợi ích khác: tệp này buộc nhóm viết ra những điều ai cũng ngầm hiểu. Những dòng đó giúp cả người mới vào nhóm, và là chỗ để cả nhóm thống nhất quyết định chung, đúng ý của bài làm việc nhóm thời AI. Tệp cũng là nơi biến mỗi lỗi thành một bài học, điều mà bài duyệt code do AI viết gọi là điểm 14: theo quy ước của dự án.

---

11. Danh sách kiểm nhanh#

1. Tệp dưới một trang, đọc lướt được trong một phút?
2. Mỗi dòng trả lời được "AI có tự suy ra được không"?
3. Có lệnh chạy một test và lệnh kiểm tra cuối không?
4. Điều cấm có kèm lý do?
5. Không có bí mật nào trong tệp?
6. Có chỗ ghi lại những lỗi đã lặp lại?
7. Lần cuối bạn xóa một dòng lỗi thời là khi nào?
8. Bạn đã thử chạy một việc với và không có tệp để so sánh chưa?

---

12. Kết luận#

AI agent bắt đầu mỗi việc với trí nhớ trống. Một cuốn sổ tay ngắn, đúng và được chăm sóc giúp nó đỡ đoán, và giúp người trong nhóm cùng nhìn về một hướng. Nhưng hiệu quả chưa được chứng minh chắc chắn, nên hãy coi nó là một thí nghiệm nhỏ: viết ngắn, đo trước và sau, thêm một dòng mỗi khi lỗi lặp lại, xóa một dòng mỗi khi nó hết cần.

Bắt đầu từ ba thứ: lệnh chạy, một đoạn bức tranh tổng thể, và một điều cấm kèm lý do. Một tuần sau, thêm những dòng sinh ra từ lỗi bạn thực sự gặp.

---

Nguồn tham khảo#

Số liệu lấy từ nguồn công khai tính đến tháng 10/2026. Nhiều nguồn là bài thuật lại, và nghiên cứu về chủ đề này còn mới, nên hãy mở nguồn gốc để kiểm tra trước khi trích dẫn.

• AGENTS.md: Socket.dev tổng hợp và InfoQ
• Lulla và cộng sự, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• Hướng dẫn viết CLAUDE.md của cộng đồng: DataCamp (không phải tài liệu chính thức của nhà cung cấp)
• Dữ liệu từ chính dự án này: tệp CLAUDE.md và thư mục .claude/skills/ trong kho mã