Apa itu fail DESIGN.md dan cara menggunakannya

Apakah itu DESIGN.md, dan perkara yang tidak diliputi oleh AGENTS.md

DESIGN.md ialah fail markdown di akar repositori anda yang memberitahu ejen pengekodan AI mengapa kod tersebut dibentuk sedemikian. AGENTS.md menjawab soalan yang berbeza: cara untuk bekerja di sini, yang bermaksud arahan binaan, arahan ujian, lint yang perlu diluluskan, dan laluan yang perlu dibiarkan. DESIGN.md merekodkan keputusan yang telah diputuskan, dan perkara yang akan rosak apabila salah satu daripadanya dibatalkan.

Ejen pengekodan, yang bermaksud alat seperti Claude Code atau Cursor yang membaca dan menyunting repositori anda sendiri, adalah yakin secara lalai. Ia menemui corak yang tidak dikenalinya dan ia menambah baik corak tersebut. Cache yang ditulis tangan menjadi Redis (storan data dalam memori), kerana itulah rupa cache dalam kebanyakan kod yang telah dibaca oleh model tersebut. AGENTS.md tidak menghalang perkara ini, kerana make test tetap lulus dalam kedua-dua keadaan. Peraturan yang dilanggar itu tidak pernah ditulis di mana-mana tempat yang boleh dibaca oleh ejen tersebut.

Jika anda belum menulis fail pertama lagi, mulakan di situ. AGENTS.md dan HUMAN.md yang terletak di sebelahnya meliputi format dan tempat setiap alat mencarinya. Perkara yang berikut ialah bab selepas bab tersebut.

Apakah kandungan sebenar DESIGN.md yang diterbitkan

Cara terpantas untuk mempelajari format ini adalah dengan membaca fail yang diterbitkan oleh syarikat tentang diri mereka sendiri. Repositori official-design-md menjejaki fail-fail tersebut sahaja. Peraturan kemasukannya hanya satu baris, dan baris itu merupakan tujuan utama koleksi ini:

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

Sehingga Ogos 2026, ia menyenaraikan tujuh: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel dan VoltAgent. Setiap fail terletak pada URL awam yang stabil, jadi anda boleh membacanya di dalam terminal sekarang juga.

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

Kedua-duanya merupakan dokumen sistem reka bentuk. Ia menerangkan rupa sesuatu produk: warna, jenis fon, jarak, dan pergerakan. Baca melangkaui subjek tersebut, kerana bahagian yang berguna ialah bentuk penulisan itu sendiri dan bukannya topik yang dibincangkan.

Fail Nuxt mengandungi kira-kira 2,100 perkataan, dan kebanyakannya merupakan peraturan yang disertakan dengan alasannya:

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"`.

Fail Vercel lebih panjang, sekitar 6,500 perkataan pada Ogos 2026, dan ia melangkah lebih jauh. Salah satu tajuknya ialah Reject generated-design reflexes. Di bawahnya terdapat senarai perkara yang akan dicapai oleh penjana yang berkebolehan apabila tiada sesiapa yang melarangnya:

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

Ayat itu mentakrifkan jenis fail tersebut. Ia merupakan senarai bertulis mengenai nilai lalai yang dihasilkan oleh model yang yakin, diterbitkan supaya model tersebut berhenti menghasilkannya. Setiap DESIGN.md yang wajar dikomitkan adalah senarai tersebut untuk sesuatu domain.

Mengapa syarikat menerbitkan DESIGN.md mereka sendiri?

Komuniti telah mendahului perkara ini. awesome-design-md mengandungi 73 fail yang diubah suai (reverse-engineered) daripada laman web awam, setiap satunya ditulis mengikut format sembilan bahagian yang sama, supaya ejen boleh diarahkan kepadanya dan menghasilkan sesuatu yang hampir dengan rupa tersebut. Fail-fail itu berguna namun ia masih sekadar tekaan. Tiada sesiapa di syarikat tersebut yang menyemaknya.

Fail pihak pertama adalah berbeza kerana ia merupakan sumber dan bukannya bacaan daripada output. Apabila Vercel menukar skala taipnya, vercel.com/design.md berubah bersamanya. Salinan yang diskrap pada bulan Mac akan terus mengajar ejen anda skala yang lama, dan tiada apa-apa dalam repositori anda yang akan memberitahu anda bahawa salinan tersebut telah lapuk.

Tujuh penerbit adalah jumlah yang kecil, dan repositori itu sendiri menyatakan perkara tersebut: piawaian ini masih baharu dan penggunaan rasmi semakin meningkat. Kedua-dua koleksi diselenggara oleh VoltAgent, sebuah rangka kerja ejen sumber terbuka yang turut menerbitkan failnya sendiri, jadi bacalah senarai tersebut sebagai penjejak dan bukannya bancian neutral. Ia masih berbaloi untuk dipantau, disebabkan oleh siapa tujuh syarikat tersebut. Mereka adalah syarikat yang kod bahagian hadapannya paling banyak disalin oleh pembangun lain, dan fail mereka sedang menjadi contoh kerja bagi apa itu DESIGN.md. Bandingkan laluan yang diambil oleh AGENTS.md: agents.md kini mencatatkan lebih 60,000 projek sumber terbuka yang menggunakan format tersebut, dan pengurusan terletak di bawah Agentic AI Foundation di bawah Linux Foundation. Konvensyen untuk fail yang boleh dibaca oleh ejen sedang terbentuk dengan pantas, dan ia terbentuk dari peringkat atasan.

Perkara yang perlu dimuatkan dalam DESIGN.md apabila projek tidak mempunyai antara muka pengguna

Kebanyakan perisian yang dijalankan pada VPS tidak mempunyai bahasa visual untuk ditentukan. Fail ini tetap penting kerana mekanismenya tiada kaitan dengan warna. Ia bertujuan untuk mencatatkan kekangan yang mungkin dilanggar oleh penyunting yang yakin tanpa disedari.

Invarian. Satu ayat bagi setiap satu, menyatakan sesuatu yang mesti kekal benar selepas sebarang suntingan. "Setiap penulisan melalui queue.enqueue(). Penulisan pangkalan data secara terus akan melangkau log audit, sedangkan log audit adalah perkara yang dibaca oleh eksport pematuhan." Invarian yang disertakan dengan sebabnya akan bertahan apabila berhadapan dengan tugasan yang tidak dijangka. Invarian yang berdiri sendiri hanya dibaca sebagai keutamaan, dan keutamaan sering dioptimumkan sehingga hilang.

Alternatif yang ditolak. Pilihan yang jelas, dan sebab ia ditolak. "Kami tidak menggunakan Redis untuk caching. Servis ini berjalan pada satu VPS sahaja, jadi peta dalam proses (in-process map) adalah lebih pantas dan ia mengurangkan satu daemon yang perlu diselenggara. Semak semula perkara ini apabila pelayan aplikasi kedua wujud." Tanpa perenggan tersebut, ejen yang diminta untuk mempercepatkan cache akan menambah Redis, dan ia adalah tindakan yang betul: anda tidak pernah memberitahunya tentang kekangan tersebut. Ini adalah bahagian yang menjadikan fail ini berbaloi.

Sempadan. Tempat di mana suntingan kecil mempunyai kesan yang besar. Skema pangkalan data. Awalan laluan awam yang telah diskripkan oleh pelanggan. Fail konfigurasi yang dibaca oleh proses deploy sebelum aplikasi bermula. Entri cron yang mengandaikan hanya satu salinan yang berjalan. Namakan setiap satu, dan nyatakan kos perubahan bagi setiap satunya. Jika ejen juga boleh mencapai web terbuka, katakan melalui instans SearXNG yang dihoskan sendiri dan disambungkan sebagai backend carian, itu adalah sempadan yang perlu dicatatkan juga, kerana fail tersebut harus menyatakan teks yang diambil mana yang dibenarkan untuk mempengaruhi kod dan mana yang hanya dipetik semula kepada anda.

Kosa kata. Jika kod menyatakan tenant dan pasukan menyatakan customer, tuliskan pemetaannya. Ejen yang meneka dengan salah di sini akan menghasilkan kod yang kelihatan betul tetapi memodelkan perkara yang salah, yang merupakan jenis kesilapan paling sukar untuk dikesan semasa semakan.

Reka bentuk DESIGN.md yang boleh anda salin hari ini

# 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.

Isikan dua bahagian yang boleh anda tulis daripada ingatan hari ini, iaitu invarian dan alternatif yang ditolak, dan biarkan bahagian lain sebagai tajuk sahaja. Fail dengan empat baris yang jujur sudah memadai. Fail dengan empat puluh baris yang sekadar tekaan tidak berguna.

Sesetengah alat memuatkan setiap fail markdown dalam root repositori dan sesetengah alat hanya memuatkan fail yang ditentukan, jadi jangan buat andaian. Tambahkan penunjuk ke AGENTS.md:

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

Invarian

• Sistem mesti sentiasa boleh dipulihkan daripada sandaran tanpa memerlukan akses kepada perkhidmatan pihak ketiga.
• Setiap perubahan konfigurasi mesti melalui kawalan versi sebelum digunakan pada pelayan pengeluaran.

Alternatif yang ditolak

• Menggunakan skrip bash tersuai untuk pengurusan konfigurasi: Ditolak kerana sukar diselenggara dan tidak mempunyai mekanisme pengesahan status (idempotency).
• Menyimpan rahsia dalam teks biasa di repositori: Ditolak kerana risiko keselamatan yang tinggi walaupun repositori bersifat peribadi.

Komponen seni bina

Aliran data

Pertimbangan keselamatan

Pelan skalabiliti

Anti-corak: DESIGN.md yang mengulangi README

Versi buruk yang paling lazim dibaca dengan lancar tetapi tidak mengajar apa-apa. Ia bermula dengan fungsi projek, menyenaraikan ciri-ciri, menerangkan cara pemasangan, dan diakhiri dengan lesen. Setiap baris tersebut sudah pun terkandung dalam README, dan tiada satu pun yang menjelaskan mengapa sesuatu perkara itu dibuat sedemikian rupa.

Ini merugikan anda dua kali ganda. Kos pertama ialah konteks. Fail yang dibaca oleh ejen pada permulaan setiap tugasan akan memakan kos pada setiap tugasan, dan bahagian pemasangan yang diduplikasi hanyalah beban tambahan terhadap tetingkap konteks yang terhad. Menguruskan tetingkap tersebut adalah satu kemahiran tersendiri, yang dibincangkan dalam menguruskan tetingkap konteks dalam Claude Code. Versi ringkasnya: apa-apa yang dimuatkan secara automatik mestilah teks yang mempunyai nilai tertinggi dalam repositori.

Kos kedua adalah lebih buruk. Dua salinan kenyataan yang sama akan menjadi tidak selari. README menyatakan servis mendengar pada 8080, DESIGN.md masih menyatakan 3000, dan ejen tidak mempunyai cara untuk menentukan mana satu yang lebih tepat, jadi ia memilih salah satu dan menulis kod berdasarkan maklumat tersebut. Fail yang kadangkala salah akan dirujuk dengan keyakinan yang sama seperti fail yang sentiasa betul.

Ujiannya mudah. Jika sesuatu perenggan boleh diletakkan dengan selesa dalam README, buang ia daripada DESIGN.md. Apa yang tinggal sepatutnya adalah bahagian yang anda akan sebutkan dengan lantang semasa semakan kod, bahagian yang bermula dengan "kami sudah mencuba perkara itu".

Bagaimana anda tahu fail tersebut berfungsi?

Tiada linter untuk perkara ini. Terdapat satu pemeriksaan yang boleh anda jalankan dalam masa seminit.

Berikan ejen satu tugasan yang terus menjurus kepada invarian. "Tambah satu kerja latar belakang yang menandakan baris lapuk sebagai tamat tempoh." Fail yang menjalankan tugasnya dengan betul akan muncul dalam jawapan sebelum sebarang kod ditulis: ejen sepatutnya memberitahu anda bahawa kerja tersebut menulis melalui queue.enqueue(), kerana penulisan terus akan melangkau log audit. Jika ia membuka sambungan pangkalan data dan menulis, salah satu daripada dua perkara ini adalah benar. Fail tersebut tidak dibaca langsung, atau invarian tersebut digubal dengan cukup longgar untuk didebatkan.

Perhatikan juga kiraan token, memandangkan fail ini dimuatkan pada setiap giliran. Jika penggunaan konteks melonjak selepas anda menambah DESIGN.md dan jawapan tidak menjadi lebih baik, fail tersebut membawa prosa yang sudah pun diketahui oleh ejen. Membaca pembilang token dalam Claude Code menunjukkan ke mana bajet tersebut pergi.

Perkara ini paling penting apabila ejen berada pada pelayan dan bukannya pada komputer riba anda. Ejen yang bekerja dalam sesi jangka masa panjang, seperti persediaan dalam ruang kerja Claude Code pada VPS dengan tmux, tidak mempunyai ingatan tentang perbualan semalam. Repositori ialah ingatannya. Segala-galanya yang anda jelaskan dalam sembang dan tidak pernah dilakukan commit akan hilang menjelang sesi seterusnya, dan DESIGN.md ialah tempat di mana penjelasan itu disimpan supaya ia kekal.

Mulakan dengan keputusan yang anda pertikaikan

Versi pertama mengambil masa dua puluh minit. Buka beberapa pull request terakhir yang mana penyemak menulis "tidak, kami melakukannya secara berbeza di sini". Setiap komen tersebut merupakan invarian yang tidak pernah ditulis, dan setiap satunya adalah tempat di mana ejen akan melakukan kesilapan yang sama, dengan lebih pantas dan lebih kerap berbanding manusia. Tambahkan pada fail tersebut apabila ia mengecewakan anda, bukan mengikut jadual. Jika anda masih mencari di mana ejen sesuai dalam aliran kerja pembangunan biasa, panduan 2026 untuk mempelajari ejen AI ialah langkah seterusnya yang munasabah.

FAQ

Adakah DESIGN.md satu standard rasmi?

Tidak seperti AGENTS.md. AGENTS.md mempunyai laman rasmi di agents.md, digunakan oleh lebih 60,000 projek sumber terbuka, dan diuruskan di bawah Agentic AI Foundation, sebahagian daripada Linux Foundation. Sehingga Ogos 2026, DESIGN.md tidak mempunyai badan pentadbir mahupun spesifikasi yang diterbitkan. Apa yang ia miliki ialah penggunaan pihak pertama: tujuh syarikat, termasuk Vercel, Nuxt, Atlassian dan Resend, menerbitkannya pada URL awam, dan satu koleksi komuniti menyimpan 73 lagi yang diolah semula daripada tapak awam. Anggap ia sebagai konvensyen yang boleh anda guna pakai sekarang dan perluaskan secara bebas, kerana tiada apa yang mengesahkan nama seksyen anda.

Patutkah DESIGN.md hanya menjadi satu seksyen dalam AGENTS.md?

Untuk repositori kecil, ya. Satu fail yang pasti dibaca oleh ejen adalah lebih baik daripada dua fail di mana salah satunya diabaikan. Asingkan fail tersebut apabila AGENTS.md tidak lagi mudah diimbas, atau apabila anda mendapati kedua-dua bahagian berubah pada kadar yang berbeza. AGENTS.md berubah apabila binaan (build) berubah. DESIGN.md berubah apabila sesuatu keputusan berubah, yang mana lebih jarang berlaku dan membawa impak yang lebih besar. Apabila anda mengasingkannya, tambah satu baris dalam AGENTS.md yang mengarahkan ejen untuk membaca DESIGN.md sebelum menyunting kod, kerana tidak semua alat memuatkan setiap fail markdown dalam direktori root.

Bagaimanakah DESIGN.md berbeza daripada architecture decision record?

ADR (architecture decision record) ialah rekod bertarikh bagi satu keputusan, dan projek yang sihat akan mengumpulkan berpuluh-puluh rekod sedemikian dalam satu folder. Itu adalah sejarah, dan sejarah mahal untuk dimuatkan, kerana ejen perlu membaca kesemuanya untuk menentukan yang mana masih relevan. DESIGN.md ialah keadaan semasa, ditulis untuk dibaca sepenuhnya bagi setiap tugasan. Simpan kedua-duanya jika anda sudah menulis ADR. ADR menyatakan apa yang diputuskan dan bila. DESIGN.md menyatakan apa yang benar pada hari ini, dan itulah fail yang perlu anda rujuk kepada ejen.

Berapa panjangkah DESIGN.md sepatutnya?

Cukup pendek untuk dimuatkan pada setiap pusingan tanpa beban. Contoh yang diterbitkan adalah panjang kerana ia menentukan keseluruhan bahasa visual: fail Nuxt mengandungi kira-kira 2,100 patah perkataan dan fail Vercel kira-kira 6,500 sehingga Ogos 2026. Servis backend biasanya memerlukan jauh lebih sedikit. Mulakan dengan satu halaman dan tambah kandungannya hanya apabila ejen melakukan kesilapan yang boleh dielakkan dengan satu ayat sahaja. Panjang bukan pengukur. Setiap baris sepatutnya merupakan perkara yang jika tidak ditulis, akan menyebabkan ejen melakukan kesilapan.