Cách viết file AGENTS.md và HUMAN.md tối ưu cho AI

AGENTS.md là gì

AGENTS.md là một file markdown thuần nằm tại thư mục gốc của repository, hướng dẫn coding agent cách làm việc trên dự án đó. Trang web chính thức mô tả nó là "một file README dành cho các agent: một nơi chuyên biệt, dễ dự đoán để cung cấp ngữ cảnh và chỉ dẫn giúp các AI coding agent làm việc trên dự án của bạn." Định dạng này được quản lý bởi Agentic AI Foundation thuộc Linux Foundation, và hiện có hơn hai mươi agent đọc file này, bao gồm Codex, Cursor, Jules, Devin và GitHub Copilot (tính đến tháng 7 năm 2026).

Lý do quy ước này tồn tại rất thực tế. Một nhân sự mới trong team của bạn sẽ đọc file README, đoán lệnh build, và hỏi người khác khi đoán sai. Một agent thì không thể hỏi. Nó sẽ tự đoán, chạy npm test trên một dự án sử dụng pnpm test, đọc lỗi, rồi thử cách khác. Bạn phải trả phí cho mỗi token đó. Việc ghi lại lệnh chính xác một lần sẽ loại bỏ hoàn toàn loại lỗi này.

Không có trường bắt buộc nào. Trang web đã nêu rõ: "AGENTS.md chỉ là Markdown tiêu chuẩn. Hãy sử dụng bất kỳ tiêu đề nào bạn muốn; agent chỉ đơn giản là phân tích cú pháp văn bản bạn cung cấp." Đó là toàn bộ đặc tả kỹ thuật. Giá trị không nằm ở định dạng. Nó nằm ở việc file này nằm tại một đường dẫn mà mọi công cụ đều đã quét qua.

Vị trí đặt file và file nào được ưu tiên

Hãy đặt file đầu tiên tại thư mục gốc của repository. Trong một monorepo, bạn có thể thêm nhiều file hơn bên trong mỗi subproject, và quy tắc rất đơn giản: "các agent tự động đọc file gần nhất trong cây thư mục, vì vậy file nào gần nhất sẽ được ưu tiên." Xung đột giữa hai file sẽ được giải quyết theo hướng ưu tiên file đang được chỉnh sửa, và bất kỳ nội dung nào bạn nhập vào chat đều ghi đè lên cả hai.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Việc lồng ghép các file là cần thiết, vì đó là cách duy nhất để thiết lập một quy tắc đúng ở thư mục này nhưng lại sai ở thư mục khác. Một quy tắc như "mọi endpoint đều phải validate input" nên nằm cạnh các endpoint đó. Nếu đặt ở file gốc, nó sẽ được tải cho mọi tác vụ không liên quan và không mang lại lợi ích gì. Nếu file gốc của bạn đã trở nên quá dài với mỗi phần dành cho một service, chia nhỏ nó thành cấu trúc lồng nhau là giải pháp, và nó sẽ xác định quy tắc nào cần chuyển xuống dưới và quy tắc nào nên giữ lại ở cấp cao nhất.

Nội dung cần có trong AGENTS.md

Hãy ghi lại những thông tin mà agent không thể tự suy luận ra khi đọc code. Các lệnh build, test và lint chính xác phải được đưa lên đầu, ở dạng bạn sẽ dán trực tiếp vào terminal. Hãy thêm lệnh để chạy một test đơn lẻ, vì một agent nếu chỉ biết chạy toàn bộ bộ test sẽ thực thi lại toàn bộ bộ test đó tới bốn mươi lần. Hãy nêu tên các quy ước khác biệt so với mặc định của công cụ, vì agent đã biết các giá trị mặc định và chỉ cần biết về điểm khác biệt của bạn. Hãy thêm cấu trúc commit message và các quy tắc pull request nếu bạn có.

Hãy viết đủ cụ thể để có thể kiểm chứng được. "Sử dụng thụt đầu dòng 2 khoảng trắng" là một chỉ dẫn hữu ích vì nó có thể được kiểm tra là đã thực hiện hay chưa. "Định dạng code đúng cách" thì không, vì không có gì trong đó có thể xác minh được. Điều tương tự cũng áp dụng cho các vị trí: "Các API handler nằm trong src/api/handlers/" tốt hơn nhiều so với "giữ file có tổ chức".

Các quy tắc phủ định cũng rất quan trọng. "Không bao giờ chỉnh sửa các file trong dist/, chúng được tạo tự động bởi npm run build" giúp ngăn chặn một lỗi cụ thể, và vì nó nêu rõ nguyên nhân, agent có thể tự suy ra các trường hợp tương đương mà bạn chưa liệt kê. Một quy tắc về phạm vi (scope) cũng nên nằm ở đây, vì nếu để agent tự quyết định, nó sẽ viết lại nhiều hơn những gì bạn yêu cầu: một kỹ năng được sao chép rộng rãi chỉ tập trung vào việc nhấn mạnh thay đổi nhỏ nhất có hiệu quả.

Những nội dung không bao giờ được đưa vào

Đừng bao giờ đặt secret vào các file này. File sẽ được commit vào git, được load vào context mỗi khi bắt đầu session, và được gửi tới nhà cung cấp model trong mỗi request. Một API key nằm trong AGENTS.md đồng nghĩa với việc API key đó nằm trong lịch sử repository và trong log của bên thứ ba. Hãy trỏ tới vị trí chứa secret thay vì dán trực tiếp: "mật khẩu database nằm ở .env, file này đã được gitignore; hãy hỏi trước khi đọc nó." Nguyên tắc rộng hơn về vấn đề này được đề cập tại giữ thông tin xác thực ngoài tầm truy cập của agent.

Hãy bỏ qua bất cứ thứ gì mà agent có thể tự suy ra bằng cách quan sát. Một danh sách file trong thư mục, bản sao danh sách dependency, hay tổng quan kiến trúc liệt kê lại tên các thư mục: tất cả sẽ trở nên lỗi thời chỉ một tuần sau khi bạn viết, và trong thời gian đó nó làm tốn dung lượng context trong mỗi session. Hãy giữ lại các cạm bẫy và lý do. Hãy bỏ qua phần liệt kê tài nguyên. Các lý do cần được tách riêng, vì một agent không hiểu tại sao một cấu trúc bất thường lại tồn tại sẽ âm thầm refactor nó đi, đó là lý do cần giữ một file DESIGN.md bên cạnh file này.

CLAUDE.md là instance Claude Code của cùng ý tưởng đó

Claude Code đọc CLAUDE.md và không tự đọc AGENTS.md. File dự án nằm tại ./CLAUDE.md hoặc ./.claude/CLAUDE.md, tùy chọn cá nhân cho mỗi dự án nằm trong ~/.claude/CLAUDE.md, và tổ chức có thể đẩy một file áp dụng cho toàn bộ máy vào /etc/claude-code/CLAUDE.md trên Linux. Các file được phát hiện sẽ được nối tiếp từ root của filesystem xuống thư mục làm việc của bạn, vì vậy file gần với nơi bạn khởi chạy phiên làm việc nhất sẽ được đọc sau cùng. Mỗi phiên bạn bắt đầu trong thư mục đó đều tải cùng một stack, đây là lý do tại sao có thể chạy hai phiên song song trên một máy, và các phiên đó có thể bàn giao công việc cho nhau trong khi đang chạy.

Nếu repository của bạn đã có sẵn một file AGENTS.md, đừng duy trì bản sao thứ hai. Hãy import nó, sau đó chỉ thêm những nội dung dành riêng cho Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Một symlink sẽ hoạt động khi bạn không có gì thêm để bổ sung:

ln -s AGENTS.md CLAUDE.md

Lệnh này không in ra gì khi thành công. Trong phiên làm việc tiếp theo, hãy chạy /context và xác nhận CLAUDE.md xuất hiện dưới mục Memory files. Nếu nó thiếu trong danh sách đó, file đã không được tải, vì vậy không có nội dung nào trong đó được áp dụng. Để tạo bản nháp đầu tiên thay vì tự viết, hãy chạy /init: nó sẽ đọc codebase và tạo ra một file khởi đầu, và khi đã có sẵn một file CLAUDE.md, nó sẽ gợi ý các cải tiến thay vì ghi đè.

Hãy giữ mỗi file dưới khoảng 200 dòng. Các file dài hơn sẽ tiêu tốn nhiều không gian của cửa sổ ngữ cảnh hơn và độ tuân thủ sẽ giảm xuống. Nếu bạn muốn xem những gì khác cạnh tranh cho không gian đó, những gì thực sự lấp đầy cửa sổ ngữ cảnh của agent sẽ phân tích chi tiết.

Một điểm cần nhấn mạnh. AGENTS.md là hướng dẫn, không phải hệ thống phân quyền. Nội dung được đưa vào như ngữ cảnh thông thường, vì vậy model sẽ đọc và thường tuân thủ, nhưng không có gì ngăn cản một hành động trái với hướng dẫn đó. Khi một quy tắc bạn viết bị lờ đi một cách âm thầm và bạn không thể biết lý do, hãy xem qua các lý do khiến một chỉ dẫn bị bỏ qua trước khi bạn viết lại câu chữ lần thứ ba. Đối với một quy tắc bắt buộc phải tuân thủ mọi lúc, chẳng hạn như "không bao giờ push vào main", hãy sử dụng hook hoặc thiết lập quyền, vì những thứ đó chạy như code và không phụ thuộc vào việc model có quyết định tuân theo hay không.

Các công cụ tự động tạo file này cho bạn

Hai dự án nằm trong danh sách trending trên GitHub vào ngày 30 tháng 7 năm 2026 cho thấy xu hướng của quy ước này.

agent0ai/dox (1.368 sao tính đến tháng 7 năm 2026) là một framework giúp duy trì cây thư mục các file AGENTS.md luôn cập nhật. Dự án này không phát hành package hay runtime nào. Bạn chỉ cần copy nội dung file AGENTS.md của nó vào file AGENTS.md ở thư mục root của bạn, đó chính là quá trình cài đặt. Đối với một dự án đã tồn tại, bạn ra lệnh cho agent của mình:

Initialize DOX tree for this project now.

Sau đó, agent sẽ tạo các file AGENTS.md con cùng các chỉ mục của chúng, duyệt qua cây thư mục đó trước khi thực hiện bất kỳ chỉnh sửa nào, và cập nhật tài liệu liên quan sau khi thay đổi được áp dụng. Giả thuyết đằng sau công cụ này là tài liệu được agent duy trì như một hiệu ứng phụ trong quá trình làm việc sẽ luôn chính xác, trong khi tài liệu do con người cập nhật thủ công thì không.

HUMAN.md, thủ thuật tương tự áp dụng cho chính bạn

Intuition-Lab/personal-model (1.260 sao tính đến tháng 7 năm 2026) áp dụng mô hình này cho một cá nhân thay vì một repository. Dự án coi HUMAN.md của bạn là đầu ra của hệ thống thay vì một file bạn tự viết: "một mô hình sống động về những gì quan trọng hiện tại, cách bạn thường ra quyết định và nơi sự chú ý của bạn đang hướng tới." Nó chạy cục bộ trên macOS 13 trở lên, ghi lại hoạt động sau khi bạn cấp quyền trên macOS và cung cấp kết quả cho các agent thông qua MCP (model context protocol). Đường dẫn cài đặt nhanh:

uv tool install personal-model
persome onboard
persome model open --after 30

Bạn không cần tất cả những thứ đó để đạt được hầu hết lợi ích. Một file HUMAN.md viết tay chỉ khoảng hai mươi dòng: vai trò của bạn, múi giờ, stack công nghệ bạn thực sự sử dụng, các quyết định bạn đã đưa ra và không muốn thảo luận lại, cùng mức độ giải thích bạn mong muốn nhận được. Nó giúp tiết kiệm việc giải thích lặp đi lặp lại giống như cách một file dự án thực hiện, nhưng ở cấp độ cao hơn.

Một lưu ý. HUMAN.md là hồ sơ của một cá nhân, vì vậy theo định nghĩa, nó rất nhạy cảm. Hãy giữ nó bên ngoài các repository công khai. Hãy đặt nó trong ~/.claude/CLAUDE.md, hoặc trong một file CLAUDE.local.md đã được gitignore tại thư mục gốc của dự án, file này sẽ được tải cùng với file đã commit và được xử lý theo cùng một cách.

Template khởi đầu bạn có thể sao chép

Tài liệu này được viết ngắn gọn có chủ đích. Hãy xóa các phần không áp dụng và tránh thêm vào những phần bạn không thể duy trì cập nhật.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Hãy viết, sau đó sửa lỗi ngay tại chỗ. Dấu hiệu để thêm một dòng mới là khi bạn nhập cùng một nội dung sửa lỗi vào khung chat hai lần. Quy tắc duy nhất này giúp file luôn hữu ích và ngăn nó phát triển thành một tài liệu không ai đọc, kể cả máy móc. Khi đã ổn định, nó sẽ đi kèm với repository, điều này quan trọng nhất khi agent chạy ở một nơi khác ngoài laptop của bạn: chạy coding agent trên server của riêng bạn đề cập đến thiết lập đó.

FAQ

AGENTS.md có phải là cùng một file với CLAUDE.md không?

Chúng là cùng một ý tưởng dưới hai tên file khác nhau. Claude Code đọc CLAUDE.md và bỏ qua AGENTS.md trừ khi bạn kết nối chúng. Hãy giữ một file làm nguồn dữ liệu chính và liên kết file còn lại vào đó, bằng một dòng ghi @AGENTS.md ở đầu file CLAUDE.md hoặc bằng ln -s AGENTS.md CLAUDE.md. Hai bản sao đầy đủ nếu được duy trì riêng biệt sẽ sớm có nội dung mâu thuẫn chỉ trong vòng một tháng.

Việc viết AGENTS.md có đảm bảo agent sẽ tuân thủ nó không?

Không. Nội dung được cung cấp dưới dạng ngữ cảnh, vì vậy model sẽ đọc và thường là tuân thủ, nhưng không có gì ngăn cản được một hành động trái ngược với nó. Các hướng dẫn mơ hồ thường ít được tuân thủ nhất, và hai file đưa ra các chỉ dẫn trái ngược nhau sẽ khiến agent chọn ngẫu nhiên một trong hai. Đối với một quy tắc bắt buộc phải thực thi mọi lúc, hãy sử dụng hook hoặc quy tắc phân quyền, vốn được client cưỡng chế bất kể model quyết định thế nào.

AGENTS.md có nên được commit vào git không?

Có, đối với bất kỳ thông tin nào đúng về dự án: lệnh build, cấu trúc, quy ước. Đó chính là mục đích của file này, vì agent của các đồng nghiệp của bạn sau đó sẽ bắt đầu với cùng một ngữ cảnh như của bạn. Bất kỳ thông tin cá nhân hoặc thông tin cụ thể cho một máy nào đó nên nằm trong một file riêng biệt đã được gitignore, và thông tin xác thực (credentials) thì không nên nằm trong cả hai.

HUMAN.md là gì và tôi có cần nó không?

HUMAN.md là một hồ sơ có thể đọc được bằng máy về một cá nhân thay vì một dự án. Nó lưu giữ vai trò, các ràng buộc và những quyết định mà bạn đã chốt để chúng không bị thảo luận lại trong mỗi phiên làm việc. Bạn không cần công cụ gì để bắt đầu: hai mươi dòng viết tay trong file hướng dẫn cấp người dùng của bạn đã mang lại hầu hết giá trị. Hãy coi nó là dữ liệu cá nhân và giữ nó bên ngoài bất kỳ repository nào mà bạn push lên.