DESIGN.md là gì? File sau AGENTS.md cho coding agent

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 gốc của repository. File này giải thích cho AI coding agent vì sao code được tổ chức 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 trong repository này như thế nào. Nội dung gồm build command, test command, lint bắt buộc phải pass và các path không được chỉnh sửa. DESIGN.md ghi lại những quyết định đã được chốt và những gì sẽ bị hỏng nếu thay đổi các quyết định đó.

Coding agent, tức một 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. Nó gặp một pattern không nhận ra rồi tìm cách cải thiện pattern đó. Một cache viết thủ công có thể bị đổi thành Redis, một in-memory data store, vì đó là cách cache thường xuất hiện trong phần lớn code mà model đã đọc. AGENTS.md không ngăn được việc này, vì make test đều pass trong cả hai trường hợp. Rule bị vi phạm chưa từng được ghi ở nơi mà 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 bên cạnh nó giải thích format và vị trí mà từng tool tìm file này. Phần tiếp theo là chapter sau phần đó.

Có gì thực sự bên 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 như vậy. Quy tắc đưa vào chỉ có một dòng, và dòng đó chính là mục đích của collection này:

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 8 năm 2026, danh sách có 7 công ty: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel và VoltAgent. Mỗi file nằm tại một public URL ổn định, nên bạn có thể đọc ngay trong terminal.

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

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

File của Nuxt dài khoảng 2.100 từ, và phần lớn nội dung là một rule đi kèm lý do:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

File của Vercel dài hơn, khoảng 6.500 từ vào tháng 8 năm 2026, và đi xa hơn một bước. Một trong các heading của file là Reject generated-design reflexes. Bên dưới là danh sách những thứ mà một generator có 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 default 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 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 đã làm việc này trước. awesome-design-md chứa 73 file được reverse-engineer từ các website công khai. Mỗi file đều tuân theo cùng một định dạng gồm 9 section, để agent có thể tham chiếu một file và tạo ra giao diện gần với thiết kế đó. Những file này hữu ích, nhưng chúng vẫn chỉ là các phỏng đoán. Không có ai tại các công ty đó review chúng.

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

7 nhà phát hành 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à mức độ áp dụng chính thức đang tăng. Cả 2 collection đề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 cuộc thống kê trung lập. Danh sách này vẫn đáng theo dõi vì 7 công ty đó là ai. Đây là những công ty có front-end code được các developer khác sao chép nhiều nhất. Các file của họ đang trở thành ví dụ thực tế cho 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, và Agentic AI Foundation thuộc Linux Foundation chịu trách nhiệm quản lý. 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ừ những công ty dẫn đầu.

Nội dung cần có trong 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ả. File này vẫn cần thiết vì cơ chế hoạt động 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 có kinh nghiệm nếu không biết sẽ vô tình vi phạm.

Các bất biến. Mỗi bất biến viết thành một câu, nêu một đ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 theo 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 đứng riêng trông giống một preference, mà các preference thường bị loại bỏ để tối ưu.

Các phương án bị loại. Nêu phương án hiển nhiên và lý do không chọn nó. "Chúng ta không dùng Redis để caching. Service chạy trên một VPS duy nhất, nên map trong process nhanh hơn và giảm một daemon cần duy trì. Hãy 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 hề nói cho agent biết ràng buộc đó. Đây là phần giúp toàn bộ file 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 lớn. Database schema. Prefix của public route mà khách hàng đã dùng trong script. File config mà deploy đọc trước khi application khởi động. Cron entry giả định rằng chỉ có một bản sao của nó đang chạy. Hãy nêu tên chúng và nói rõ thay đổi từng mục sẽ phải trả giá gì. 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ì đó cũng là một ranh giới cần ghi lại. File cần nêu rõ loại text đã fetch nào được phép ảnh hưởng đến code và loại nào chỉ được trích dẫn lại cho bạn.

Thuật ngữ. Nếu code dùng tenant còn team dùng customer, hãy ghi rõ mapping. Agent đoán sai ở đây có thể tạo ra code đọc vẫn 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 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ãy điền 2 phần bạn có thể viết từ trí nhớ ngay hôm nay: các invariant và những phương án đã loại bỏ. Các phần còn lại chỉ cần để heading. Một file có 4 dòng trung thực vẫn có ích. Một file có 40 dòng phỏng đoán 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 dùng cách tách theo từng thư mục giống như cách áp dụng cho các file AGENTS.md lồng nhau trong 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 từng 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. Hãy thêm một liên kết tham chiếu đến AGENTS.md:

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

Mẫu chống nên dùng: DESIGN.md lặp lại README

Phiên bản kém phổ biến nhất thường đọc khá trôi chảy nhưng không cung cấp thông tin hữu ích. Nó mở đầu bằng việc mô tả project, liệt kê các feature, giải thích cách cài đặt rồi kết thúc bằng license. Mọi dòng trong đó đều đã có trong README, và không dòng nào giải thích vì sao mọi thứ đượ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 một section 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 đề cập 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 ghi service lắng nghe trên 8080, còn DESIGN.md vẫn ghi 3000. Agent không có cách nào xác định bản nào được ưu tiên, nên nó chọn một bản và viết code dựa trên đó. Một file đôi khi sai sẽ đượ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 paragraph có thể nằm nguyên trong README, hãy xóa 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 code review, những điều bắt đầu bằng câu “chúng ta đã thử cách đó rồi”.

Làm sao biết file này đang có tác dụng?

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

Giao cho agent một task đi thẳng vào một invariant. Ví dụ: "Thêm một background job đánh dấu các row đã stale là expired." File đang hoạt động sẽ thể hiện ngay trong câu trả lời, trước khi agent viết 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 khả năng sau là đúng. File hoàn toàn không được đọc, hoặc invariant được viế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 mức sử dụng context tăng 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 đoạn prose mà agent đã biết. Đọc các bộ đếm token trong Claude Code cho biết ngân sách đó được sử dụng ở đâ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 làm việc trong một session chạy lâu, như thiết lập trong workspace Claude Code trên VPS với tmux, không có memory về cuộc trò chuyện của ngày hôm qua. Repository chính là memory. 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, còn 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 với 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ở một 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 như vậy là một invariant chưa từng được ghi lại, đồng thời là một chỗ agent sẽ lặp lại cùng lỗi đó nhanh hơn và thường xuyên hơn con người. Chỉ bổ sung vào file khi file không giúp được bạn, không cần cập nhật theo lịch. Nếu bạn vẫn đang tìm cách đưa agent vào workflow phát triển thông thường, hướng dẫn tìm hiểu 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 là tiêu chuẩn chính thức. AGENTS.md có trang chủ tại agents.md, được hơn 60,000 dự án mã nguồn mở sử dụng và được Agentic AI Foundation, một tổ chức thuộc Linux Foundation, quản lý. Tính đến tháng 8 năm 2026, DESIGN.md chưa có cơ quan quản lý và cũng chưa có đặc tả được công bố. Điểm mạnh của nó là đã được các bên phát triển sử dụng trực tiếp: bảy công ty, gồm Vercel, Nuxt, Atlassian và Resend, công khai một file DESIGN.md tại URL của họ. Một bộ sưu tập do cộng đồng duy trì có thêm 73 file được reverse-engineer từ các website công khai. Bạn có thể xem DESIGN.md là một quy ước có thể áp dụng ngay và tự do mở rộng, vì không có gì xác thực tên các section của bạn.

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

Với repository nhỏ thì có. Một file mà agent chắc chắn đọc được tốt hơn hai file nhưng một file bị bỏ qua. Hãy tách chúng khi AGENTS.md không còn dễ quét, 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 quá trình build thay đổi. DESIGN.md thay đổi khi một quyết định thay đổi. Trường hợp này ít xảy ra hơn và có tác độ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 thư mục root.

DESIGN.md khác gì so với architecture decision record?

ADR (architecture decision record) là bản ghi có ngày tháng về một quyết định. Một project được quản lý tốt thường tích lũy hàng chục ADR trong một thư mục. Đây là lịch sử, và lịch sử tốn chi phí load, 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 toàn bộ 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 vào thời điểm nào. DESIGN.md cho biết điều gì đang đúng hôm nay. Đây là file bạn trỏ agent đến.

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

Đủ ngắn để có thể load trong mỗi lượt mà không thấy lãng phí. Các ví dụ được công bố khá dài vì chúng đặc tả cả một ngôn ngữ trực quan: file của Nuxt dài khoảng 2,100 từ và file của Vercel dài khoảng 6,500 từ tính đến tháng 8 năm 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 điều mà một câu duy nhất đã có thể ngăn chặn. Độ dài không phải là thước đo. Mỗi dòng phải mô tả một điều mà nếu không có dòng đó, agent có thể làm sai.