DESIGN.md là gì, khác AGENTS.md thế nào?

DESIGN.md là gì và AGENTS.md không bao quát những gì

DESIGN.md là một file markdown trong thư mục root của repository. File này giải thích cho AI coding agent vì sao code được thiết kế theo cách hiện tại. AGENTS.md trả lời một câu hỏi khác: phải làm việc ở đây như thế nào. Nội dung gồm build command, test command, lệnh lint bắt buộc phải pass và các path không được sửa. DESIGN.md ghi lại những quyết định đã được chốt và những gì sẽ hỏng nếu thay đổi một trong các quyết định đó.

Coding agent, tức các tool như Claude Code hoặc Cursor có thể tự đọc và chỉnh sửa repository, mặc định thường rất tự tin. Khi gặp một pattern không nhận ra, nó sẽ cải tiến pattern đó. Một cache tự viết có thể bị thay bằng Redis (in-memory data store), vì đó là dạng cache xuất hiện trong phần lớn code mà model từng đọc. AGENTS.md không ngăn được việc này, vì make test vẫn pass trong cả hai trường hợp. Rule bị vi phạm chưa từng được ghi lại ở nơi agent có thể đọc.

Nếu bạn chưa viết file đầu tiên, hãy bắt đầu từ đó. AGENTS.md và HUMAN.md nằm cùng thư mục với nó giải thích format và vị trí mà từng tool sẽ tìm file này. Phần tiếp theo là chương sau chương đó.

Thực sự có gì trong một DESIGN.md đã được công bố

Cách nhanh nhất để hiểu định dạng này là đọc các file mà các công ty công bố về chính họ. Repository official-design-md chỉ theo dõi những file đó. Quy tắc đưa vào chỉ có một dòng, và dòng đó chính là mục đích của cả collection:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Tính đến tháng 10 năm 2026, danh sách có 11 file: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel và VoltAgent. Mỗi file nằm tại một URL public, phần lớn trên domain của bên phát hành và số còn lại trong một repository GitHub public, nên bạn có thể đọc một file ngay trong terminal.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Cả hai đều là tài liệu design system. Chúng mô tả sản phẩm nên có giao diện như thế nào: màu sắc, kiểu chữ, khoảng cách và chuyển động. Hãy đọc qua chủ đề cụ thể, vì phần hữu ích nằm ở cách bài viết được tổ chức chứ không phải ở chủ đề.

Tính đến ngày 27 tháng 10 năm 2026, file Nuxt dài khoảng 2.000 từ, và phần lớn nội dung là một quy tắc đi kèm với lý do. File mở đầu bằng việc nêu rõ dark mode là theme mặc định. File liệt kê màu xanh thương hiệu #00DC82 kèm ghi chú rằng các màu thương hiệu là "Dùng cho logo, hình ảnh trên mạng xã hội và bản in. Không dùng chúng làm giá trị thô trong code UI." Gần cuối file có một section với tiêu đề Reject these, bao gồm:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

File Vercel dài hơn, khoảng 6.000 từ tính đến tháng 10 năm 2026, và tiến thêm một bước. Một trong các tiêu đề của file là Reject generated-design reflexes. Bên dưới là danh sách những thứ mà một generator đủ năng lực sẽ ưu tiên dùng khi không ai bảo nó tránh dùng:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Câu đó định nghĩa loại file này. Đây là danh sách bằng văn bản về các mặc định mà một model tự tin sẽ tạo ra, được công bố để model ngừng tạo ra chúng. Mọi DESIGN.md đáng được commit đều là danh sách như vậy cho một domain nào đó.

Vì sao các công ty tự phát hành DESIGN.md?

Cộng đồng đã đi trước. awesome-design-md hiện chứa 84 file được trích xuất từ các website công khai, theo số liệu trong README tại thời điểm ngày 27 tháng 10 năm 2026. Tất cả đều được viết theo cùng một định dạng gồm chín section, nên bạn có thể trỏ agent vào một file và tạo ra giao diện gần giống file đó. Những file này hữu ích, nhưng vẫn chỉ là các phỏng đoán. Không có ai tại các công ty đó kiểm duyệt chúng.

File do chính công ty phát hành thì khác, vì nó là nguồn gốc chứ không phải bản diễn giải của sản phẩm đầu ra. Khi Vercel thay đổi type scale, vercel.com/design.md cũng thay đổi theo. Bản sao được scrape vào tháng 3 vẫn tiếp tục hướng dẫn agent dùng type scale cũ, và trong repository không có gì cho bạn biết bản sao đó đã lỗi thời.

Mười một nhà phát hành vẫn là một con số nhỏ, và repository cũng nói rõ điều đó: tiêu chuẩn này còn mới và đang được các công ty chính thức áp dụng ngày càng nhiều. Cả hai bộ sưu tập đều do VoltAgent duy trì. Đây là một agent framework mã nguồn mở cũng tự phát hành file của mình. Vì vậy, hãy xem danh sách này như một tracker, không phải một thống kê trung lập. Tuy vậy, danh sách này vẫn đáng theo dõi vì những công ty có mặt trong đó. Một số công ty là nơi phát hành front-end code được các developer khác sao chép nhiều nhất. Các mục mới hơn như Ant Design, Microsoft FAST, Juspay và Oxide Computer là những design system được các team khác dùng làm nền tảng. File của họ đang trở thành ví dụ thực tế về một DESIGN.md. Hãy so sánh với quá trình phát triển của AGENTS.md: agents.md hiện được hơn 60.000 dự án mã nguồn mở sử dụng, còn quyền quản lý thuộc về Agentic AI Foundation dưới Linux Foundation. DESIGN.md cũng đã bắt đầu đi theo hướng đó. Ngày 21 tháng 4 năm 2026, Google đã phát hành mã nguồn mở một bản đặc tả nháp cho định dạng này dưới dạng google-labs-code/design.md, kèm token schema và CLI theo giấy phép Apache-2.0. Tính đến tháng 10 năm 2026, định dạng này đang ở phiên bản alpha và vẫn được phát triển tích cực. Nó do Google Labs duy trì thay vì một foundation trung lập, đồng thời mô tả visual identity, nên không nói gì về các invariant mà một file backend cần có. Các convention cho file mà agent có thể đọc đang nhanh chóng ổn định, và chúng đang được định hình từ các tổ chức dẫn đầu.

Nội dung DESIGN.md khi dự án không có giao diện người dùng

Phần lớn phần mềm chạy trên VPS không có ngôn ngữ hình ảnh để đặc tả. Tuy vậy, file này vẫn cần thiết vì cơ chế không liên quan gì đến màu sắc. Mục đích là ghi lại các ràng buộc mà một editor tự tin có thể vô tình vi phạm.

Các bất biến. Mỗi bất biến gồm một câu, nêu điều phải luôn đúng sau mọi lần chỉnh sửa. “Mọi thao tác ghi đều đi qua queue.enqueue(). Ghi trực tiếp vào database sẽ bỏ qua audit log, trong khi compliance export đọc dữ liệu từ audit log.” Bất biến kèm lý do sẽ vẫn có tác dụng khi gặp một task bạn chưa từng dự đoán. Bất biến không có lý do chỉ giống một preference, và preference thường bị tối ưu loại bỏ.

Các phương án bị loại. Nêu lựa chọn hiển nhiên và lý do không chọn nó. “Chúng ta không dùng Redis cho caching. Service chạy trên một VPS duy nhất, nên map trong process nhanh hơn và bớt một daemon phải duy trì. Xem xét lại khi có application server thứ hai.” Nếu thiếu đoạn này, khi được yêu cầu tăng tốc cache, agent sẽ thêm Redis, và làm vậy là hợp lý: bạn chưa cho agent biết ràng buộc đó. Đây là phần giúp toàn bộ file này phát huy giá trị.

Các ranh giới. Đây là những nơi mà một chỉnh sửa nhỏ có thể gây ảnh hưởng rất lớn. Database schema. Public route prefix mà khách hàng đã dùng trong các script. Config file mà deploy đọc trước khi application khởi động. Cron entry giả định chỉ có một bản sao đang chạy. Hãy nêu rõ từng ranh giới và cho biết thay đổi ở đó sẽ phải trả giá như thế nào. Nếu agent cũng có thể truy cập open web thông qua một instance SearXNG tự host được cấu hình làm search backend, thì đây cũng là một ranh giới cần ghi lại. File phải nêu rõ nội dung được fetch nào được phép ảnh hưởng đến code và nội dung nào chỉ được trích dẫn lại cho bạn.

Từ vựng. Nếu code dùng tenant còn team dùng customer, hãy ghi rõ ánh xạ này. Agent đoán sai ở đây có thể tạo ra code trông hợp lý nhưng mô hình hóa sai đối tượng. Đây là loại lỗi khó phát hiện nhất khi review.

Một DESIGN.md bạn có thể dùng ngay hôm nay

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Hôm nay, hãy điền 2 phần bạn có thể viết từ trí nhớ: các bất biến và các phương án đã loại bỏ. Các phần còn lại chỉ để tiêu đề. Một file có 4 dòng trung thực vẫn hữu ích. Một file có 40 dòng đoán chừng thì không. Nếu repository chứa nhiều package, một file ở thư mục gốc sẽ không phù hợp với tất cả. Khi đó, hãy áp dụng cách tách theo từng thư mục giống như các file AGENTS.md lồng nhau trong một monorepo: một file ngắn ở thư mục gốc cho các quyết định dùng chung, và một file nhỏ hơn bên cạnh mỗi package có các quyết định riêng.

Một số tool tải mọi file markdown trong thư mục gốc của repository. Một số tool chỉ tải file được chỉ định. Vì vậy, đừng giả định cách nào cũng giống nhau. Thêm một liên kết đến AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Mẫu anti-pattern: DESIGN.md lặp lại README

Phiên bản kém chất lượng phổ biến nhất đọc khá trôi chảy nhưng không cung cấp thông tin hữu ích. Nó mở đầu bằng phần mô tả dự án, liệt kê các tính năng, giải thích cách cài đặt rồi kết thúc bằng licence. Tất cả nội dung đó đã có trong README, và không dòng nào giải thích vì sao mọi thứ lại được thiết kế như vậy.

Điều này khiến bạn tốn chi phí hai lần. Chi phí đầu tiên là context. Một file mà agent đọc khi bắt đầu mọi task sẽ bị tính vào mọi task, còn phần hướng dẫn cài đặt bị lặp lại chỉ tạo overhead trong một window cố định. Việc phân bổ window đó cũng là một kỹ năng riêng, được trình bày trong quản lý context window trong Claude Code. Tóm lại: mọi nội dung được tự động load phải là phần có giá trị cao nhất trong repository.

Chi phí thứ hai nghiêm trọng hơn. Hai bản sao của cùng một thông tin sẽ dần khác nhau. README nói service lắng nghe trên 8080, còn DESIGN.md vẫn nói 3000. Agent không có cách nào xác định thông tin nào được ưu tiên, nên sẽ chọn một bản và viết code dựa trên đó. Một file đôi khi sai vẫn được tham khảo với mức độ tin cậy giống như một file luôn đúng.

Cách kiểm tra rất nhanh. Nếu một đoạn văn có thể nằm tự nhiên trong README, hãy xóa đoạn đó khỏi DESIGN.md. Phần còn lại phải là những điều bạn sẽ nói trực tiếp trong một buổi code review, tức là phần bắt đầu bằng câu “chúng ta đã thử cách đó rồi”.

Làm thế nào biết file đang hoạt động?

Không có linter cho việc này. Bạn có thể chạy một phép kiểm tra trong 1 phút.

Giao cho agent một task buộc phải tuân theo một invariant. Ví dụ: "Thêm một background job đánh dấu các row đã stale là expired." Một file đang hoạt động đúng sẽ thể hiện ngay trong câu trả lời, trước khi có bất kỳ code nào: agent phải nói rằng job ghi dữ liệu thông qua queue.enqueue(), vì ghi trực tiếp sẽ bỏ qua audit log. Nếu agent mở database connection rồi ghi dữ liệu, thì một trong hai điều sau là đúng. File hoàn toàn không được đọc, hoặc invariant được mô tả quá lỏng nên có thể tranh luận.

Đồng thời, hãy theo dõi token count vì file này được load trong mọi turn. Nếu context usage tăng mạnh sau khi bạn thêm DESIGN.md nhưng câu trả lời không tốt hơn, file đang chứa những phần prose mà agent đã biết. Đọc bộ đếm token trong Claude Code cho biết budget đó được sử dụng vào đâu.

Điều này đặc biệt quan trọng khi agent chạy trên server thay vì laptop của bạn. Agent hoạt động trong một session chạy dài, như thiết lập trong workspace Claude Code trên VPS với tmux, không có memory của cuộc trò chuyện hôm qua. Repository là memory của nó. Mọi thứ bạn đã giải thích trong chat nhưng chưa commit sẽ biến mất ở session tiếp theo. DESIGN.md là nơi lưu phần giải thích đó để nó tồn tại lâu dài.

Bắt đầu từ những quyết định thường gây tranh luận

Phiên bản đầu tiên chỉ mất 20 phút. Mở vài pull request gần đây nhất có nhận xét của reviewer như “không, ở đây chúng ta làm theo cách khác”. Mỗi nhận xét đó là một invariant chưa từng được ghi lại. Đó cũng là nơi agent sẽ lặp lại cùng một lỗi, nhanh hơn và thường xuyên hơn con người. Hãy bổ sung vào file khi nó không giúp được bạn, thay vì cập nhật theo lịch. Nếu bạn vẫn đang xác định agent phù hợp với workflow phát triển thông thường ở đâu, hướng dẫn học về AI agent năm 2026 là bước tiếp theo hợp lý.

FAQ

DESIGN.md có phải là một tiêu chuẩn chính thức không?

Không theo cách AGENTS.md được công nhận. AGENTS.md có trang chính thức tại agents.md, được hơn 60,000 dự án nguồn mở sử dụng và được Agentic AI Foundation, thuộc Linux Foundation, quản lý. DESIGN.md có đặc tả được công bố nhưng không có tổ chức trung lập quản lý. Google đã phát hành bản đặc tả dự thảo dưới dạng nguồn mở vào April 21, 2026, và bản này nằm trong repository google-labs-code/design.md theo giấy phép Apache-2.0. Tính đến October 2026, đặc tả này đang ở phiên bản alpha và vẫn được phát triển tích cực. Nó mô tả nhận diện trực quan: màu sắc, typography, bố cục và component. DESIGN.md cũng đã được một số bên áp dụng trực tiếp: eleven công ty và dự án, gồm Vercel, Nuxt, Atlassian và Resend, đã công bố file này. Một bộ sưu tập do cộng đồng duy trì đã trích xuất thêm 84 file từ các site công khai tính đến October 27, 2026. Với một file backend chứa các invariant và những phương án bị loại, hãy xem DESIGN.md là một convention mà bạn có thể áp dụng ngay và tự do mở rộng, vì chưa có đặc tả nào quy định các tên section đó.

Có nên để DESIGN.md chỉ là một section trong AGENTS.md không?

Với repository nhỏ thì nên. Một file mà agent chắc chắn đọc được hữu ích hơn hai file mà một file có thể bị bỏ qua. Hãy tách chúng khi AGENTS.md không còn dễ quét nhanh, hoặc khi bạn nhận thấy hai phần thay đổi với tốc độ khác nhau. AGENTS.md thay đổi khi build thay đổi. DESIGN.md thay đổi khi một quyết định thay đổi. Việc này ít xảy ra hơn và có ảnh hưởng lớn hơn. Khi tách file, hãy thêm một dòng vào AGENTS.md yêu cầu agent đọc DESIGN.md trước khi sửa code, vì không phải tool nào cũng load mọi file markdown trong root.

DESIGN.md khác architecture decision record như thế nào?

ADR (architecture decision record) là bản ghi có ngày tháng về một quyết định. Một project lành mạnh sẽ tích lũy hàng chục ADR trong một folder. Đó là lịch sử, và việc load lịch sử tốn tài nguyên, vì agent phải đọc tất cả ADR để xác định quyết định nào vẫn còn hiệu lực. DESIGN.md mô tả trạng thái hiện tại và được viết để đọc đầy đủ trong mỗi task. Nếu bạn đã viết ADR thì hãy giữ cả hai. ADR cho biết đã quyết định điều gì và quyết định khi nào. DESIGN.md cho biết hiện tại điều gì là đúng, và đây là file bạn trỏ agent tới.

DESIGN.md nên dài bao nhiêu?

Đủ ngắn để load trong mỗi lượt mà không thấy tiếc thời gian. Các ví dụ được công bố dài vì chúng đặc tả toàn bộ một visual language: file của Nuxt dài khoảng 2,000 từ và file của Vercel dài khoảng 6,000 từ tính đến October 2026. Một backend service thường cần ít hơn nhiều. Hãy bắt đầu với một trang và chỉ mở rộng khi agent làm sai một việc mà một câu duy nhất có thể đã ngăn được. Độ dài không phải thước đo. Mỗi dòng phải mô tả một điều mà nếu không có dòng đó, agent sẽ có thể làm sai.