Điểm đau: Sao AI viết code cứ lăn ra ở cùng một chỗ

Ai dùng Cursor, Windsurf hay Claude Code để viết dự án đều trải qua một kiểu sập nguồn giống nhau: AI phun ra cả đoạn code, bạn copy paste chạy thử — build lỗi, test đỏ vạch, cài dependency nhầm chỗ. Vấn đề không nằm ở trình độ AI, mà ở chỗ nó không hề biết “luật ngầm” của dự án bạn.

AGENTS.md là một file Markdown đặt ngay thư mục gốc dự án, viết riêng cho AI đọc, bảo nó build thế nào, test ra sao, tuân theo quy chuẩn gì. README.md viết cho người — nhồi nhét giới thiệu dự án, hướng dẫn đóng góp, câu chuyện thương hiệu. AI đọc mấy thứ này giống như nhân viên mới vào ngày đầu được phát một cuốn brochure công ty rồi bị bắt viết code ngay — nó biết công ty làm gì, nhưng không biết lệnh build, không biết chạy test thế nào, không biết rule ESLint ra sao. Hệ quả là bạn cứ phải sửa đi sửa lại trong khung chat: “xài pnpm chứ không phải npm”, “test nằm ở packages/web”, “quên chạy lint rồi”. Sửa trăm lần như vậy, dự án vẫn loạn.

Thiệt hại trong việc nhận freelance còn trực tiếp hơn: bạn nhận dự án ngoài Next.js + Prisma, dùng Cursor tăng tốc, kết quả AI chạy npm install, phá sạch cấu hình workspace của pnpm; nó không biết schema database nằm đâu, file migration sinh ra lỗi tươi. Khách hối bàn giao, bạn mất ba tiếng debug code do AI sinh — đồng tiền kiếm quá ấm ức.

Ba kiểu lật xe điển hình vì AI không nắm luật ngầm dự án: ① Nhầm trình quản lý gói (dự án xài pnpm, AI mặc định npm install), dependency cài nhầm chỗ, workspace config mất tác dụng; ② Không tìm thấy đầu vào test (test nằm ở packages/web, AI chạy pnpm test ở thư mục gốc, báo “không tìm thấy file test”); ③ Style code lệch nhau (dự án dùng ESLint + Prettier, code AI sinh ra thụt lề và dấu nháy đều sai, CI đỏ vạch).

Cơ hội: AGENTS.md tách bạch “tài liệu cho người” và “tài liệu cho máy”

Dự án mã nguồn mở AGENTS.md trên GitHub (repo github.com/agentsmd/agents.md, tính đến 2026-08-25 khoảng 24 nghìn stars) giải quyết đúng vấn đề này. Ý tưởng cốt lõi cực kỳ đơn giản: đặt một file Markdown ở thư mục gốc dự án, chuyên bảo AI cách build, cách test, tuân theo style code nào.

Đây không phải thay thế README, mà bổ sung cho nó. README phục vụ người đóng góp, AGENTS.md phục vụ AI agent. Hai bên phân vai rõ ràng, không đụng nhau.

Theo bài gốc, AGENTS.md đã được hàng chục nghìn dự án mã nguồn mở áp dụng (con số cụ thể cần xác minh), phủ VS Code, Cursor, Windsurf, Aider, GitHub Copilot và các công cụ AI lập trình phổ biến (kết luận đã xác minh); ngoài ra theo phản hồi cộng đồng, OpenAI Codex, Google Jules cũng hỗ trợ (⚠️ chưa kiểm chứng). Bạn không học bây giờ, đồng nghĩa để AI nói giọng địa phương với mình.

Lộ trình 1: Viết tay một AGENTS.md tối thiểu dùng được

Chi phí cực thấp. Tạo file mới, viết ba đoạn là đủ dùng.

Kiến thức nền: ví dụ dưới đây dùng pnpm (tiết kiệm ổ đĩa hơn npm, hỗ trợ monorepo workspace), turbo là công cụ điều phối task monorepo, tham số --filter chỉ định tác dụng lên một sub-package, tránh ảnh hưởng cả kho.

Đoạn một “Dev environment tips”: bảo AI dự án xài trình quản lý gói nào, cách nhảy vào sub-package, cách tạo module mới. Ví dụ từ template chính thức:

• pnpm dlx turbo run where <project_name> — nhảy thẳng vào thư mục sub-package chỉ định, khỏi ls từng cái
• pnpm install --filter <project_name> — chỉ cài dependency cho một sub-package, không động cả monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — tạo sub-package React + Vite có kiểm tra TypeScript

Mấy lệnh này AI tự đoán không ra, nhưng bạn viết ra thì nó làm theo.

Đoạn hai “Testing instructions”: bảo AI chạy test thế nào, pipeline CI ở đâu, trước khi commit phải chạy check gì. Template chính thức gồm:

• pnpm turbo run test --filter <project_name> — chạy toàn bộ check của sub-package chỉ định
• pnpm vitest run -t "<test name>" — chỉ chạy một test khớp tên
• “Fix any test or type errors until the whole suite is green” — không xanh hết thì chưa được dừng
• “Add or update tests for the code you change, even if nobody asked” — câu này là chốt, không viết thì AI hay lười không viết test

Đoạn ba “PR instructions”: chuẩn hóa format tiêu đề commit, bắt buộc chạy lint và test. Template chính thức là Title format: [<project_name>] <Title>, và “Always run pnpm lint and pnpm test before committing”.

Ba đoạn cộng lại chưa đến 50 dòng, nhưng tỷ lệ code AI sinh ra chạy thông tăng rõ rệt (theo phản hồi cộng đồng, con số cụ thể cần xác minh).

Lộ trình 2: Lồng AGENTS.md trong monorepo cỡ lớn

Nếu bạn nhận dự án cấp doanh nghiệp, codebase là monorepo (nhiều dự án liên quan đặt chung một kho Git, ví dụ frontend, backend, shared code mỗi cái một thư mục con), một AGENTS.md duy nhất không đủ. AGENTS.md hỗ trợ lồng nhau: đặt một file riêng ở mỗi thư mục con, AI tự động đọc “file gần nhất”.

Cách làm cụ thể: AGENTS.md ở thư mục gốc viết quy chuẩn toàn cục (trình quản lý gói, quy trình CI, lưu ý bảo mật), rồi ở packages/web/, packages/api/, packages/shared/ mỗi chỗ đặt một file, ghi lệnh build riêng, đầu vào test riêng, dependency đặc thù của sub-package đó. Ví dụ package frontend cần ghi “thư viện component dùng shadcn, style dùng Tailwind, icon dùng lucide-react”; package backend cần ghi “migration database dùng Prisma, route API nằm ở src/routes, xác thực dùng JWT”.

Khi AI làm việc trong thư mục con, nó tự load AGENTS.md gần nhất, ưu tiên cao hơn file gốc. Nghĩa là trong cùng một dự án, AI assistant frontend và AI assistant backend nhận chỉ thị hoàn toàn khác nhau, không chồng chéo.

Lộ trình 3: Biến nó thành điểm bán hàng khác biệt khi nhận freelance

Thị trường nhận code bằng AI giờ đã đỏ máu — ai cũng biết dùng Cursor, nhưng chất lượng bàn giao thì nhấp nhổm. Nếu bạn ghi trong hồ sơ dự thầu một câu “Dự án đã cấu hình chuẩn AGENTS.md, phát triển có AI hỗ trợ tuân theo quy chuẩn dự án”, tỷ lệ trúng thầu sẽ cao hơn rõ rệt so với đám chỉ nói “tôi dùng AI viết code”.

Cách đánh cụ thể: nhận đơn xong, bỏ 30 phút đọc cấu trúc dự án khách, rồi viết một AGENTS.md tùy biến. Bản thân file này đã là một phần sản phẩm bàn giao — khách nhận về, sau này tự dùng AI bảo trì code cũng trơn tru hơn.

Tách riêng dịch vụ cấu hình AGENTS.md ra báo giá (tham khảo, cần điều chỉnh theo thị trường địa phương): bản cơ bản ~1.500.000đ (cấu hình một file + một file README hướng dẫn), bản doanh nghiệp ~8.000.000đ (lồng monorepo + quy chuẩn bảo mật + đào tạo team). Danh sách bàn giao: ① file AGENTS.md tùy biến ② hỗ trợ hỏi đáp 30 ngày qua Zalo ③ một video hướng dẫn 10 phút. Phù hợp: khách đã có gói Cursor/Windsurf nhưng dùng chưa ra gì. Không phù hợp: khách vẫn dev thuần tay, chưa đưa AI vào.

Case study: Chiến hào tương thích của AGENTS.md

AGENTS.md dùng giấy phép MIT (xác nhận từ source pack), do cộng đồng duy trì (cơ cấu quản trị cụ thể cần xác minh), trang chủ là agents.md.

Tương thích là chiến hào lớn nhất: kết luận đã xác minh VS Code, Cursor, Windsurf, Aider, GitHub Copilot đều hỗ trợ đọc AGENTS.md; theo phản hồi cộng đồng, OpenAI Codex, Claude Code, Gemini CLI, Google Jules cũng hỗ trợ (⚠️ chưa kiểm chứng). Nghĩa là bạn viết một file, AI assistant phổ biến nào cũng dùng được — không phải viết cấu hình riêng cho từng tool.

So với các phương án khác: .cursorrules của Cursor chỉ tác dụng trên Cursor, đổi sang Windsurf là mất; CLAUDE.md của Claude Code chỉ phục vụ Claude; hệ thống chỉ thị của GitHub Copilot lại là một bộ khác. Đặc tính “viết một lần, chạy khắp nơi” của AGENTS.md là lý do nó được áp dụng rộng trong thời gian ngắn.

Chi phí chuyển tool về 0. Hôm nay bạn xài Cursor, mai đổi Windsurf, AGENTS.md dùng lại luôn, không phải viết lại rule.

Lời kêu gọi: Tối nay thêm sổ tay cho dự án

Checklist 5 phút: ① Mở thư mục gốc dự án ② Tạo file AGENTS.md ③ Copy template chính thức (github.com/agentsmd/agents.md) ④ Điền ba lệnh (build, test, lint) ⑤ Lần sau nhờ AI viết code thì quan sát hiệu quả.

Nếu bạn đang xài monorepo, tối nay bỏ thêm 20 phút thêm cấu hình lồng cho từng sub-package. Mai mở máy bạn sẽ thấy code AI sinh ra không còn phải sửa đi sửa lại.

AGENTS.md là cấu hình AI lập trình có ROI cao nhất hiện tại — bỏ 30 phút, đổi lại mỗi tháng vài tiếng debug.