- Trong bài đánh giá nhắm vào API Next.js 16, chỉ mục tài liệu
AGENTS.md nằm ở thư mục gốc dự án ghi nhận độ chính xác cao hơn cách tiếp cận dựa trên skills
- Skills là dạng gói tri thức miền mà tác tử sẽ gọi khi cần, nhưng việc gọi không ổn định nên ở cấu hình mặc định chỉ đạt tỷ lệ vượt qua 53%
- Ngược lại, chỉ mục
AGENTS.md được nén xuống 8KB đạt tỷ lệ vượt qua 100% trong mọi bài kiểm tra (Build, Lint, Test)
- Cách làm này cho kết quả ổn định hơn so với việc gọi chủ động nhờ loại bỏ điểm quyết định, luôn sẵn có và giải quyết vấn đề thứ tự
- Người duy trì framework có thể đưa chỉ mục tài liệu khớp phiên bản vào AGENTS.md để nâng cao độ chính xác khi sinh mã
Bối cảnh vấn đề
- Tác tử lập trình AI có hạn chế là dữ liệu huấn luyện dựa trên API phiên bản cũ, nên không thể xử lý chính xác framework mới nhất
- Các tính năng như
'use cache', connection(), forbidden() của Next.js 16 không có trong dữ liệu huấn luyện hiện có của mô hình
- Ngược lại, ở các dự án dùng phiên bản cũ, mô hình cũng có thể đề xuất API mới không hề tồn tại
- Để giải quyết điều này, nhóm đã thử nghiệm cách tiếp cận truy cập tài liệu khớp phiên bản
Hai cách tiếp cận
- Skills: gói tiêu chuẩn mở gom prompt, công cụ và tài liệu lại với nhau, được tác tử gọi và sử dụng khi cần
AGENTS.md: tệp ngữ cảnh thường trực nằm ở thư mục gốc dự án, luôn có thể được tham chiếu trong mọi lượt hội thoại- Hai cách được đánh giá so sánh dựa trên cùng bộ tài liệu Next.js
Giới hạn của cách tiếp cận Skills
- Kết quả đánh giá cho thấy, ở 56% bài kiểm tra skill không được gọi, và tỷ lệ vượt qua mặc định là 53%, không có cải thiện
- Ở một số hạng mục, kết quả thậm chí còn thấp hơn mốc cơ sở (ví dụ: test 58% so với 63%)
- Điều này được chỉ ra là giới hạn hiện tại khi mô hình chưa thể thực hiện việc dùng công cụ một cách ổn định
Thử nghiệm bổ sung chỉ dẫn tường minh
- Khi thêm vào
AGENTS.md chỉ dẫn tường minh “hãy gọi skill trước khi viết mã”, tỷ lệ vượt qua tăng lên 79%
- Tuy nhiên, khác biệt rất nhỏ trong cách diễn đạt chỉ dẫn lại ảnh hưởng lớn tới kết quả
- “Hãy gọi skill trước” → bị cố định vào mẫu trong tài liệu, bỏ sót ngữ cảnh dự án
- “Hãy khám phá dự án rồi gọi skill” → cho kết quả tốt hơn
- Do tính mong manh về ngôn ngữ này, độ tin cậy trong sử dụng thực tế bị đánh giá là thấp
Xây dựng đánh giá đáng tin cậy
- Bài kiểm tra ban đầu thiếu độ tin cậy do prompt mơ hồ và vấn đề xác minh trùng lặp
- Để cải thiện, nhóm đã tăng cường bằng xác minh dựa trên hành vi và các bài test tập trung vào API Next.js 16 chưa có trong dữ liệu huấn luyện
- Các API được kiểm tra chính gồm:
connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh()...
Thử nghiệm với cách tiếp cận AGENTS.md
- Nhóm loại bỏ quá trình lựa chọn của tác tử và chèn trực tiếp chỉ mục tài liệu vào AGENTS.md
- Chỉ mục không chứa toàn bộ tài liệu mà gồm danh sách đường dẫn tài liệu theo từng phiên bản
- Chỉ dẫn bổ sung:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
- Nhằm hướng mô hình ưu tiên suy luận dựa trên tài liệu thay vì dữ liệu đã học trước đó
Kết quả đánh giá
- Khi chèn chỉ mục vào AGENTS.md, tỷ lệ vượt qua đạt 100%
- Build, Lint và Test đều cho kết quả hoàn hảo
- Thống kê so sánh:
- Baseline 53%, Skill mặc định 53%, Skill + chỉ dẫn 79%, AGENTS.md 100%
- Lý do cách ngữ cảnh thụ động vượt trội hơn cách gọi chủ động
- Không có điểm quyết định — thông tin luôn hiện diện
- Tính sẵn có nhất quán — được đưa vào system prompt ở mọi lượt
- Loại bỏ vấn đề thứ tự — không phụ thuộc vào thứ tự khám phá tài liệu
Giải quyết vấn đề dung lượng ngữ cảnh
- Chỉ mục ban đầu là 40KB nhưng đã được nén còn 8KB (giảm 80%)
- Dùng cấu trúc phân tách bằng dấu pipe (
|) để lưu đường dẫn tài liệu và tên tệp với không gian tối thiểu
- Tác tử chỉ đọc các tệp cần thiết trong thư mục
.next-docs/ để sử dụng chính xác thông tin đúng phiên bản
Cách áp dụng
Hàm ý đối với nhà phát triển framework
- Skills vẫn hữu ích, nhưng để cải thiện độ chính xác sinh mã nói chung thì cách làm với AGENTS.md hiệu quả hơn
- Skills phù hợp với các quy trình tập trung vào nhiệm vụ cụ thể như “nâng cấp phiên bản”, “di chuyển sang App Router”
- Khuyến nghị:
- Đừng chờ skills được cải thiện, hãy dùng AGENTS.md ngay
- Chỉ bao gồm chỉ mục tài liệu để giảm tối thiểu ngữ cảnh
- Xác minh bằng đánh giá tập trung vào các API không có trong dữ liệu huấn luyện
- Thiết kế tài liệu theo cấu trúc tìm kiếm phân mảnh chi tiết
- Mục tiêu là chuyển từ suy luận dựa trên tiền huấn luyện sang suy luận dựa trên truy xuất, và
AGENTS.md là cách triển khai điều này ổn định nhất
4 bình luận
> Tác nhân AI viết mã có hạn chế là dựa trên dữ liệu huấn luyện dùng API phiên bản cũ nên không thể xử lý chính xác các framework mới nhất.
Dùng Context7 thì vấn đề trên được giải quyết phần nào.
https://context7.com
Là vì context7 không hiệu quả nên mới dùng hai cách ở trên...
Tôi hiểu ý bạn muốn nói, nhưng thay vì mỗi lần đều phải tổng hợp rồi đưa vào AGENTS.md hoặc Skills từng liên kết tài liệu mới nhất của mọi framework/thư viện đang dùng, tôi nghĩ dùng context7 như một công cụ hỗ trợ cũng không hẳn là lựa chọn tệ.
Ngoài ra, cả bài trên GeekNews lẫn bài gốc của Vercel đều không nhắc đến context7. Tôi để lại bình luận này vì có vẻ như bạn đã diễn giải nội dung đi trước khoảng nửa bước.
(Xin nói thêm, việc có thể tiết kiệm token bằng Skills hoặc AGENTS.md được viết tốt là điều đã được biết đến rộng rãi, và bản thân tôi cũng hiểu rõ điều đó.)
Ý kiến trên Hacker News
Mô hình không phải AGI. Nó chỉ là trình tạo văn bản, được huấn luyện để tạo ra các hiệu ứng như chỉnh sửa file hay gọi công cụ
Mô hình không phải “hiểu” kỹ năng của người dùng rồi sử dụng, mà tạo ra loại văn bản đó nhờ học tăng cường (RL) dựa trên các ví dụ do con người tạo ra và nhật ký sử dụng
Lý do nó không luôn dùng kỹ năng là vì vẫn chưa được học đủ nhiều trường hợp như vậy. Nếu ép bằng RL thì ngược lại còn có thể khiến mô hình ngu đi
Hiện tại chúng ta đang tích lũy nhật ký sử dụng kỹ năng để các mô hình tương lai học tốt hơn về thời điểm cần dùng kỹ năng
AGENTS.md đơn giản chỉ là ngữ cảnh. Mô hình ngay từ đầu đã được huấn luyện để làm theo ngữ cảnh
Frontmatter của kỹ năng cuối cùng cũng được đưa vào ngữ cảnh, nên nếu AGENTS.md hoạt động tốt hơn thì đó là do khác biệt trong cách trích xuất và bơm thông tin kỹ năng
Một số agent có thể dùng mô hình nhỏ hơn (ví dụ: Haiku) để quyết định nên truyền thông tin kỹ năng nào sang mô hình lớn hơn (ví dụ: Sonnet, Opus)
Cuối cùng, điểm cốt lõi là thông tin nào đi vào “prompt thô”
Hữu ích nhưng không hoàn hảo. Bản thân công nghệ GPT có vẻ đã bước vào giai đoạn chững hiệu năng
Phần sẽ còn được cải thiện về sau là các hệ thống bổ trợ như kỹ năng. Nhưng tính năng kỹ năng hiện tại được triển khai vẫn kém hơn việc viết trực tiếp AGENTS.md
Trong bài đánh giá có kết quả cho thấy ở 56% trường hợp, kỹ năng chưa từng được gọi lấy một lần. Tức là có tài liệu nhưng không dùng. Kèm theo câu đùa “thế là vượt qua Turing test rồi…”
Khác biệt là AI chấp nhận chỉ thị sửa đổi mà không có tự ái
Chưa tới mức lập trình viên senior, nhưng vẫn nghe lời hơn junior
Phát hiện cốt lõi là nén (compression) các con trỏ tài liệu có hiệu quả
Khó đọc với con người, nhưng với LLM thì đây là cấu trúc tham chiếu trực tiếp và hiệu quả
Về sau, thay vì các heuristic như agents.md/claude.md/skills.md, có khả năng một định dạng chỉ mục nén luôn được tải sẽ trở thành tiêu chuẩn
Cũng có thể tái sử dụng bộ test API để kiểm chứng hiệu năng code của LLM
Khi việc áp dụng LLM ngày càng lớn, thư viện và API cũng cần tiến hóa theo hướng này
Trong Antigravity (= dựa trên GEMINI.md), đã yêu cầu tuân theo quy tắc AGENTS.md nhưng vẫn bị phớt lờ
Ngược lại, prompt kiểu “hãy kiểm tra xem dự án có AGENTS.md không” thì lúc nào cũng hoạt động
Đây là hiện tượng kỳ lạ giống thời xưa khi “let’s think step by step” có thể kích hoạt chain-of-thought
Nếu đưa AGENTS.md trực tiếp vào system prompt thì nó luôn nằm trong ngữ cảnh
Nhưng nhét mọi kỹ năng vào mỗi lần đều rất lãng phí. Vì vậy cần cách tiếp cận chỉ gọi khi cần, như advanced tool use của Anthropic
Cuối cùng đây là bài toán cân bằng giữa ngữ cảnh và chi phí. Nếu còn dư sức chứa thì nén vào AGENTS.md là hiệu quả
Các agent tự quản lý ngữ cảnh kiểu này có lẽ sẽ tiến bộ mạnh trong năm nay
Tỷ lệ tuân thủ kỹ năng của Claude khá thấp
Tôi cũng đang làm trong khu vực tương tự. Tôi muốn đánh giá cấu trúc scaffolding của dự án ảnh hưởng thế nào tới kết quả của Claude Code/Opencode
Nhưng cách test của Vercel không rõ ràng nên khó so sánh
AGENTS.md không phải thứ hoàn toàn khác kỹ năng, mà là phiên bản đơn giản hóa của kỹ năng
Điều cốt lõi là chất lượng thiết kế kỹ năng, tức là giảm thiểu số bước AI phải đi qua để tìm đúng thông tin
Càng ít bước thì lỗi tích lũy càng giảm
Và để giảm lãng phí token, các file lớn chỉ được đưa vào system prompt một lần
Mỗi lần blog so sánh prompt engineering, điều tôi luôn thắc mắc là họ chạy đúng một lần hay lặp lại nhiều lần
Kết quả của LLM không ổn định ngay cả với cùng một đầu vào
Phần lớn tạo cảm giác như dữ liệu mức giai thoại được gói lại cho giống khoa học
Nhưng nếu benchmark cẩn thận thì ít lượt xem, còn làm qua loa thì traffic blog tăng gấp 9 lần
Cấu trúc khuyến khích méo mó mới là vấn đề
Cũng có cách tốt hơn AGENTS.md
Tạo một thư mục
.context, đặt các liên kết tượng trưng tới tài liệu liên quan của dự án (README, tài liệu dependency, v.v.) vào đó, rồi luôn tải nó vào ngữ cảnhLàm vậy thì ngay từ đầu LLM đã có đủ thông tin cần thiết, nên có thể tăng hiệu năng và giảm chi phí
_vendorcòn hữu ích hơn nhiềuLLM có thể trực tiếp phân tích code để hiểu cách nó hoạt động
Đây là kinh nghiệm tôi có được khi tự làm agent tùy chỉnh của mình
Sau khi đưa read/write_file vào trạng thái và hiển thị nó trong system prompt, mọi thứ hoạt động tốt hơn nhiều
Giờ tôi đang cố chứng minh điều đó bằng đánh giá định lượng (evals). Theo cảm nhận thì hiệu năng rất tốt