Khi các tác nhân AI trở thành “bộ não thứ hai” của lập trình viên, một vấn đề lớn sẽ nảy sinh:

Làm thế nào chúng ta có thể giao tiếp hiệu quả với những “đồng nghiệp kỹ thuật số” ngày càng thông minh này?

Copilot , Devin , Claude Code , Gemini CLI , Codex … Mỗi tác nhân lập trình đều có tính khí riêng khi chiến đấu.

Để AI hoạt động theo đúng thông số kỹ thuật của dự án, các nhà phát triển phải nhồi nhét nhiều tệp cấu hình như .cursorrules, AGENT.md, v.v. vào cơ sở mã.CLAUDE.md

Danh mục dự án ngày càng phình to và chi phí bảo trì ngày càng tăng.

Như một nhà phát triển trên X (trước đây là Twitter) đã phàn nàn: “Thật điên rồ, chúng ta đang làm cái quái gì vậy?”

Bức ảnh này mô tả chính xác tình trạng hiện tại của các công cụ lập trình AI: phân mảnh và độc lập, có thể được gọi là “Tháp Babel”.

Tuy nhiên, sự hỗn loạn này có thể sắp kết thúc.

OpenAI vàGoogleđã hợp tác với một số nhà cung cấp trong hệ sinh thái lập trình AI, bao gồmFactory, Sourcegraph/Amp và Cursor , để ra mắt một tiêu chuẩn mới, đơn giản và mở:

AGENTS.md

Mục tiêu của nó rất rõ ràng: thay thế các tệp cấu hình dành riêng cho nhà sản xuất bằng một tài liệu thống nhất, rõ ràng, cung cấp cho các tác nhân lập trình AI một cách có thể dự đoán được để hiểu và vận hành các dự án phần mềm.

Nói cách khác, đó là cung cấp cho AI Agent một “thông số kỹ thuật dự án” chung .

Liệu tài liệu nhỏ này có phải .mdlà liều thuốc tiên để giải quyết những thách thức trong cộng tác AI, hay chỉ là một sự tái tạo bánh xe? Liệu nó có thực sự thống nhất bối cảnh lập trình AI và trở thành nền tảng then chốt cho một mô hình lập trình cộng tác mới giữa con người và AI?

Hôm nay, chúng ta sẽ cùng tìm hiểu AGENTS.mdcâu chuyện đằng sau nó, các chi tiết kỹ thuật và những cuộc thảo luận nảy sinh từ nó.

READMENó dành cho con người để xem, AGENTS.md dành cho AI để xem

Nói một cách đơn giản, AGENTS.mdđó là ” README.md để các Đại lý đọc “ .

AGENTS.mdĐây là một tệp Markdown đơn giản, thường được đặt trong thư mục gốc của kho lưu trữ mã, cùng tồn tại với các tệp quen thuộc README.mdvà CONTRIBUTING.md.

Chúng ta đều biết README.mdrằng nó được viết cho các nhà phát triển, và nội dung thường là phần giới thiệu dự án, hướng dẫn bắt đầu nhanh và quy trình đóng góp. Nhưng đối với “đồng nghiệp kỹ thuật số” của chúng ta – những trợ lý lập trình AI, những thông tin này vẫn còn quá ít.

Nó bao gồm cụ thể các chi tiết kỹ thuật và hướng dẫn vận hành mà các nhà phát triển thường không quan tâm, nhưng lại rất cần thiết để các tác nhân AI hoàn thành nhiệm vụ .

AGENTS.mdMục tiêu là thu thập thông tin theo ngữ cảnh có thể quá dài hoặc không liên quan đến người đóng góp nhưng lại rất quan trọng đối với AI vào một tệp chuyên dụng.

Một AGENTS.mdví dụ chính thức về chủ nghĩa tối giản như sau:

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Như bạn thấy, bản thân tệp rất đơn giản, chỉ là một danh sách hướng dẫn và quy tắc. Ba nguyên tắc cốt lõi của thiết kế này bao gồm:

1. Vị trí cố định : Tên tệp và vị trí lưu trữ vẫn nhất quán, giúp AI Agent dễ dàng tự động tìm thấy tệp hơn.
2. Đọc đồng thời giữa người và máy : Định dạng này nhẹ và có thể dễ dàng được cả con người và công cụ đọc và phân tích.
3. Khả năng mở rộng linh hoạt : Cấu trúc đủ linh hoạt để thích ứng với nhiều ngôn ngữ lập trình, khuôn khổ và thậm chí cả kho lưu trữ mã phức tạp.

Nó cũng rất dễ sử dụng AGENTS.md, chỉ cần ba bước:

1. Trong thư mục gốc của kho lưu trữ mã, hãy tạo một AGENTS.mdtệp có tên .
2. Thêm thông tin quan trọng vào tệp có thể giúp AI hoạt động hiệu quả, bao gồm nhưng không giới hạn ở tổng quan dự án, lệnh xây dựng và kiểm tra, kiểu mã, hướng dẫn kiểm tra, các cân nhắc về an toàn, v.v.
3. Thêm các hướng dẫn bổ sung khác. Hãy tưởng tượng bạn có một đồng nghiệp mới và bạn có thể đưa ra mọi thứ bạn muốn nói với anh ấy/cô ấy. Ví dụ: Commitđịnh dạng thông tin, Pull Requesthướng dẫn, biện pháp phòng ngừa khi xử lý các tập dữ liệu lớn, các bước triển khai, v.v.

Lồng ghépAGENTS.md cũng được hỗ trợ cho các kho lưu trữ lớn . Bạn có thể đặt thêm các tệp vào các gói quan trọng . Khi Agent hoạt động, nó sẽ tự động đọc tệp gần nhất với thư mục tác vụ hiện tại, cung cấp hướng dẫn chi tiết hơn.AGENTS.md

Theo các nguồn tin chính thức, cơ sở mã chính của OpenAI hiện có 88AGENTS.md tệp, cho thấy tính thực tiễn của nó trong các dự án phức tạp.

Thảo luận cộng đồng: Có cần thiết hay không?

AGENTS.mdSau khi được đề xuất, nó đã gây ra cuộc tranh luận sôi nổi trong cộng đồng nhà phát triển.

Tranh luận 1: AGENTS.mdvs.CONTRIBUTING.md

Cuộc tranh luận cốt lõi là: Chúng ta có thực sự cần một văn bản mới không? README.mdHay CONTRIBUTING.mdnó chưa đủ?

Những tiếng nói đối lập: Ý định ban đầu của AI và sự thống nhất của tài liệu

Nhiều nhà phát triển tin rằng điều này đi ngược lại mục đích của AI. Vì năng lực cốt lõi của LLM là hiểu ngôn ngữ con người, chúng ta nên tập trung vào việc tối ưu hóa tài liệu cho con người và để AI tự thích nghi, thay vì cung cấp đào tạo chuyên biệt cho AI.

Toàn bộ vấn đề này đáng lẽ phải được CONTRIBUTING.mdgiải quyết trong . AGENTS.mdNội dung trong đó không khác gì những gì người đóng góp muốn biết.

Quan điểm này cho rằng AGENTS.mdsự xuất hiện của , đơn giản là do sự bỏ bê lâu dài việc viết tài liệu giới thiệu rõ ràng cho các nhà phát triển mới .

Phải đến khi AI Agents xuất hiện thì việc thiếu tài liệu này mới ảnh hưởng trực tiếp đến hiệu quả phát triển, và mọi người mới bắt đầu chú ý. Về cơ bản, đây là một tài liệu được viết muộn CONTRIBUTING.md.

Lý do hỗ trợ: Sự khác biệt cơ bản giữa con người và AI

Tuy nhiên, những người ủng hộ đã đưa ra một lý do thực tế thuyết phục hơn, cốt lõi là có sự khác biệt cơ bản về nhu cầu, sự hiểu biết và mô hình giao tiếp giữa con người và AI .

1. Phong cách viết và độ chính xác : Trong AGENTS.mdmột tài liệu, bạn có thể nhấn mạnh các quy tắc bằng những chỉ dẫn trực tiếp, thậm chí thẳng thừng, như “TUYỆT ĐỐI KHÔNG BAO GIỜ làm điều gì đó”. AI yêu cầu những chỉ dẫn rõ ràng, trung lập như vậy. Tuy nhiên, việc viết những chỉ dẫn như vậy trong một tài liệu dành cho đồng nghiệp con người có thể gây hiểu lầm nghiêm trọng. Con người có thể hiểu được tầm quan trọng của những gợi ý tinh tế, nhưng AI thì không.
2. Mức độ chi tiết và chi phí theo ngữ cảnh : Tài liệu dành cho các tác nhân phải cực kỳ súc tích , vì nội dung quá nhiều sẽ tiêu tốn các mã thông báo API có giá trị, làm tăng chi phí và thậm chí làm giảm chất lượng đầu ra. Đối với tài liệu kỹ thuật nội bộ dành cho con người, chúng tôi nỗ lực đạt được độ hoàn thiện 100% . AGENTS.mdNó giống như một tập dữ liệu được sắp xếp hợp lý, tối ưu hóa, được thiết kế riêng để cung cấp dữ liệu cho mô hình.
3. Điểm mù kiến ​​thức khác nhau : AI và con người có những điểm mù kiến ​​thức khác nhau. Ví dụ, một mô hình mới có thể đã hoàn toàn quen thuộc với API của một khuôn khổ mã nguồn mở nhất định, vì vậy bạn không cần phải AGENTS.mdnhắc lại ở đây. Tuy nhiên, đối với một nhân viên mới, tài liệu API này là tài liệu bắt buộc phải đọc. Ngược lại, một số “quy tắc bất thành văn” của một dự án, chỉ các thành viên trong nhóm mới biết, lại là điểm mù hoàn toàn đối với AI và phải được ghi chép rõ ràng.

Tranh luận 2: Tệp so với Thư mục, Đơn khối so với Có cấu trúc

Một chủ đề thảo luận quan trọng khác là AGENTS.mdcách tổ chức Markdown. Các nhà phát triển giàu kinh nghiệm chỉ ra rằng đối với các dự án lớn và phức tạp, một tệp Markdown khổng lồ sẽ nhanh chóng trở nên khó bảo trì.

Đối với các dự án phức tạp, “một tệp khổng lồ” có thể không phải là giải pháp tốt nhất. Nhiều nhà phát triển khuyến nghị cấu trúc thư mục được tổ chức tốt hơn, chẳng hạn như .agentsthư mục ẩn:

.agents/
├── index.md
├── auth.md
├── performance.md
├── code_quality.md
└── testing.md

Lợi ích của việc làm này rất rõ ràng:

• Cấu trúc rõ ràng : dễ dàng cho con người và AI duy trì.
• Độ chính xác theo ngữ cảnh : AI Agent chỉ có thể tải .mdcác tệp có liên quan dựa trên yêu cầu của tác vụ, thay vì nhồi nhét tất cả các quy tắc vào ngữ cảnh, do đó tiết kiệm mã thông báo và cải thiện độ chính xác của phản hồi.

Tranh luận 3: Ô nhiễm thư mục gốc

Đây là một vấn đề cũ đã gây khó khăn cho cộng đồng nhà phát triển trong nhiều năm. Bất cứ khi nào một công cụ hoặc tiêu chuẩn mới xuất hiện, nó thường tạo các tệp riêng trong thư mục gốc của dự án, khiến thư mục gốc ngày càng trở nên lộn xộn.

Các dự án nên ngừng tự tạo các tệp và thư mục gốc. Đừng làm ô nhiễm thư mục gốc!

Một số nhà phát triển đã đề xuất rằng nên tuân thủ các quy ước hiện hành như .well-known/RFC 8615 hoặc RFC 8615 .config/để tập trung toàn bộ cấu hình công cụ và siêu dữ liệu vào một vị trí duy nhất. Điều này phản ánh mục tiêu của các nhà phát triển là hướng đến sự sạch sẽ và chuẩn hóa trong các dự án của họ.

Tranh luận 4: kế thừa hay ghi đè?

AGENTS.mdViệc lồng nhau trong các thư mục con được hỗ trợ, nhưng quy tắc là “tệp gần đây nhất sẽ nằm trước” .

Một nhà phát triển đã chỉ ra một rủi ro tiềm ẩn:

Các tệp ngữ cảnh trong thư mục con sẽ thay thếREPLACE thay vì cải thiện các tệp bên trên chúng augment. Tôi cho rằng sự khác biệt này rất nguy hiểm vì người dùng có thể không nhận thấy sự khác biệt.

apps/api/Điều này có nghĩa là nếu bạn đặt ./configure_root trong một thư mục con , Agent sẽ hoàn toàn bỏ qua .configure_root của thư mục gốc AGENTS.mdkhi xử lý các tệp trong thư mục đó . Điều này khác với hành vi “thừa hưởng và ghi đè” mà nhiều nhà phát triển mong đợi, và có thể dẫn đến những hậu quả không mong muốn.AGENTS.md

Tranh luận 5: AI có nên thông minh hơn không?

Cũng có quan điểm cho rằng AGENTS.mdbản thân nó là “sản phẩm của thời kỳ chuyển tiếp”.

Chúng ta đang trong giai đoạn chuyển tiếp, khi các tác nhân ngày nay cần sự hướng dẫn chuyên biệt vượt xa những gì con người cần để hiểu một cơ sở mã. Nhưng trong tương lai gần, tôi không nghĩ họ sẽ cần điều đó nữa. Điểm hấp dẫn của LLM nằm ở chỗ nó có thể đọc và hiểu ngôn ngữ của chúng ta, và chúng ta nên thiết kế nó ở mức độ đó.

Quan điểm này cho rằng mục tiêu cuối cùng của AI là hiểu các tài liệu ngôn ngữ tự nhiên của con người, thay vì dựa vào AI được thiết kế đặc biệt agents.md. Chúng ta nên để AI thích nghi với cách con người giao tiếp, chứ không phải ngược lại.

Lợi ích bất ngờ: AI đang thúc đẩy sự hợp tác cho các tài liệu chuẩn hóa

Giữa tất cả các cuộc tranh luận, một sự đồng thuận thú vị dần xuất hiện: AGENTS.md đang khéo léo “thu hút” các nhà phát triển bắt đầu viết và duy trì tài liệu một cách nghiêm túc.

Trước đây, việc viết tài liệu hướng dẫn thường bị coi là một công việc tẻ nhạt với thời gian hoàn vốn dài. Nhiều nhà phát triển quá lười biếng để viết vì họ biết rằng sẽ chẳng ai đọc nó .

Nhưng bây giờ, tình hình đã hoàn toàn khác.

Như một nhà phát triển đã nói:

Về tài liệu hướng dẫn, tôi nghĩ mọi người quá lười đọc nên không ai có động lực viết. Với Agent, tôi biết rằng nếu tôi viết một quy tắc CLAUDE.mdmột lần, nó sẽ được hàng ngàn phiên bản Agent đọc trong vòng một tuần. Đó chính là động lực để viết tài liệu hướng dẫn.

Theo góc nhìn này, việc viết tài liệu cho con người có tỷ lệ đầu vào/đầu ra rất thấp. Tuy nhiên, việc viết tài liệu cho một tác nhân AI mang lại lợi ích ngay lập tức và chắc chắn—tác nhân sẽ tuân thủ nghiêm ngặt mọi hướng dẫn của bạn.

Phản hồi mang tính quyết định này thúc đẩy mạnh mẽ các nhà phát triển duy trì “sổ tay hướng dẫn sử dụng máy” này.

Khi giá trị của tài liệu có thể được chứng minh ngay lập tức và trực quan thông qua hiệu quả của trợ lý AI, động lực để viết tài liệu chất lượng cao sẽ cao hơn bao giờ hết. Đây có lẽ là “tác dụng phụ” bất ngờ và giá trị nhất của tiêu chuẩn AGENTS.md .

Điều này cũng giống như việc khuyến khích các nhà phát triển hình thành thói quen duy trì tài liệu tốt. Dù con người hay AI cuối cùng được hưởng lợi thì kết quả vẫn tốt.

Đi sâu hơn nữa: Chúng ta có đang định hình lại thế giới số cho AI không?

Vượt ra ngoài cuộc tranh luận về các chi tiết kỹ thuật AGENTS.md, sự xuất hiện của AI có thể tiết lộ một xu hướng lớn hơn: để cộng tác tốt hơn với AI, con người đang tích cực chuyển đổi các cấu trúc thông tin hiện có để khiến chúng “dễ đọc bằng máy” hơn.

Một nhà phát triển đã đưa ra một phép so sánh:

Tôi ngờ rằng khi AI ngày càng được tích hợp sâu hơn vào xã hội, các phương pháp có thể đọc được bằng máy sẽ trở thành tiêu chuẩn. Một ví dụ điển hình là lái xe tự động và luật pháp/bối cảnh địa phương. Ví dụ, một biển báo giao thông có nội dung: “Cấm rẽ khi đèn đỏ từ 7:00 sáng đến 9:00 sáng vào các ngày học”.
Xe tự hành cần biết: Tôi đang ở đâu? Trường này có những ngày nào? Ngày giờ hiện tại là mấy giờ? … Một cách tiếp cận thực tế hơn là các thành phố nên đơn giản hóa luật lệ (làm cho chúng ít phụ thuộc vào ngữ cảnh hơn) hoặc cung cấp một số thông tin có thể đọc được bằng máy trên các biển báo (ví dụ: mã QR).

AGENTS.mdĐây là “mã QR” trong lĩnh vực phát triển phần mềm.

Một ví dụ khác là llms.txt vốn rất phổ biến trước đây, cung cấp nội dung web theo định dạng thân thiện với AI.

Chúng ta đang dần chuyển đổi từ một thế giới được thiết kế cho con người sang một thế giới nơi con người và máy móc cùng tồn tại. Trong thế giới mới này, thông tin không chỉ phải dễ hiểu đối với con người mà còn phải được máy móc diễn giải một cách hiệu quả và chính xác.

Kết luận: Một bước nhỏ hướng tới mô hình hợp tác mới giữa con người và máy móc

AGENTS.mdSự ra đời của là tín hiệu cho thấy hệ sinh thái phát triển phần mềm AI đang trưởng thành và chuẩn hóa.

Giải pháp này cố gắng giải quyết một điểm yếu chung và xây dựng sự đồng thuận giữa các công ty lớn trong ngành thông qua một giải pháp mở, đơn giản. Mặc dù chưa hoàn hảo và chưa nhận được sự hỗ trợ đầy đủ từ tất cả các nhà sản xuất chính (đặc biệt là Anthropic), nhưng nó vẫn chưa hoàn hảo.

Bất kể hình thức cuối cùng của nó là gì, AGENTS.mdcuộc thảo luận xoay quanh chủ đề này đã vô cùng giá trị. Nó thôi thúc chúng ta suy nghĩ sâu sắc: Trong thời đại mà các kỹ sư con người và các tác nhân AI làm việc song song, chúng ta nên xây dựng các giao thức truyền thông và chuẩn mực hợp tác mới như thế nào?

Khi con người bắt đầu chiều theo cách hiểu của máy móc, liệu đây có phải là sự thỏa hiệp bất lực hay là sự tiến hóa tất yếu?

Hiện tại, AGENTS.mdđây có vẻ là bước tiến vững chắc hướng tới một tương lai có trật tự, hiệu quả và chuẩn hóa hơn.

Cũng giống như con người đã phát minh ra các công cụ và tiêu chuẩn mới để truyền tải thông tin chính xác hơn, từ ngôn ngữ nói đến văn bản viết và sau đó là dữ liệu có cấu trúc ngày nay, đây AGENTS.mdcó lẽ chỉ là “hiến chương hợp tác giữa con người và máy móc” trên chặng đường dài này.

Tương lai của nó phụ thuộc vào sự chung tay xây dựng của toàn thể cộng đồng.

Bạn nghĩ gì về AGENTS.md ? Bạn nghĩ đây có phải là hướng đi tương lai hay chỉ là giải pháp tạm thời? Hãy cho chúng tôi biết trong phần bình luận nhé.