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 dalam 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 tersebut:

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

Sehingga Oktober 2026, ia menyenaraikan sebelas entiti: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel dan VoltAgent. Setiap fail terletak pada URL awam, kebanyakannya pada domain penerbit sendiri dan selebihnya dalam repositori GitHub awam, 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 perkara yang dibincangkan, kerana bahagian yang berguna adalah bentuk penulisan tersebut dan bukannya topik itu sendiri.

Fail Nuxt mempunyai kira-kira 2,000 patah perkataan setakat 27 Oktober 2026, dan kebanyakannya merupakan peraturan yang disertakan dengan alasannya. Ia bermula dengan menyatakan bahawa mod gelap (dark mode) adalah tema lalai. Ia menyenaraikan warna jenama hijau #00DC82 dengan nota bahawa warna jenama adalah "Untuk logo, imej sosial, dan cetakan. Jangan gunakannya sebagai nilai mentah dalam kod UI." Menjelang bahagian akhir, satu seksyen yang bertajuk Reject these mengandungi:

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

Fail Vercel lebih panjang, kira-kira 6,000 patah perkataan setakat Oktober 2026, dan ia melangkah lebih jauh. Salah satu tajuknya ialah Reject generated-design reflexes. Di bawahnya terdapat senarai perkara yang akan dicapai oleh penjana (generator) 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 tersebut mentakrifkan jenis fail ini. Ia merupakan senarai bertulis mengenai nilai lalai yang dihasilkan oleh model yang yakin, diterbitkan supaya model tersebut berhenti menghasilkannya. Setiap DESIGN.md yang wajar dilakukan (commit) adalah senarai tersebut untuk sesuatu domain.

Mengapa syarikat menerbitkan DESIGN.md mereka sendiri?

Komuniti telah mendahului perkara ini. awesome-design-md mengandungi 84 fail yang diekstrak daripada laman web awam, berdasarkan kiraan pada README setakat 27 Oktober 2026. Setiap satunya ditulis mengikut format sembilan bahagian yang sama, supaya ejen boleh diarahkan kepada satu fail 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 disalin (scrape) 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.

Sebelas penerbit masih merupakan jumlah yang kecil, dan repositori tersebut sendiri menyatakan perkara itu: 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 baca senarai tersebut sebagai penjejak dan bukannya bancian neutral. Ia masih berbaloi untuk dipantau, disebabkan oleh siapa yang tersenarai di dalamnya. Beberapa daripadanya adalah syarikat yang kod bahagian hadapan (front-end) mereka paling banyak disalin oleh pembangun lain, dan penyertaan yang lebih baharu, Ant Design, Microsoft FAST, Juspay dan Oxide Computer, adalah sistem reka bentuk yang dibina oleh pasukan lain. Fail mereka menjadi contoh kerja tentang apakah 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. DESIGN.md telah mula menempuh jalan yang sama. Pada 21 April 2026, Google telah membuka sumber (open-source) draf spesifikasi untuk format tersebut, diterbitkan sebagai google-labs-code/design.md dengan skema token dan CLI di bawah lesen Apache-2.0. Setakat Oktober 2026, format ini berada pada versi alpha dan masih dalam pembangunan aktif, ia diselenggara oleh Google Labs dan bukannya yayasan neutral, dan ia menerangkan identiti visual, jadi ia tidak menyatakan apa-apa tentang invarian yang diperlukan oleh fail bahagian belakang (backend). 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 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. DESIGN.md mempunyai spesifikasi yang diterbitkan tetapi tiada pengurus neutral. Google mengeluarkan draf spesifikasi sumber terbuka pada 21 April 2026, dan ia disimpan dalam repositori google-labs-code/design.md di bawah lesen Apache-2.0. Setakat Oktober 2026, ia berada pada versi alpha dan masih dalam pembangunan aktif, serta menerangkan identiti visual: warna, tipografi, susun atur dan komponen. DESIGN.md juga mempunyai penggunaan pihak pertama: sebelas syarikat dan projek, termasuk Vercel, Nuxt, Atlassian dan Resend, menerbitkannya, dan koleksi komuniti mengandungi 84 lagi yang diekstrak daripada laman awam setakat 27 Oktober 2026. Untuk fail bahagian belakang (backend) yang mengandungi invarian dan alternatif yang ditolak, anggap ia sebagai konvensyen yang boleh anda guna pakai sekarang dan kembangkan secara bebas, kerana tiada spesifikasi yang meliputi nama seksyen tersebut.

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 alatan memuatkan setiap fail markdown dalam direktori akar.

Bagaimanakah DESIGN.md berbeza daripada rekod keputusan seni bina (ADR)?

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, memandangkan ejen perlu membaca kesemuanya untuk menentukan yang mana masih relevan. DESIGN.md ialah keadaan semasa, ditulis untuk dibaca sepenuhnya pada setiap tugasan. Simpan kedua-duanya jika anda sudah menulis ADR. ADR menyatakan apa yang diputuskan dan bila. DESIGN.md menyatakan apa yang benar hari ini, dan itulah fail yang perlu anda rujuk kepada ejen.

Berapa panjangkah DESIGN.md sepatutnya?

Cukup pendek untuk dimuatkan pada setiap pusingan tanpa bebanan. Contoh yang diterbitkan adalah panjang kerana ia menentukan keseluruhan bahasa visual: fail Nuxt mempunyai kira-kira 2,000 perkataan dan fail Vercel kira-kira 6,000 setakat Oktober 2026. Servis bahagian belakang biasanya memerlukan jauh lebih sedikit. Mulakan dengan satu halaman dan kembangkan hanya apabila ejen melakukan kesilapan yang boleh dicegah dengan satu ayat sahaja. Panjang bukan ukuran. Setiap baris sepatutnya merupakan perkara yang ejen akan tersilap jika ia tidak dinyatakan.