AGENTS.md tốt = upgrade từ Haiku lên Opus, AGENTS.md tệ = tệ hơn không có gì

TL;DR

Agentic coding tool như Claude Code, Cursor, Codex đang đọc AGENTS.md mỗi session. Augment Code đo hiệu ứng trên hàng chục file thật trong monorepo của họ và phát hiện: file tốt nhất tăng chất lượng output ngang việc upgrade từ Haiku lên Opus, file tệ nhất khiến output xấu hơn cả khi không có file nào.

Bài này tổng hợp các pattern thắng (kèm số đo cụ thể) và các failure mode hay gặp.

Cùng một file, kết quả ngược nhau ở task khác nhau

Một AGENTS.md không phải uniformly good hay bad. Ví dụ thực:

• Trên một bug fix routine: file boost best_practices lên 25%
• Trên một feature task phức tạp ở cùng module đó: cùng file kéo completeness xuống 30%

Lý do: trên bug fix, decision table giúp agent chọn pattern fetch data đúng ngay lập tức. Trên feature task, cùng file lại pull agent vào reference section, agent mở hàng chục markdown khác để verify approach, tạo abstraction thừa, ship solution thiếu sót.

Từng block trong document có hiệu ứng ngược nhau ở task khác nhau.

Phương pháp

Augment Code dùng AuggieBench — eval suite nội bộ. Lấy PR chất lượng cao từ repo lớn (đại diện công việc dev hằng ngày), set up env + prompt, để agent làm cùng task, rồi so output với golden PR (bản đã merge sau review của senior eng). Lọc PR có scope creep hoặc bug đã biết. Cho study này, thêm 2 filter: PR phải nằm trong 1 module/app duy nhất, và scope phải là loại mà info trong AGENTS.md plausibly có thể giúp. Mỗi task chạy 2 lần — có và không có file — rồi so điểm.

7 Pattern thắng

1. Progressive disclosure beats comprehensive coverage

Treat AGENTS.md như một skill. Cover common case + workflow ở high level, push chi tiết vào reference file để agent load on demand. Mỗi reference cần scope rõ để agent biết khi nào cần pull in.

Số đo: 100–150 dòng + vài reference doc focused → top performer, mang lại 10–15% improvement cross-metric trên module mid-size (~100 core files). Vượt mốc đó, gain bắt đầu reverse.

2. Procedural workflow đưa agent từ fail thành finish

Mô tả task dạng workflow numbered, multi-step là một trong những pattern mạnh nhất. Workflow tốt có thể chuyển agent từ “không làm xong được” thành “làm đúng từ lần đầu”.

Ví dụ: 6-step workflow để deploy một integration mới — agent follow đúng từng bước, không lạc.

3. Decision table cho stack choice

Khi codebase có nhiều cách làm cùng việc (e.g. fetch data: SWR vs server state vs local cache), decision table thắng prose explanation:

| Server là single source? | ✅ |   |
| Multiple code path mutate state? |   | ✅ |
| Cần optimistic update + local state? |   | ✅ |

Số đo: PR ở khu vực này score best_practices cao hơn 25%. Table giải quyết ambiguity trước khi agent viết dòng code đầu tiên.

4. Example từ codebase thật

Snippet 3–10 dòng từ production code cải thiện reuse và pattern adherence. Giữ vài example relevant nhất, không duplicate. Nhiều hơn → agent pattern-match nhầm chỗ.

5. Domain rule vẫn quan trọng

Language-specific gotcha hoặc org-specific quirk. Pattern này hay được dùng nhất trong AGENTS.md. Hoạt động khi rule specific và enforceable. Không hoạt động khi xếp chồng hàng tá.

6. Cặp “Don’t” với “Do” cụ thể

Warning-only documentation underperform consistently so với prohibitions kèm alternative cụ thể.

• Tệ: Don't instantiate HTTP clients directly
• Tốt: Don't instantiate HTTP clients directly. Use the shared apiClient from lib/http with the retry middleware.

Dạng đầu chỉ làm agent cautious + exploratory. Dạng sau cho biết cần làm gì và move on.

AGENTS.md có 15+ “don’ts” liên tiếp không kèm “do” → agent over-explore, conservative, làm ít việc hơn.

7. Modular code, modular AGENTS.md

Top performer là agent doc mô tả submodule tương đối isolated. Module mid-size (~100 core file), AGENTS.md 100–150 dòng + vài reference → 10–15% gain cross-metric. Ví dụ: UI component của client, standalone service.

AGENTS.md cross-cutting ở root repo underperform so với module-level.

2 failure mode chính

Overexploration trap (context rot)

Failure mode phổ biến nhất. Hai nguyên nhân:

Quá nhiều architecture overview. Agent bị pull vào đọc doc, có khi hàng chục file, để “better understand the architecture”. Load hàng chục/trăm nghìn token context, output xấu đi.

Excessive warnings. 30–50 warnings không kèm alternative → agent đọc từng cái, cố figure out có apply cho task hiện tại không, rồi verify solution chống lại từng warning. Kết cục: đọc migration script, check API version compat, explore auth middleware ngay cả khi task không liên quan gì.

AGENTS.md đè trên đống doc khổng lồ

Trong study, AGENTS.md worst-performing là cái sitting trên top documentation sprawl khổng lồ. Một module có 37 doc liên quan, ~500K ký tự. Module khác có 226 doc, >2MB.

Ở cả hai trường hợp, xoá AGENTS.md đi gần như không thay đổi behavior — agent vẫn tìm và đọc đống doc xung quanh, và đống doc đó mới là vấn đề.

Nếu AGENTS.md của bạn ngon nhưng module có 500K spec xung quanh → spec mới là cái agent đọc. Fix documentation environment, không chỉ entry point.

Bảng pattern theo metric

Discovery rate thực tế

Augment Code trace doc discovery qua hàng trăm session. Số liệu lopsided đủ để shape migration priorities:

• AGENTS.md: discovered tự động 100% ở mọi cấp hierarchy từ working directory (đa số harness)
• Reference từ AGENTS.md: load on demand, đọc trong 90%+ session khi agent có lý do pull in
• README.md ở folder hiện tại: không auto-load, nhưng agent đọc trong 80%+ session khi work trong directory đó
• Nested README.md (sub-folder không phải working dir): chỉ ~40%
• Orphan doc trong _docs/ không có reference: <10%. Một service trong codebase của họ có 30K protocol/throttling/security doc trong _docs/. Agent gần như không bao giờ mở qua hàng chục session.

AGENTS.md là location duy nhất có reliable discovery. Cái gì cần được đọc thì hoặc nằm trong đó, hoặc reference trực tiếp từ đó. Move content vào referenced location thường có leverage cao hơn việc viết thêm doc mới.

Migration playbook

Có nên rename README.md thành AGENTS.md?

Hai file phục vụ audience khác nhau, nhưng có thể reuse. Agent đủ tốt ở codebase summarization rồi nên human-oriented doc ít cần thiết hơn trước. Có thể viết agentic doc from scratch, hoặc reuse README.md. Nếu reuse, trim aggressive. Giữ ngắn, follow pattern trên, cắt bất cứ section nào dành cho human skim.

Khi nào giữ doc cũ

Nếu doc high-quality, current, to-the-point và có example → reuse được. Reference chúng từ module/folder-level AGENTS.md. Đừng put hơn 10–15 reference trong 1 file AGENTS.md, giữ context lean.

Và audit môi trường xung quanh: nếu module có hàng chục architecture doc + spec file, agent sẽ tìm và đọc bất kể bạn có reference hay không. Một AGENTS.md 150 dòng focused đè trên 500K spec sẽ không save được agent khỏi đống spec.

AGENTS.md không phải con đường duy nhất

Agent tìm reference qua grep + semantic search nữa. ~50% search hit trong trace của họ đến từ tool đó, không phải từ reference của AGENTS.md. Nếu giữ legacy doc, đảm bảo doc có code example liên quan + text descriptive searchable. AGENTS.md cho bạn nhiều control hơn về context window, nhưng không phải way in duy nhất.

Study không cover

Focus là one-shot trajectory + khả năng agent finish coding task không human-in-loop. Chưa cover: maintain AGENTS.md theo thời gian, operational/interactive/analytics task. Theo author, các post sau sẽ đi vào.

Dev nên quan tâm vì…

1. Nếu repo của bạn đã có AGENTS.md: đếm số dòng. Nếu >150 và không có reference doc kèm theo, gần như chắc chắn đang gây overexploration.
2. Nếu chưa có: bắt đầu bằng decision table cho stack choice và procedural workflow cho deploy/integration. Hai pattern này có ROI đo được nhất.
3. Nếu codebase có _docs/ đầy spec: agent gần như không bao giờ đọc. Hoặc move vào reference của AGENTS.md, hoặc xoá nếu không cần.
4. Đừng stack “Don’t”: mỗi prohibition phải kèm “Do” cụ thể. Đây là quick win dễ nhất.