Hướng dẫn viết AGENTS.md và HUMAN.md cho AI coding

AGENTS.md là gì

AGENTS.md là một tệp markdown thuần túy nằm tại thư mục root của repository, có nhiệm vụ 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 tệp README dành cho các agent: một vị trí chuyên biệt, có thể dự đoán trước để 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 tệp 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 nhóm của bạn sẽ đọc tệp 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 trả về, và thử cách khác. Bạn phải trả phí cho từng 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 sẽ 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 tệp tin này nằm tại một đường dẫn mà mọi công cụ đều đã quét qua.

Vị trí đặt tệp và tệp nào có quyền ưu tiên

Hãy đặt tệp đầ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 tệp bên trong mỗi dự án con, và quy tắc rất đơn giản: "các agent tự động đọc tệp gần nhất trong cây thư mục, vì vậy tệp gần nhất sẽ có quyền ưu tiên." Xung đột giữa hai tệp sẽ được giải quyết theo hướng tệp đ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 tệp rất đáng sử dụng, vì đây 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 xác thực dữ liệu đầu vào" cần đặt cạnh các endpoint đó. Nếu đặt trong tệp gốc, nó sẽ tải trên mọi tác vụ không liên quan và không mang lại lợi ích gì.

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 từ mã nguồn. Các lệnh build, test và lint chính xác phải được đặt lên đầu, ở định dạng bạn sẽ dán vào terminal. Hãy thêm lệnh để chạy một bài test đơn lẻ, vì một agent nếu chỉ biết chạy toàn bộ bộ test sẽ thực hiện việc đó tới 40 lần. Hãy nêu tên các quy ước khác với mặc định của công cụ, vì agent đã biết các 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 thông điệp commit và các quy tắc pull request nếu có.

Hãy viết đủ cụ thể để có thể kiểm chứng được. "Sử dụng thụt lề 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 mã nguồn đúng cách" thì không, vì không có gì trong đó có thể xác minh được. Điều tương tự á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ữ các tệp được sắp xếp ngăn nắp".

Các quy tắc phủ định cũng rất quan trọng. "Không bao giờ chỉnh sửa các tệp trong dist/, chúng được tạo tự động bởi npm run build" 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 luận ra các trường hợp tương tự mà bạn chưa liệt kê.

Những thứ không bao giờ được đưa vào

Đừng bao giờ đặt bí mật vào một trong những tệp này. Tệp này được commit vào git, được tải vào context khi bắt đầu mỗi phiên làm việc và được gửi đến nhà cung cấp mô hình trong mỗi yêu cầu. Một API key nằm trong AGENTS.md đồng nghĩa với việc nó nằm trong lịch sử repository của bạn và trong log của bên thứ ba. Hãy trỏ đến bí mật thay vì dán trực tiếp: "mật khẩu cơ sở dữ liệu nằm trong .env, tệp này đã được gitignore; hãy hỏi trước khi đọc nó." Nguyên tắc rộng hơn được đề cập trong giữ thông tin xác thực ngoài tầm với 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 thư mục được dán vào, một bản sao danh sách dependency, một bản tổng quan kiến trúc liệt kê lại các tên thư mục: tất cả đều 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ó tiêu tốn context trong mỗi phiên làm việc. Hãy giữ lại các cạm bẫy và lý do. Loại bỏ phần liệt kê tài nguyên.

CLAUDE.md là phiên bản Claude Code của cùng một ý tưởng

Claude Code đọc CLAUDE.md và không tự đọc AGENTS.md. Một tệp dự án nằm tại ./CLAUDE.md hoặc ./.claude/CLAUDE.md, các tùy chọn cá nhân cho mỗi dự án nằm trong ~/.claude/CLAUDE.md, và một tổ chức có thể đẩy một tệp áp dụng cho toàn bộ máy vào /etc/claude-code/CLAUDE.md trên Linux. Các tệp được phát hiện sẽ được nối từ root của hệ thống tệp xuống thư mục làm việc của bạn, vì vậy tệp gần nhất với nơi bạn khởi chạy phiên làm việc sẽ được đọc cuối cùng.

Nếu repository của bạn đã có sẵn một tệp 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 đó, tệp đã 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 tệp khởi đầu, và khi một tệp CLAUDE.md đã tồn tại, nó sẽ gợi ý các cải tiến thay vì ghi đè.

Hãy giữ mỗi tệp dưới khoảng 200 dòng. Các tệp 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à mức độ 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. Một tệp AGENTS.md là hướng dẫn, không phải là hệ thống phân quyền. Nội dung được đưa vào dưới dạng ngữ cảnh thông thường, vì vậy model sẽ đọc nó và thường tuân thủ, nhưng không có gì ngăn cản một hành động trái ngược với nó. Đối với một quy tắc phải luôn luôn được giữ vững, 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ư mã nguồn và không phụ thuộc vào việc model quyết định có tuân theo hay không.

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

Hai dự án nằm trong danh sách xu hướng 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 dùng để duy trì cây tệp AGENTS.md luôn ở trạng thái cập nhật. Nó không phát hành gói cài đặt hay runtime nào. Bạn sao chép nội dung từ tệp AGENTS.md của nó vào tệp AGENTS.md ở thư mục root của chính 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 tệp 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 tác dụ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, cùng một thủ thuật áp dụng cho 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 tệp tin bạn tự soạn thảo: "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 tệp HUMAN.md viết tay chỉ khoảng hai mươi dòng: vai trò của bạn, múi giờ, stack 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 thời gian giải thích lặp đi lặp lại giống như tệp dự án, nhưng ở một 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ó ngoài các repository công khai. Hãy đặt nó trong ~/.claude/CLAUDE.md, hoặc trong một tệp CLAUDE.local.md đã được gitignore tại thư mục gốc của dự án, tệp này sẽ được tải cùng với tệp đã commit và được xử lý theo cùng một cách.

Mẫu 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 đó chỉnh sửa trực tiếp tại chỗ. Dấu hiệu cho thấy cần thêm một dòng là khi bạn phải nhập cùng một nội dung chỉnh sửa vào khung chat hai lần. Quy tắc đơn giản này giúp tệp tin 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, tệp tin này 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 một coding agent trên server của riêng bạn đề cập đến thiết lập đó.

FAQ

AGENTS.md có giống với CLAUDE.md không?

Chúng là cùng một ý tưởng dưới hai tên tệp 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 tệp làm nguồn dữ liệu chính và liên kết tệp còn lại vào đó, bằng một dòng ghi @AGENTS.md ở đầu tệp CLAUDE.md hoặc bằng ln -s AGENTS.md CLAUDE.md. Hai bản sao đầy đủ được duy trì riêng biệt sẽ không còn đồng nhất trong vòng một tháng.

Việc viết AGENTS.md có đảm bảo agent sẽ tuân theo 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 tuân thủ, nhưng không có gì ngăn cản 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 tệp đưa ra hướng dẫn trái ngược nhau sẽ khiến agent tự chọn một cách tùy ý. Đối với một quy tắc bắt buộc phải thực hiện mọi lúc, hãy sử dụng hook hoặc quy tắc phân quyền, vốn được client thực thi 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. Đó là mục đích của tệp này, vì agent của các đồng đội bạn sẽ bắt đầu với cùng 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 tệp riêng biệt đã được gitignore, và thông tin xác thực 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à hồ sơ có thể đọc được bằng máy về một cá nhân thay vì một dự án. Nó chứa vai trò, các ràng buộc và các quyết định 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 tệp hướng dẫn cấp người dùng của bạn sẽ mang lại hầu hết giá trị. Hãy coi nó là dữ liệu cá nhân và giữ nó ngoài bất kỳ repository nào mà bạn push lên.