Cách dùng AGENTS.md lồng nhau trong monorepo
Một AGENTS.md dài 600 dòng ở root dễ lỗi thời và tốn context. Tách rule theo service để agent chỉ đọc đúng thư mục cần sửa, không kéo theo front end hay Terraform.
Ý nghĩa của AGENTS.md lồng nhau trong monorepo
AGENTS.md lồng nhau trong monorepo nghĩa là có một file nhỏ ở root của repository và thêm một file bên trong mỗi thư mục service. File ở root chứa một số ít quy tắc áp dụng ở mọi nơi, cùng với sơ đồ vị trí của các file còn lại. File của từng service chứa các command và quy ước chỉ áp dụng cho thư mục đó. Khi chỉnh sửa services/worker/queue.py, agent sẽ đọc file ở root và file của worker, không tốn context cho phần front end mà nó sẽ không động đến.
Không cần cài đặt gì. AGENTS.md là một quy ước, và project upstream nói rõ điều đó:
AGENTS.md chỉ là Markdown tiêu chuẩn. Bạn có thể dùng bất kỳ heading nào; agent chỉ phân tích nội dung bạn cung cấp.
Đó là lý do bạn nên học kỹ kỹ thuật này. Format sẽ không tự thay đổi. Những thứ gây lỗi là vị trí đặt file và việc bảo trì, và cả hai đều là trách nhiệm của bạn.
Vì sao một AGENTS.md lớn ở thư mục gốc dần không còn hiệu quả?
Một AGENTS.md dài 600 dòng ở thư mục gốc của repository chứa web app, background worker và thư mục Terraform sẽ hỏng theo 4 cách riêng biệt.
Nó nhanh lỗi thời vì không ai chịu trách nhiệm cập nhật. Kỹ sư đổi tên một test script trong apps/web nhưng đang chỉnh sửa các file bên dưới apps/web. AGENTS.md ở thư mục gốc không nằm trong diff đó, nên không reviewer nào thấy sự không khớp. 6 tuần sau, file vẫn mô tả một build step không còn tồn tại, còn người gây ra thay đổi đã quên mất.
Nó tiêu tốn context trong mọi task. Các file này được load khi bắt đầu session, trước khi agent biết bạn sẽ yêu cầu gì. Tài liệu Claude Code đưa ra một con số cụ thể: “nên giữ dưới 200 dòng cho mỗi file CLAUDE.md. File dài hơn tiêu tốn nhiều context hơn và làm giảm mức độ tuân thủ.” Codex ngừng merge các instruction file khi tổng kích thước đạt 32 KiB, theo mặc định project_doc_max_bytes. Một file ở thư mục gốc mô tả 4 service sẽ dùng ngân sách đó cho 3 service không liên quan trong mọi task.
Các instruction bắt đầu mâu thuẫn với nhau. Thư mục web cần pnpm test. Worker cần pytest -q. Khi viết chung trong một file, mỗi rule chỉ đúng trong một số trường hợp, nên agent phải đoán rule nào đang áp dụng. Tài liệu Claude Code mô tả kết quả như sau: “nếu 2 instruction mâu thuẫn nhau, Claude có thể chọn một cách ngẫu nhiên.” Tách file không ngăn rule còn lại khỏi context. Claude Code nối tất cả instruction file đã load thay vì để một file thay thế file khác. Vì vậy, file ở thư mục gốc luôn có mặt. Khi agent đã mở file trong cả apps/web và services/worker, cả 2 file của các thư mục đó cùng nằm trong context. Tác dụng của file theo từng thư mục là gắn mỗi rule với thư mục mà nó quản lý. Hãy ghi tên thư mục ở đầu file, như các ví dụ bên dưới làm với # apps/web. Khi nhiều file được load cùng lúc, mỗi command vẫn cho biết nó áp dụng ở đâu. Khi một rule mà bạn chắc chắn đã viết rõ vẫn bị bỏ qua, tìm hiểu các lý do khiến instruction không được áp dụng sẽ hiệu quả hơn việc viết lại câu đó lần thứ 4.
Nó bị lấp đầy bởi những thông tin agent có thể đọc từ code. Cấu trúc thư mục, danh sách dependency, phần tóm tắt chức năng của từng package. Claude Code có kiểm tra /doctor để loại bỏ chính những nội dung này. Kiểm tra đó “loại bỏ nội dung mà Claude có thể suy ra từ codebase, chẳng hạn như cấu trúc thư mục, danh sách dependency và tổng quan kiến trúc”, đồng thời giữ lại “các lỗi dễ gặp, lý do và quy ước khác với mặc định của tool”. Đây là tiêu chí tốt nhất tôi biết để xác định một dòng có thực sự thuộc về file này hay không.
Agent có đọc file ở thư mục root không, hay chỉ đọc file gần nhất?
Đây là điểm mà nhiều người hiểu sai về model, vì vậy nên trích nguyên quy ước upstream thay vì diễn giải lại:
Đặt thêm một AGENTS.md bên trong mỗi package. Agent tự động đọc file gần nhất trong cây thư mục, vì vậy file gần nhất sẽ được ưu tiên và mỗi subproject có thể cung cấp bộ hướng dẫn phù hợp riêng.
Về xung đột:
AGENTS.md gần file được chỉnh sửa nhất sẽ được ưu tiên; prompt trực tiếp của người dùng trong chat có quyền ghi đè mọi thứ.
Với nhiều người, "được ưu tiên" có nghĩa là "file ở root bị bỏ qua". Không phải vậy. Trong các tool triển khai quy ước này, mọi file trên đường dẫn từ repository root đến thư mục làm việc đều được đọc và ghép lại. File gần nhất chỉ được ưu tiên khi hai file đưa ra hướng dẫn khác nhau về cùng một vấn đề.
Codex mô tả rõ cơ chế này: "Codex nối các file từ root xuống dưới, phân cách chúng bằng các dòng trống. Những file gần thư mục hiện tại hơn sẽ ghi đè hướng dẫn trước đó." Claude Code cũng duyệt cùng đường dẫn. Khi bắt đầu session, nó đọc "mọi AGENTS.md và .claude/AGENTS.md trong thư mục làm việc của bạn và các thư mục bên trên", đồng thời tài liệu của nó nêu rõ mô hình tải: "Tất cả file được phát hiện đều được ghép vào context thay vì ghi đè lên nhau." Các thư mục bên dưới thư mục làm việc hoạt động khác: Claude Code tải AGENTS.md của thư mục con khi cần, "khi Claude mở một file trong đó bằng tool Read."
Có 2 hệ quả thực tế. File ở root là phần mở đầu trong mọi session của repository, vì vậy hãy xem mỗi dòng ở đó là một dòng bạn phải trả chi phí 100 lần mỗi tuần. File theo từng thư mục không tốn chi phí cho đến khi agent mở một file trong thư mục đó, nên phần hướng dẫn chi tiết nên đặt ở đó.
Hành vi này đã được đối chiếu với tài liệu của Codex và Claude Code vào ngày 27 tháng 10 năm 2026. Các tool triển khai quy ước này hơi khác nhau và chúng cũng có thể thay đổi, vì vậy hãy xác nhận quy tắc tải file cho agent mà team bạn đang sử dụng.
Bố cục mẫu cho một repository có ba service
repo/
AGENTS.md rules true everywhere, plus the map
apps/web/AGENTS.md TypeScript client, Vite, Vitest
services/worker/AGENTS.md Python queue consumer, pytest
infra/AGENTS.md Terraform and the deploy scriptsFile ở root được giữ ngắn một cách có chủ đích. File này chỉ nêu nơi cần tìm và chỉ chứa các rule áp dụng cho mọi thư mục.
# AGENTS.md
This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.
- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts
## Rules for the whole repository
- The package manager is `pnpm`. `npm install` writes a second lockfile
that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
`schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
in the same commit.File ở từng thư mục là nơi chứa phần chi tiết. Độ dài của file có thể tương ứng với mức độ phức tạp của thư mục đó.
# apps/web
Browser client. Vite and React, TypeScript with `strict` on.
## Commands
- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.
## Conventions
- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
because the client attaches the auth header and retries on 429.
## Traps
- `pnpm build` does not type check. Vite strips the types instead of
checking them, so a broken type still produces a green build.
Run `pnpm typecheck` as a separate step.File của worker có cùng cấu trúc nhưng nội dung khác: install command, pytest -q, lý do consumer phải luôn idempotent và migration phải chạy trước khi test pass. File infra là nơi ghi các rule ngăn agent gây hỏng hệ thống. Không bao giờ chạy terraform apply. Chỉ chạy terraform plan rồi dừng lại, đồng thời nêu rõ state backend đã được cấu hình để agent không cố khởi tạo một state backend mới.
Hãy lưu ý những gì không xuất hiện trong bất kỳ file nào: mô tả mục đích của từng service. Phần đó dành cho con người. Upstream cũng phân định như vậy: "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", còn AGENTS.md chứa "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." Phần phân tách giữa AGENTS.md và README dành cho con người trình bày ranh giới này theo từng câu. Một file DESIGN.md ghi lại lý do code có cấu trúc như hiện tại trình bày file thứ ba, dùng để giải thích các quyết định thay vì các command.
Ai cập nhật file khi code thay đổi?
Chỉ cần một quy tắc và ghi quy tắc đó trong file ở root: ai thay đổi code trong một thư mục thì phải cập nhật AGENTS.md của thư mục đó trong cùng commit.
Quy tắc này hiệu quả vì lý do cơ học, không phải vì văn hóa. File theo từng thư mục nằm trong cùng diff với code, nên reviewer của pull request thấy cả hai cùng lúc. File ở root thuộc về tất cả mọi người, nghĩa là không thực sự thuộc về ai, và không bao giờ xuất hiện trong diff mà mọi người đang đọc.
Hãy kiểm tra quy tắc này trong pull request. Kiểm tra sẽ tìm AGENTS.md gần nhất phía trên mỗi file đã thay đổi, rồi báo cáo khi file đó chưa được chỉnh sửa.
#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)
nearest_doc() {
d=$(dirname "$1")
while [ "$d" != "." ]; do
if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
d=$(dirname "$d")
done
echo "AGENTS.md"
}
printf '%s\n' "$changed" | while read -r f; do
[ -n "$f" ] || continue
case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
doc=$(nearest_doc "$f")
printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
echo "note: $f changed but $doc was not updated"
doneVới một branch đã thay đổi API client nhưng không chỉnh sửa tài liệu, output sẽ như sau:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedHãy để đây là cảnh báo thay vì lỗi. Một hard gate sẽ khiến mọi người thêm một dòng trống vào file để CI chuyển sang màu xanh. Một file được chỉnh sửa chỉ để làm hài lòng robot còn kém giá trị hơn cả việc không có file. Cảnh báo cung cấp cho reviewer một câu hỏi cần đặt ra. Đó mới là phần thực sự hiệu quả.
Làm thế nào để phát hiện AGENTS.md đã lỗi thời?
Bạn có thể chạy hai kiểm tra ngay hôm nay và sẽ thấy một dấu hiệu trong session.
So sánh thời gian của từng file với thời gian của code mà file đó mô tả. %cs in ngày commit dưới dạng YYYY-MM-DD.
for f in $(git ls-files '*AGENTS.md'); do
d=$(dirname "$f")
printf '%s doc:%s code:%s\n' "$f" \
"$(git log -1 --format=%cs -- "$f")" \
"$(git log -1 --format=%cs -- "$d")"
doneapps/web/AGENTS.md doc:2026-02-11 code:2026-08-07
services/worker/AGENTS.md doc:2026-07-29 code:2026-08-09
infra/AGENTS.md doc:2026-08-01 code:2026-08-01Ngày của tài liệu chậm hơn ngày của code sáu tháng không chứng minh file đó sai. Nó cho biết nên đọc file nào trước. Chỉ vậy là đủ đối với một kiểm tra mất một giây.
Tìm các path không còn tồn tại. Tài liệu thường lỗi thời theo một cách rất cụ thể: tiếp tục mô tả code đã bị xóa. Mọi path trong các file này đều được viết trong backtick, nên dễ trích xuất và kiểm tra.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneHãy đọc output thay vì đưa kiểm tra này vào CI. Nó cũng sẽ đánh dấu các glob như src/**/*.ts và mọi URL bạn đặt trong dấu nháy, vì cả hai đều chứa dấu gạch chéo nhưng không phải file trên disk. Trên Claude Code v2.1.283 trở lên, /doctor prompt-audit thực hiện một lượt kiểm tra tương tự: tìm "các tham chiếu đến file hoặc command không tồn tại" và các file mâu thuẫn với nhau, mặc định kiểm tra các file AGENTS.md của bạn, và không thay đổi gì cho đến khi bạn yêu cầu áp dụng các chỉnh sửa mà nó đề xuất.
Dấu hiệu trong một session. Agent đọc file, cố mở src/api/client.ts vì file yêu cầu như vậy, rồi tool trả về:
No such file or directoryVì vậy, agent làm điều hợp lý và tự viết một wrapper fetch. Đây là chi phí thực sự của một file lỗi thời. Agent không bỏ qua tài liệu của bạn. Nó làm theo tài liệu, đi đến một path đã bị xóa ba tháng trước, rồi viết lại code mà bạn đã có. Một skill như Ponytail, buộc agent chỉ thực hiện thay đổi nhỏ nhất có hiệu quả, giúp giảm xu hướng viết lại này, nhưng không thể tìm thấy helper khi file của bạn trỏ sai chỗ.
Claude Code có đọc các file AGENTS.md không?
Có, từ Claude Code v2.1.277. Quy tắc chính xác rất quan trọng vì layout lồng nhau phụ thuộc vào quy tắc này. Đã kiểm tra tài liệu vào ngày 27 tháng 10 năm 2026: "Claude Code có thể đọc AGENTS.md làm hướng dẫn dự án, nên repository đã được thiết lập cho các coding agent khác có thể hoạt động mà không cần thêm CLAUDE.md, import hoặc setting." Giá trị Project instructions mặc định, claude-md-or-agents-md, đọc "các file AGENTS.md của bạn khi trong working directory hoặc các thư mục phía trên không có CLAUDE.md hoặc CLAUDE.local.md." Các file lồng nhau cũng được áp dụng: Claude đọc AGENTS.md của một subdirectory "khi Claude mở một file trong đó bằng Read tool", miễn là "subdirectory đó không có file CLAUDE.md nào trong ba file của riêng nó". Ba file đó là CLAUDE.md, .claude/CLAUDE.md và CLAUDE.local.md, nên chỉ cần một CLAUDE.local.md cá nhân trong apps/web là đủ để ngăn apps/web/AGENTS.md được load.
Điều này khiến lời khuyên cũ về việc đặt một CLAUDE.md bên cạnh mỗi AGENTS.md trở thành cái bẫy. Khi có AGENTS.md và CLAUDE.md hoặc CLAUDE.local.md trong working directory hoặc các thư mục phía trên, tài liệu nói Claude chỉ đọc "các file CLAUDE.md của bạn". Một .claude/CLAUDE.md cũng được tính theo cách tương tự. Một file đi kèm tại root chứa một dòng dành riêng cho Claude sẽ ẩn mọi AGENTS.md trên đường dẫn, và một CLAUDE.local.md cá nhân cũng có tác dụng tương tự. Nếu muốn giữ một file, hãy nhập /config và đặt Project instructions thành claude-md-and-agents-md. Setting này đọc cả hai file: CLAUDE.md của từng directory trước, rồi đến AGENTS.md.
Chỉ riêng version number không xác nhận rằng tính năng đã hoạt động. Bạn cần v2.1.277 trở lên, nhưng trước v2.1.281, một số session, chẳng hạn session trên Amazon Bedrock hoặc session đã tắt telemetry, chỉ đọc các file CLAUDE.md. Trong một số trường hợp, session đầu tiên sau khi nâng cấp từ v2.1.276 trở xuống cũng bỏ qua AGENTS.md: tài liệu nói rằng "Claude sẽ đọc AGENTS.md từ session tiếp theo". Vì vậy hãy kiểm tra ngay trong session. Trong một interactive session, Claude Code in ra một dòng như no CLAUDE.md found; AGENTS.md loaded:, theo sau là path. Trên các version hiện tại, /memory liệt kê file đó. Trước v2.1.280, /memory và /context không liệt kê AGENTS.md mà Claude đọc trực tiếp. Vì vậy trên các version đó, hãy hỏi Claude nội dung project instructions mà nó đang sử dụng.
Dạng import vẫn phù hợp khi Claude không thể đọc trực tiếp AGENTS.md: version cũ, session trước v2.1.281 trên Amazon Bedrock hoặc khi telemetry bị tắt, session đã tắt built-in plugin dùng để đọc file này, hoặc project có CLAUDE.md với Project instructions được đặt thành claude-md. Đặt nội dung sau vào services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.Dạng symlink phù hợp khi không cần thêm nội dung dành riêng cho tool.
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln không in gì khi chạy thành công, nên hãy kiểm tra listing: apps/web/CLAUDE.md -> AGENTS.md. Sau đó khởi động một session và chạy /context; các file đã load sẽ xuất hiện dưới Memory files. Trên Windows, symlink cần quyền Administrator hoặc Developer Mode. Git cũng checkout một symlink đã commit thành plain text file nếu core.symlinks chưa được bật. Khi đó clone sẽ chứa một dòng CLAUDE.md thay cho instructions của bạn. Nếu có người clone repository và làm việc trên Windows, hãy dùng @AGENTS.md import. Nếu đã thiết lập một trong hai workaround trước khi Claude Code tự đọc AGENTS.md, bạn có thể giữ nguyên: tài liệu nói rằng việc giữ import "không bao giờ khiến Claude đọc AGENTS.md hai lần", còn một CLAUDE.md được symlink sẽ chỉ được đọc một lần.
Có một cái bẫy liên quan đến việc này. Sau /compact, CLAUDE.md tại project root được đọc lại từ disk, nhưng các file lồng nhau trong subdirectory không được inject lại. Claude Code sẽ reload chúng theo nhu cầu, vào lần tiếp theo agent làm việc với một file trong directory đó. Tài liệu nêu rõ điều này đối với các file CLAUDE.md và không mô tả riêng việc compaction cho AGENTS.md được đọc trực tiếp. Vì vậy, hãy giả định các file lồng nhau của cả hai tên đều hoạt động theo cách này. Nếu rule theo từng directory có vẻ ngừng áp dụng giữa một session dài, đây thường là nguyên nhân. Đọc bất kỳ file nào trong directory đó sẽ nạp rule trở lại.
Các setting trỏ agent khác đến AGENTS.md
Codex đọc AGENTS.md native. Ở mỗi level, nó kiểm tra AGENTS.override.md trước. Điều này cho phép một directory có local override mà không cần sửa file dùng chung. Codex dừng việc merge khi tổng kích thước đạt 32 KiB, là project_doc_max_bytes mặc định. Đây cũng là một lý do nên giữ file root ngắn.
Aider sử dụng file này thông qua .aider.conf.yml với dòng read: AGENTS.md.
Gemini CLI sử dụng file này thông qua .gemini/settings.json với { "context": { "fileName": "AGENTS.md" } }.
Upstream có tài liệu về việc đổi tên tương thích ngược cho các repository vẫn dùng tên singular cũ: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
Trong một monorepo rất lớn, setting claudeMdExcludes của Claude Code bỏ qua các file ancestor theo path hoặc glob. Điều này hữu ích khi directory của team khác nằm phía trên directory của bạn. Các pattern này cũng áp dụng cho các file AGENTS.md mà Claude Code đọc.
Điểm này khác gì với agent memory hoặc skill?
Các cơ chế này trông giống nhau nhưng có cách hỏng hoàn toàn khác nhau. Vì vậy, cần xác định chính xác bạn đang cần cơ chế nào.
AGENTS.md do bạn viết, commit vào git và review trong pull request. Nội dung này giống nhau với mọi người clone repository. Agent memory do agent ghi, được lưu bên ngoài repository và chỉ có trên một máy. Tài liệu Claude Code cũng phân biệt như vậy: CLAUDE.md chứa “Instructions and rules” do bạn viết, còn auto memory chứa “Learnings and patterns” do Claude ghi; thư mục memory không được chia sẻ giữa các máy. Cách kiểm tra rất đơn giản. Nếu một thông tin phải đúng với đồng nghiệp vừa clone repository, thông tin đó không thể nằm trong memory. Cách agent memory tồn tại giữa các phiên trình bày phần này chi tiết hơn.
Skill là cơ chế thứ ba. AGENTS.md là context được nạp trong mọi session; skill là một quy trình chỉ được nạp khi cần. Tài liệu Claude Code đưa ra một quy tắc dễ áp dụng: “Nếu một mục là quy trình nhiều bước hoặc chỉ liên quan đến một phần của codebase, hãy chuyển mục đó vào skill hoặc rule áp dụng theo path.” Vế sau của câu này chính là trường hợp nested AGENTS.md giải quyết. Vế trước là mục đích của agent skills. Khi cùng một quy trình cần dùng trong nhiều repository, hãy chia sẻ skill giữa các repo thay vì dán cùng một đoạn văn vào 10 file AGENTS.md khác nhau.
Upstream ghi rằng “tại thời điểm viết bài, repository OpenAI chính có 88 file AGENTS.md”. Con số này chính là toàn bộ lập luận. Một repository lớn không cần một file lớn hơn. Nó cần nhiều file nhỏ hơn, mỗi file nằm cạnh phần code mà nó mô tả và do người thay đổi phần code đó gần nhất phụ trách.
FAQ
AGENTS.md lồng nhau thay thế tệp gốc hay bổ sung vào tệp đó?
Nó bổ sung vào tệp đó. Tài liệu upstream nói rằng “tệp gần nhất được ưu tiên”, nhưng câu này mô tả cách xử lý khi có xung đột, không phải những gì được tải. Codex “nối các tệp từ gốc xuống, phân cách bằng các dòng trống”, còn Claude Code nối mọi tệp tìm được khi đi ngược lên từ working directory thay vì ghi đè chúng. Tệp gần nhất chỉ được ưu tiên khi hai tệp đưa ra hướng dẫn khác nhau về cùng một chủ đề. Hãy viết các quy tắc dùng chung một lần trong tệp gốc và không lặp lại chúng trong mọi thư mục.
AGENTS.md gốc nên dài bao nhiêu?
Đủ ngắn để bạn không ngại dán nó lên đầu mọi request bạn gửi trong repository đó, vì đó chính là điều xảy ra. Tài liệu của Claude Code khuyến nghị mỗi tệp nên dưới 200 dòng và cảnh báo rằng các tệp dài hơn sẽ “làm giảm mức độ tuân thủ”. Codex mặc định dừng gộp các tệp hướng dẫn khi tổng dung lượng đạt 32 KiB. Nếu tệp gốc của bạn mô tả bốn service, phần lớn nội dung sẽ không cần thiết cho từng task riêng lẻ. Hãy chuyển phần chi tiết xuống các tệp theo từng thư mục và để lại một sơ đồ chỉ dẫn.
Làm thế nào để các tệp này không trở nên lỗi thời?
Đặt một quy tắc trong tệp gốc: ai thay đổi code trong một thư mục thì phải cập nhật AGENTS.md của thư mục đó trong cùng một commit. Đặt tệp ngay cạnh code giúp quy tắc này được tuân thủ, vì thay đổi đó sẽ nằm trong cùng pull request diff mà người khác vốn đang đọc. Thêm một cảnh báo CI ánh xạ từng path đã thay đổi đến AGENTS.md gần nhất nằm phía trên nó, rồi thỉnh thoảng so sánh git log -1 --format=%cs trên từng tệp với cùng command chạy trên thư mục mà tệp đó mô tả.
Claude Code có đọc các tệp AGENTS.md không?
Có, từ v2.1.277. Đã kiểm tra theo tài liệu vào ngày 27 October 2026, Claude Code mặc định đọc AGENTS.md khi trong working directory hoặc các thư mục phía trên không có CLAUDE.md hay CLAUDE.local.md, và đọc AGENTS.md của một thư mục con khi mở một tệp trong đó bằng Read tool nếu thư mục con đó không có CLAUDE.md, .claude/CLAUDE.md hoặc CLAUDE.local.md riêng. Đừng thêm một CLAUDE.md bên cạnh mỗi AGENTS.md: khi có một tệp ở working directory hoặc phía trên nó, Claude chỉ đọc “các tệp CLAUDE.md của bạn”. Nếu bạn cũng cần CLAUDE.md, hãy đặt Project instructions thành claude-md-and-agents-md trong /config, hoặc đặt @AGENTS.md ở dòng đầu tiên của tệp đó. Chạy /memory trong một session và xác nhận path AGENTS.md xuất hiện trong danh sách.
Tôi phải đặt một quy tắc chỉ có hiệu lực đôi khi ở đâu?
Không đặt trong AGENTS.md. Tệp đó được tải trong mọi session, nên mọi dòng trong đó đều cạnh tranh sự chú ý với request bạn thực sự đã nhập. Một quy trình gồm nhiều bước và chỉ thỉnh thoảng mới cần dùng nên được đặt trong skill, vì skill chỉ được tải khi cần. Một quy tắc chỉ áp dụng cho một thư mục nên được đặt trong AGENTS.md của thư mục đó. Một thông tin mà agent có thể đọc trực tiếp từ code, chẳng hạn như cây thư mục hoặc danh sách dependency, thì không nên đặt ở đâu trong hai vị trí này.