DESIGN.md: Fail Selepas AGENTS.md untuk Ejen Kod

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

DESIGN.md ialah fail markdown dalam akar repositori anda yang menerangkan sebab kod dibentuk sedemikian. AGENTS.md menjawab soalan yang berbeza: cara bekerja dalam repositori ini, termasuk perintah binaan, perintah ujian, lint yang mesti lulus dan laluan yang tidak boleh diubah. DESIGN.md merekodkan keputusan yang telah dimuktamadkan serta perkara yang akan rosak jika keputusan itu diubah.

Ejen pengekodan, iaitu alat seperti Claude Code atau Cursor yang membaca dan mengedit repositori anda secara kendiri, secara lalainya mempunyai keyakinan tinggi. Ejen itu menemui corak yang tidak dikenalinya lalu menambah baik corak tersebut. Cache yang ditulis secara manual menjadi Redis (stor data dalam memori), kerana itulah rupa cache dalam kebanyakan kod yang telah dibaca oleh model. AGENTS.md tidak menghalang perkara ini kerana make test lulus dalam kedua-dua keadaan. Peraturan yang dilanggar itu tidak pernah ditulis di mana-mana lokasi yang boleh dibaca oleh ejen.

Jika anda belum menulis fail pertama itu, mulakan dengan fail tersebut. AGENTS.md dan HUMAN.md yang terletak di sebelahnya menerangkan formatnya dan lokasi yang dicari oleh setiap alat. Perkara berikut ialah bab selepas bab itu.

Perkara sebenar yang terdapat 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 hanya menjejaki fail tersebut. Peraturan kemasukannya hanya satu baris, dan baris itulah inti koleksi ini:

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

Setakat Ogos 2026, repositori itu menyenaraikan tujuh syarikat: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel dan VoltAgent. Setiap fail berada pada URL awam yang stabil, jadi anda boleh membacanya dalam terminal sekarang.

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

Kedua-duanya ialah dokumen sistem reka bentuk. Dokumen tersebut menerangkan rupa sesuatu produk: warna, tipografi, jarak dan gerakan. Lihat melangkaui perkara yang dibincangkan, kerana bahagian yang berguna ialah bentuk penulisannya, bukan topiknya.

Fail Nuxt mengandungi kira-kira 2,100 perkataan, dan sebahagian besarnya terdiri daripada peraturan berserta sebabnya:

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, kira-kira 6,500 perkataan pada Ogos 2026, dan melangkah lebih jauh. Salah satu tajuknya ialah Reject generated-design reflexes. Di bawahnya terdapat senarai perkara yang akan digunakan oleh penjana berkeupayaan apabila tiada sesiapa memberitahunya supaya tidak menggunakannya:

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 ini. DESIGN.md ialah senarai bertulis tentang tetapan lalai yang dihasilkan oleh model yang yakin, diterbitkan supaya model itu berhenti menghasilkannya. Setiap DESIGN.md yang wajar dihantar ke repositori ialah senarai tersebut untuk sesuatu domain.

Mengapa syarikat menerbitkan DESIGN.md mereka sendiri?

Komuniti memulakannya terlebih dahulu. awesome-design-md mengandungi 73 fail yang direka bentuk semula berdasarkan laman web awam. Setiap fail menggunakan format sembilan bahagian yang sama. Ejen boleh diarahkan kepada salah satu fail itu untuk menghasilkan sesuatu yang hampir menyerupai reka bentuk tersebut. Fail-fail ini berguna, tetapi masih merupakan anggaran. Tiada pihak daripada syarikat berkenaan yang menyemaknya.

Fail pihak pertama berbeza kerana fail itu ialah sumber, bukan tafsiran terhadap hasil akhir. Apabila Vercel mengubah skala tipografinya, vercel.com/design.md turut berubah. Salinan yang dikikis pada bulan Mac akan terus mengajar ejen anda skala lama. Tiada apa-apa dalam repositori anda yang akan memberitahu bahawa salinan itu sudah lapuk.

Tujuh penerbit ialah jumlah yang kecil, dan repositori itu menyatakan perkara yang sama: standard ini masih baharu dan penerimaan rasmi semakin meningkat. Kedua-dua koleksi diselenggara oleh VoltAgent, iaitu rangka kerja ejen sumber terbuka yang turut menerbitkan failnya sendiri. Oleh itu, anggap senarai ini sebagai penjejak, bukan banci neutral. Senarai ini masih wajar dipantau kerana identiti tujuh syarikat tersebut. Syarikat-syarikat ini ialah syarikat yang kod bahagian hadapannya paling kerap disalin oleh pembangun lain. Fail mereka semakin menjadi contoh praktikal tentang maksud DESIGN.md. Bandingkan laluan yang dilalui AGENTS.md: agents.md kini mengira lebih 60,000 projek sumber terbuka yang menggunakan format tersebut. Pengawasannya terletak pada Agentic AI Foundation di bawah Linux Foundation. Konvensyen untuk fail yang boleh dibaca ejen sedang ditetapkan dengan cepat, dan penetapan itu bermula daripada pihak atasan.

Apakah kandungan DESIGN.md apabila projek tidak mempunyai antara muka pengguna

Kebanyakan perisian yang berjalan pada VPS tidak mempunyai bahasa visual yang perlu ditentukan. Fail ini tetap berguna kerana mekanismenya tidak berkaitan dengan warna. Fail ini mendokumentasikan kekangan yang mungkin dilanggar oleh penyunting yang yakin tanpa disedari.

Invarian. Tulis satu ayat bagi setiap invarian untuk menyatakan perkara yang mesti kekal benar selepas sebarang pengeditan. "Setiap operasi tulis mesti melalui queue.enqueue(). Operasi tulis terus ke pangkalan data melangkau log audit, sedangkan eksport pematuhan membaca log audit." Invarian yang disertakan sebabnya tetap dipatuhi apabila berdepan dengan tugas yang tidak pernah anda jangkakan. Invarian tanpa sebab kelihatan seperti pilihan, dan pilihan biasanya akan diketepikan untuk pengoptimuman.

Alternatif yang ditolak. Nyatakan pilihan yang paling jelas dan sebab pilihan itu ditolak. "Kami tidak menggunakan Redis untuk caching. Perkhidmatan ini berjalan pada satu VPS, jadi peta dalam proses lebih pantas dan kami tidak perlu memastikan satu daemon tambahan terus berjalan. Nilai semula keputusan ini apabila pelayan aplikasi kedua tersedia." Tanpa perenggan itu, ejen yang diminta mempercepat cache akan menambah Redis, dan tindakan itu munasabah: anda tidak pernah memberitahunya tentang kekangan tersebut. Bahagian ini yang menjadikan keseluruhan fail berbaloi.

Sempadan. Nyatakan tempat yang perubahan kecil padanya boleh memberi kesan besar. Skema pangkalan data. Awalan laluan awam yang sudah digunakan dalam skrip pelanggan. Fail konfigurasi yang dibaca oleh proses deployment sebelum aplikasi dimulakan. Entri cron yang mengandaikan hanya satu salinannya berjalan. Namakan setiap satunya dan nyatakan kos perubahan padanya.

Perbendaharaan kata. Jika kod menggunakan tenant dan pasukan menggunakan customer, catatkan pemetaan itu. Ejen yang membuat tekaan salah di sini akan menghasilkan kod yang kelihatan betul tetapi memodelkan perkara yang salah. Kesilapan seperti ini paling sukar dikesan semasa semakan.

A 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, kemudian biarkan bahagian lain sebagai tajuk. Fail yang mempunyai empat baris yang jujur sudah memadai. Fail yang mempunyai empat puluh baris tekaan tidak memadai.

Sesetengah alat memuatkan setiap fail markdown dalam akar repositori, manakala sesetengah alat hanya memuatkan fail yang dinyatakan kepadanya. Oleh itu, jangan membuat 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.

Corak anti: DESIGN.md yang mengulangi README

Versi buruk yang paling biasa kelihatan kemas tetapi tidak memberikan panduan. Versi ini bermula dengan penerangan tentang fungsi projek, menyenaraikan ciri, menerangkan cara memasangnya, dan diakhiri dengan lesen. Semua maklumat itu sudah ada dalam README, dan tiada satu pun menerangkan sebab sesuatu keputusan dibuat.

Anda menanggung kos ini dua kali. Kos pertama ialah konteks. Fail yang dibaca ejen pada permulaan setiap tugasan perlu diproses dalam setiap tugasan, manakala bahagian pemasangan yang diduplikasi hanya menggunakan ruang dalam tetingkap konteks yang terhad. Pengurusan tetingkap itu sendiri ialah satu kemahiran, yang dibincangkan dalam mengurus tetingkap konteks dalam Claude Code. Ringkasnya: apa-apa yang dimuatkan secara automatik mestilah teks yang paling bernilai dalam repositori.

Kos kedua lebih serius. Dua salinan pernyataan yang sama boleh berbeza dari semasa ke semasa. README menyatakan bahawa servis mendengar pada 8080, tetapi DESIGN.md masih menyatakan 3000. Ejen tidak mempunyai cara untuk menentukan pernyataan yang lebih utama, lalu memilih salah satu dan menulis kod berdasarkan pernyataan itu. Fail yang kadangkala salah dirujuk dengan tahap keyakinan yang sama seperti fail yang sentiasa betul.

Ujiannya mudah. Jika sesuatu perenggan sesuai diletakkan dalam README, padamkan perenggan itu daripada DESIGN.md. Kandungan yang tinggal mestilah perkara yang akan anda nyatakan dengan jelas semasa semakan kod, iaitu perkara yang bermula dengan “kita sudah mencuba cara itu”.

Bagaimanakah anda mengetahui fail itu berfungsi?

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

Berikan ejen tugas yang terus berhadapan dengan invarian. "Tambahkan tugas latar belakang yang menandakan baris lapuk sebagai luput." Fail yang berfungsi dengan betul akan terlihat dalam jawapan sebelum sebarang kod ditulis: ejen sepatutnya memberitahu anda bahawa tugas itu menulis melalui queue.enqueue(), kerana penulisan terus akan melangkau log audit. Jika ejen membuka sambungan pangkalan data dan menulis, salah satu daripada dua perkara adalah benar. Fail itu langsung tidak dibaca, atau invarian tersebut dirumuskan dengan cukup longgar sehingga boleh dipertikaikan.

Pantau kiraan token juga, kerana fail ini dimuatkan pada setiap giliran. Jika penggunaan konteks meningkat selepas anda menambahkan DESIGN.md tetapi jawapan tidak menjadi lebih baik, fail itu mengandungi prosa yang sudah diketahui oleh ejen. Membaca pembilang token dalam Claude Code menunjukkan ke mana belanjawan itu digunakan.

Perkara ini paling penting apabila ejen berada pada server, 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 memorinya. Semua perkara yang anda terangkan dalam chat tetapi tidak pernah commit akan hilang pada sesi seterusnya, dan DESIGN.md ialah tempat penjelasan itu disimpan supaya kekal.

Mulakan dengan keputusan yang sering diperdebatkan

Versi pertama mengambil masa dua puluh minit. Buka beberapa pull request terakhir yang mengandungi ulasan penilai seperti "tidak, kita melakukannya secara berbeza di sini". Setiap ulasan itu ialah invarian yang tidak pernah didokumentasikan. Setiap satunya juga ialah keadaan yang akan menyebabkan ejen melakukan kesilapan yang sama, dengan lebih pantas dan lebih kerap berbanding manusia. Tambahkan kandungan pada fail apabila fail itu tidak membantu anda, bukan mengikut jadual. Jika anda masih menentukan cara ejen sesuai digunakan dalam aliran kerja pembangunan biasa, panduan 2026 untuk mempelajari ejen AI ialah langkah seterusnya yang munasabah.

FAQ

Adakah DESIGN.md standard rasmi?

Tidak seperti AGENTS.md. AGENTS.md mempunyai laman utama di agents.md, digunakan oleh lebih 60,000 projek sumber terbuka, serta diselenggara di bawah Agentic AI Foundation, sebahagian daripada Linux Foundation. Setakat August 2026, DESIGN.md tidak mempunyai badan pentadbir atau spesifikasi yang diterbitkan. Namun, DESIGN.md telah diterima pakai oleh pihak pertama: tujuh syarikat, termasuk Vercel, Nuxt, Atlassian dan Resend, menerbitkannya pada URL awam. Koleksi komuniti pula mengandungi 73 lagi fail yang direka bentuk semula berdasarkan tapak awam. Anggap DESIGN.md sebagai konvensyen yang boleh anda pakai sekarang dan kembangkan secara bebas, kerana tiada pihak yang mengesahkan nama bahagiannya.

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

Untuk repositori kecil, ya. Satu fail yang pasti dibaca oleh ejen lebih baik daripada dua fail apabila salah satunya diabaikan. Asingkan kedua-duanya apabila AGENTS.md tidak lagi mudah diimbas, atau apabila anda mendapati kedua-dua bahagian berubah pada kadar yang berbeza. AGENTS.md berubah apabila binaan berubah. DESIGN.md berubah apabila sesuatu keputusan berubah, yang berlaku lebih jarang dan mempunyai kesan yang lebih besar. Selepas mengasingkannya, tambahkan satu baris pada AGENTS.md yang mengarahkan ejen membaca DESIGN.md sebelum mengedit kod, kerana tidak semua alat memuatkan setiap fail markdown dalam root.

Apakah perbezaan DESIGN.md dengan rekod keputusan seni bina?

ADR (rekod keputusan seni bina) ialah rekod bertarikh bagi satu keputusan. Projek yang diurus dengan baik akan mengumpulkan berpuluh-puluh ADR dalam satu folder. Itu ialah sejarah, dan sejarah memerlukan kos pemuatan yang tinggi kerana ejen perlu membaca semuanya untuk menentukan perkara yang masih benar. DESIGN.md ialah keadaan semasa, dan ditulis untuk dibaca sepenuhnya pada setiap tugasan. Kekalkan kedua-duanya jika anda sudah menulis ADR. ADR menyatakan perkara yang diputuskan dan masanya. DESIGN.md menyatakan perkara yang benar pada hari ini, dan itulah fail yang anda rujukkan kepada ejen.

Berapa panjangkah DESIGN.md sepatutnya?

Cukup pendek untuk dimuatkan pada setiap giliran tanpa membebankan proses. Contoh yang diterbitkan adalah panjang kerana contoh tersebut menyatakan keseluruhan bahasa visual: fail Nuxt mengandungi kira-kira 2,100 perkataan dan fail Vercel kira-kira 6,500 perkataan setakat August 2026. Perkhidmatan backend biasanya memerlukan lebih sedikit kandungan. Mulakan dengan satu halaman dan tambah kandungan hanya apabila ejen melakukan kesilapan yang boleh dicegah dengan satu ayat. Panjang bukan ukurannya. Setiap baris hendaklah menyatakan perkara yang mungkin tersilap dilakukan oleh ejen.