Hướng Dẫn Sử Dụng AGENTS.md Để Quản Lý AI Trong Monorepo

Tại Sao Tài Liệu Điều Hướng Quan Trọng

Một tài liệu AGENTS.md được duy trì tốt là hợp đồng giữa mã nguồn của bạn và hệ sinh thái agent. Nó giúp trả lời các câu hỏi:

• Tôi có thể yêu cầu agent này làm gì ở đây?
• Công cụ, quy ước hoặc quy trình nào là trong phạm vi?

Một bộ tài liệu điều hướng tốt giúp AI trở nên dự đoán và đáng tin cậy hơn. Nó hướng dẫn AI tuân theo các mẫu của bạn, hiểu kiến trúc của bạn và tạo ra mã phù hợp với mã nguồn của bạn. Nó không thay thế các thực hành tốt về AI, nhưng cải thiện trải nghiệm OOTB.

Hãy nhớ rằng tài liệu này được viết cho các agent AI, không phải cho con người. Giữ cho chúng ngắn gọn và đi thẳng vào vấn đề. Ví dụ, hãy xem hướng dẫn prompting cho GPT5-codex và sự súc tích của các prompt. Số ký tự thêm vào cửa sổ ngữ cảnh của agent, vì vậy sự súc tích cho phép chúng làm nhiều hơn.

Cách Kiểm Tra Tài Liệu Điều Hướng

Việc kiểm tra tài liệu điều hướng tương tự như việc kiểm tra hướng dẫn onboarding. Bạn cần đi qua từng bước một.

1. Tạo một bộ sưu tập các prompt ví dụ.
   Hãy nghĩ đến tất cả các nhiệm vụ mà một kỹ sư có thể thực hiện trong monorepo của bạn, đảm bảo bạn có một hoặc hai prompt ví dụ cho mỗi nhiệm vụ.
   Ví dụ: “Di chuyển một mẫu email sang framework mới của chúng tôi. Đây là mã trước đó: [...]”

2. Lưu trữ chúng ở đâu đó bền vững.
   Một tài liệu Google chia sẻ hoặc trang Confluence hoạt động tốt—đây là những công cụ nhẹ, có thể chỉnh sửa và truy cập.

3. Chạy các prompt với tất cả các công cụ mà bạn hỗ trợ.
   Thử nghiệm Claude Code, Cursor, Codex CLI, hoặc bất kỳ agent nào mà nhóm của bạn hỗ trợ. Các agent khác nhau hoạt động khác nhau, tốt nhất là kiểm tra trên nhiều nền tảng.

4. Quan sát các điểm gãy.
   Agent đã bị lạc ở đâu? Kiến thức nào mà nó thiếu để hoàn thành nhiệm vụ một cách chính xác? git reset --hard, chỉnh sửa tài liệu điều hướng của bạn và thử lại cho đến khi agent của bạn thực hiện thành công prompt thử nghiệm.

Điều này có thể có vẻ đơn giản, nhưng sự đơn giản là một tính năng. Bạn sẽ phát hiện ra những khoảng trống thực sự nhanh hơn nếu bạn không làm quá phức tạp một khuôn khổ đánh giá. Theo thời gian, bạn có thể bắt đầu giới thiệu các đánh giá tự động—nhưng đừng để điều đó cản trở bạn bắt đầu.

AGENTS.md và Các Biến Thể Của Nó

Hầu hết các công cụ ngày nay đều công nhận AGENTS.md như một tiêu chuẩn.

Một ngoại lệ đáng chú ý vào thời điểm viết là Claude code của Anthropic chỉ hỗ trợ CLAUDE.md. (Hy vọng rằng điều này sẽ sớm thay đổi)

Để hỗ trợ Claude code, tôi khuyên bạn không nên sử dụng symlink. Thay vào đó, tôi tiếp cận như sau:

echo "Đọc @AGENTS.md" > CLAUDE.md

Tôi thích cách tiếp cận này vì nó cho phép chúng ta linh hoạt mở rộng với các tính năng cụ thể của Claude (như sub-agents).

repo-root/
├── AGENTS.md
├── CLAUDE.md          # chứa "Đọc @AGENTS.md"
└── src/
    └── ...

AGENTS.md Gốc Là Router Của Bạn

Các tài liệu AGENTS.md lồng nhau là khuyến nghị mặc định cho monorepo. Điều này có nghĩa là AGENTS.md gần nhất với tệp đã chỉnh sửa sẽ thắng, nhưng tôi thấy cách tiếp cận này khá hạn chế nếu chỉ dựa vào điều đó! Một mặt, điều này chỉ hoạt động nếu làm việc từ một thư mục con/tệp cụ thể hoặc nếu người dùng @ tham chiếu đến tệp một cách thủ công. Chỉ làm như vậy:

1. Giới hạn quyền truy cập của agent vào các ví dụ/mẫu trong phần mã còn lại.
2. Người dùng cần biết từ thư mục con nào để làm việc; làm cho việc phát hiện trở nên khó khăn hơn.

Chúng ta có thể làm cầu nối khoảng cách đó bằng cách sử dụng một AGENTS.md gốc để từ từ tiết lộ thông tin cho agent của bạn. Ví dụ:

# Nhiệm Vụ

Để tạo một email, đọc @emails/AGENTS.md
Để tạo một dịch vụ Go, đọc @go/services/AGENTS.md
Để thêm unit tests, đọc @.agents/unit-tests.md

Cứ khi nào có thể, chúng tôi thích thêm tài liệu vào một AGENTS.md liên quan đến nội dung của một thư mục. Nhưng một thư mục .agents/ chung để thu thập các loại nội dung khác là rất quý giá cho bối cảnh tổng quát hơn.

Ví dụ về cấu trúc thư mục:

repo-root/
├── AGENTS.md
├── emails/
    └── AGENTS.md
├── go/
    └── services/
        └── AGENTS.md
└── .agents/
    └── unit-tests.md

Như vậy, AGENTS.md gốc trở thành một bản đồ, chỉ dẫn các agent đọc tài liệu phù hợp dựa trên nhiệm vụ của họ. Điều này giúp rất nhiều trong việc quản lý cửa sổ ngữ cảnh khi làm việc với các nhiệm vụ kéo dài lâu hơn.

Còn Tài Liệu Được Duy Trì Ở Nơi Khác Thì Sao?

Ở mức cao, không có gì sai khi tham chiếu tài liệu bên ngoài.

Để tạo một email, sử dụng máy chủ Atlassian MCP để đọc https://...

Nhược điểm là có nguy cơ làm đầy cửa sổ ngữ cảnh với tài liệu được viết cho con người. Nhưng vì bạn đang kiểm tra các prompt cốt lõi của mình, bạn sẽ dễ dàng thấy nếu bạn đang khiến agent bị nhầm lẫn.

Chúng tôi khuyến nghị một cách tiếp cận thực dụng ban đầu, và mở rộng sau đó.

Ngoài ra, bạn có thể yêu cầu agent tóm tắt nội dung của tài liệu bên ngoài. Đặt đầu ra vào một tệp AGENTS.md, và bảo agent rằng họ có thể tìm kiếm thêm thông tin nếu cần tại URL đã cho.

Điều này sẽ cần được giữ cập nhật như bất kỳ tài liệu nào. Và đó là điều mà chúng tôi hy vọng sẽ giao cho các agent tự động trong thời gian tới...

Đưa Nhóm Nền Tảng Của Bạn Cùng Đi

Tại một số điểm, các nhóm kinh nghiệm phát triển tập trung không thể là chuyên gia trong mọi thứ. Các nhóm nền tảng và sản phẩm phải sở hữu nội dung điều hướng của riêng họ.

• Nhóm trung tâm cung cấp cấu trúc (AGENTS.md, routing, cấu hình chia sẻ).
• Mỗi nhóm đối tác điền vào hướng dẫn cụ thể theo miền (ví dụ: “cách thêm khả năng quan sát vào dịch vụ backend python”).
• Điều này chuyển giao chuyên môn gần hơn đến nơi công việc diễn ra, trong khi vẫn duy trì một cấu trúc điều hướng nhất quán.

Hỗ Trợ Tùy Chỉnh Của Người Dùng

Không phải kỹ sư nào cũng làm việc một cách giống nhau. Tùy chỉnh là điều quan trọng.

1. Tùy chọn toàn cầu. Ví dụ: giọng điệu, ưu tiên công cụ. Đặt những điều này trong ~/AGENTS.md.
2. Ghi đè cụ thể theo repo của người dùng. Ví dụ: dịch vụ nào họ sở hữu, phạm vi của họ, v.v. Giới thiệu AGENTS.local.md. .gitignore nó. Và chỉ dẫn AGENTS.md gốc của bạn kiểm tra trước: Nếu có, ưu tiên hướng dẫn bên trong @AGENTS.local.md

repo-root/
├── AGENTS.md
└── AGENTS.local.md   # .gitignored, cụ thể cho người dùng

Kết Luận

Tài liệu điều hướng vẫn là một lĩnh vực khá mới đối với chúng tôi. Vì vậy, chúng tôi rất mong muốn được học hỏi từ cộng đồng!

• Bạn cấu trúc tài liệu điều hướng trong monorepo của mình như thế nào?
• Bạn chia sẻ các cấu hình khác (ngoài điều hướng) khi nào/thế nào?
• Bạn đã thấy các agent bị lạc ở đâu nhiều nhất?

Không gian này đang phát triển nhanh chóng—các thực tiễn tốt nhất sẽ đến từ cộng đồng cũng như từ các công cụ. Đây chỉ là một cách tiếp cận, và sẽ tiếp tục phát triển.