Apa itu DESIGN.md dan beza dengan AGENTS.md

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

DESIGN.md ialah fail markdown di pangkal repositori anda yang memberitahu ejen pengekodan AI mengapa kod tersebut dibentuk sedemikian. AGENTS.md menjawab soalan yang berbeza: cara 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 dengan sendirinya, adalah yakin secara lalai. Ia menemui corak yang tidak dikenalinya dan ia menambah baik corak tersebut. Cache tulisan 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 walau apa pun. Peraturan yang dilanggar itu tidak pernah ditulis di mana-mana tempat yang boleh dibaca oleh ejen tersebut.

Jika anda belum menulis fail pertama itu lagi, mulakan di situ. AGENTS.md dan HUMAN.md yang terletak di sebelahnya merangkumi 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 mengenai diri mereka sendiri. Repositori official-design-md hanya menjejaki fail-fail tersebut. Peraturan kemasukannya adalah satu baris, dan baris itu merupakan tujuan utama koleksi tersebut:

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, jarak, gerakan. Baca melangkaui perkara yang dibincangkan, kerana bahagian yang berguna adalah bentuk penulisan tersebut dan bukannya topik itu sendiri.

Fail Nuxt mempunyai 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 dicapai oleh penjana yang berkebolehan apabila tiada sesiapa yang memberitahunya untuk tidak berbuat demikian:

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 tetapan 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 asal 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 sudah lapuk.

Tujuh penerbit adalah jumlah yang kecil, dan repositori tersebut menyatakan perkara yang sama: standard 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 baca 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 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 daripada pihak 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 terus ke pangkalan data melangkau log audit, dan 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 akan dibaca sebagai keutamaan, dan keutamaan biasanya akan dioptimumkan sehingga hilang.

Alternatif yang ditolak. Pilihan yang nyata, dan sebab ia ditolak. "Kami tidak menggunakan Redis untuk caching. Servis ini dijalankan pada satu VPS, jadi peta dalam proses adalah lebih pantas dan ia mengurangkan satu daemon yang perlu dikekalkan. 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 daripadanya yang berjalan. Namakan setiap satu, dan nyatakan kos untuk mengubahnya. Jika ejen juga boleh mencapai web terbuka, contohnya 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 yang dibenarkan untuk mempengaruhi kod dan yang mana hanya boleh 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.

Isi 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 tekaan tidak akan membantu. Jika repositori mengandungi beberapa pakej, satu fail akar tidak akan sesuai untuk kesemuanya, dan pembahagian per-direktori yang sama yang berkesan untuk fail AGENTS.md bersarang dalam monorepo juga terpakai di sini: fail akar yang ringkas untuk keputusan yang dikongsi oleh semua, dan fail yang lebih kecil di sebelah setiap pakej yang mempunyai keputusannya sendiri.

Sesetengah alatan memuatkan setiap fail markdown dalam akar repositori dan sesetengah alatan hanya memuatkan fail yang diarahkan, 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

Alternatif yang ditolak

Keputusan

Konteks dan akibat

Anti-pattern: 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, menerangkan cara pemasangan, dan diakhiri dengan lesen. Setiap baris tersebut sudah pun ada dalam README, dan tiada satu pun yang menjelaskan mengapa sesuatu perkara itu dibuat sedemikian.

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 adalah beban tulen terhadap tetingkap konteks yang tetap. 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 paling bernilai 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 yang mana satu 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 sesuai dalam README, buang ia daripada DESIGN.md. Apa yang tinggal sepatutnya adalah bahagian yang akan anda sebutkan dengan lantang semasa semakan kod, bahagian yang bermula dengan "kami sudah mencuba perkara itu".

Bagaimanakah anda tahu fail tersebut berfungsi?

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

Berikan ejen tugasan yang terus menjurus kepada invarian. "Tambah kerja latar belakang yang menandakan baris lapuk sebagai tamat tempoh." Fail yang menjalankan tugasnya akan muncul dalam jawapan sebelum sebarang kod diberikan: 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 dimiliki oleh ejen. Membaca pembilang token dalam Claude Code menunjukkan ke mana perginya bajet tersebut.

Perkara ini paling penting apabila ejen berada pada pelayan dan bukannya pada komputer riba anda. Ejen yang bekerja dalam sesi yang berjalan lama, 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 penjelasan itu diletakkan 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, kita lakukan 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 gagal membantu anda, bukan mengikut jadual. Jika anda masih memikirkan di mana ejen sesuai dalam aliran kerja pembangunan biasa, panduan 2026 untuk mempelajari ejen AI adalah 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 ada hanyalah penggunaan pihak pertama: tujuh syarikat, termasuk Vercel, Nuxt, Atlassian dan Resend, menerbitkannya pada URL awam, dan 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 sekadar 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 alatan memuatkan setiap fail markdown di 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 mengumpul berpuluh-puluh rekod sedemikian di dalam satu folder. Itu adalah sejarah, dan sejarah memakan kos yang tinggi untuk dimuatkan, kerana ejen perlu membaca kesemuanya untuk menentukan keputusan mana yang masih sah. DESIGN.md ialah keadaan semasa, yang 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 ia adalah fail yang perlu anda rujuk kepada ejen.

Berapa panjangkah DESIGN.md sepatutnya?

Cukup pendek untuk dimuatkan pada setiap giliran tanpa rasa rugi. Contoh-contoh yang diterbitkan adalah panjang kerana ia menentukan keseluruhan bahasa visual: fail Nuxt mengandungi kira-kira 2,100 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 dicegah dengan satu ayat sahaja. Panjang bukan pengukur. Setiap baris sepatutnya merupakan perkara yang jika tidak dinyatakan, akan menyebabkan ejen melakukan kesilapan.