DESIGN.md: Mengapa Kode Repository Disusun Begitu

Apa itu DESIGN.md dan hal-hal yang tidak dicakup oleh AGENTS.md

DESIGN.md adalah file Markdown di root repository yang menjelaskan kepada agen coding AI mengapa kode disusun seperti itu. AGENTS.md menjawab pertanyaan yang berbeda: bagaimana bekerja di sini, termasuk perintah build, perintah pengujian, lint yang harus berhasil, dan path yang tidak boleh diubah. DESIGN.md mencatat keputusan yang sudah ditetapkan serta hal-hal yang akan rusak jika salah satunya dibatalkan.

Agen coding, yaitu tool seperti Claude Code atau Cursor yang membaca dan mengedit repository Anda secara mandiri, secara default bersikap yakin. Agen tersebut menemukan pola yang tidak dikenalnya lalu memperbaiki pola itu. Cache yang ditulis secara manual diubah menjadi Redis (penyimpanan data dalam memori), karena itulah bentuk cache dalam sebagian besar kode yang pernah dibaca model. AGENTS.md tidak mencegah hal ini, karena make test tetap berhasil dengan kedua cara tersebut. Aturan yang dilanggar tidak pernah ditulis di tempat yang dapat dibaca oleh agen.

Jika Anda belum menulis file pertama, mulailah dari sana. AGENTS.md dan HUMAN.md yang berada di sebelahnya menjelaskan formatnya dan lokasi yang diperiksa setiap tool. Bagian berikutnya adalah bab setelah bab tersebut.

Apa yang sebenarnya ada di dalam DESIGN.md yang dipublikasikan

Cara tercepat untuk mempelajari format ini adalah membaca file yang dipublikasikan perusahaan tentang dirinya sendiri. Repositori official-design-md hanya melacak file tersebut. Aturan penyertaannya 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.

Per Agustus 2026, repositori tersebut mencantumkan tujuh perusahaan: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel, dan VoltAgent. Setiap file berada di URL publik yang stabil, sehingga Anda dapat membacanya langsung di terminal.

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

Keduanya adalah dokumen design system. Dokumen tersebut menjelaskan tampilan produk: warna, tipografi, spasi, dan animasi. Jangan berhenti pada topiknya, karena bagian yang berguna adalah struktur penulisannya, bukan topiknya.

File Nuxt terdiri dari sekitar 2,100 kata, dan sebagian besar isinya berupa aturan beserta 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"`.

File Vercel lebih panjang, sekitar 6,500 kata pada Agustus 2026, dan melangkah lebih jauh. Salah satu heading-nya adalah Reject generated-design reflexes. Di bawahnya terdapat daftar hal yang akan dipilih oleh generator yang mampu ketika tidak ada 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.

Kalimat tersebut mendefinisikan jenis file ini. DESIGN.md adalah daftar tertulis berisi default yang dihasilkan model dengan penuh keyakinan, lalu dipublikasikan agar model berhenti menghasilkannya. Setiap DESIGN.md yang layak di-commit adalah daftar tersebut untuk domain tertentu.

Mengapa perusahaan menerbitkan DESIGN.md mereka sendiri?

Komunitas sudah lebih dahulu melakukannya. awesome-design-md berisi 73 file yang direkayasa balik dari situs web publik. Setiap file ditulis dalam format sembilan bagian yang sama, sehingga agent dapat diarahkan ke salah satunya untuk menghasilkan tampilan yang mendekati aslinya. File-file tersebut berguna, tetapi tetap merupakan perkiraan. Tidak ada pihak dari perusahaan terkait yang meninjaunya.

File dari pihak pertama berbeda karena file tersebut merupakan sumbernya, bukan interpretasi atas hasil akhir. Saat Vercel mengubah skala tipografinya, vercel.com/design.md ikut berubah. Salinan yang diambil melalui scraping pada bulan Maret akan terus mengajarkan skala lama kepada agent, dan tidak ada yang menunjukkan di repository Anda bahwa salinan tersebut sudah usang.

Tujuh penerbit adalah jumlah yang kecil, dan repository tersebut menyatakannya dengan jelas: standarnya masih baru dan adopsi resmi terus meningkat. Kedua koleksi tersebut dikelola oleh VoltAgent, framework agent open source yang juga menerbitkan filenya sendiri. Karena itu, anggap daftar tersebut sebagai pelacak, bukan sensus netral. Daftar ini tetap layak dipantau berdasarkan siapa ketujuh perusahaan tersebut. Mereka adalah perusahaan yang kode front-end-nya paling sering disalin oleh developer lain, dan file mereka mulai menjadi contoh penerapan DESIGN.md. Perhatikan perkembangan AGENTS.md: agents.md kini mencatat lebih dari 60.000 proyek open source yang menggunakan format tersebut, dan pengelolaannya berada di bawah Agentic AI Foundation dalam Linux Foundation. Konvensi untuk file yang dapat dibaca agent sedang ditetapkan dengan cepat, dan penetapannya dimulai dari perusahaan-perusahaan terkemuka.

Apa yang perlu dicantumkan dalam DESIGN.md jika proyek tidak memiliki antarmuka pengguna

Sebagian besar software yang berjalan pada VPS tidak memiliki bahasa visual yang perlu ditentukan. File ini tetap berguna karena mekanismenya tidak berkaitan dengan warna. Isinya adalah batasan yang perlu ditulis agar editor yang yakin tidak melanggarnya tanpa menyadarinya.

Invarian. Tulis satu kalimat untuk setiap invarian. Setiap kalimat harus menyatakan sesuatu yang harus tetap benar setelah pengeditan apa pun. "Setiap operasi tulis dilakukan melalui queue.enqueue(). Penulisan langsung ke database melewati audit log, sedangkan audit log digunakan oleh ekspor kepatuhan." Invarian yang disertai alasannya tetap berlaku ketika menghadapi tugas yang tidak pernah Anda antisipasi. Invarian tanpa alasan akan terbaca sebagai preferensi, dan preferensi akan dihapus demi optimasi.

Alternatif yang ditolak. Jelaskan opsi yang paling jelas dan alasan opsi tersebut ditolak. "Kami tidak menggunakan Redis untuk caching. Service berjalan pada satu VPS, sehingga map dalam proses lebih cepat dan mengurangi satu daemon yang harus tetap aktif. Tinjau kembali keputusan ini jika server aplikasi kedua tersedia." Tanpa paragraf tersebut, agent yang diminta mempercepat cache akan menambahkan Redis, dan tindakan itu benar: Anda tidak pernah memberitahukan batasannya. Bagian inilah yang membuat seluruh file tersebut bermanfaat.

Batasan. Cantumkan bagian yang dapat menyebabkan dampak besar akibat pengeditan kecil. Misalnya, skema database. Prefix route publik yang sudah digunakan dalam script pelanggan. File konfigurasi yang dibaca saat deploy sebelum aplikasi dimulai. Entri cron yang mengasumsikan hanya satu salinannya berjalan. Sebutkan semuanya dan jelaskan dampak setiap perubahan. Jika agent juga dapat mengakses web terbuka, misalnya melalui instance SearXNG self-hosted yang dikonfigurasi sebagai backend pencariannya, hal itu juga merupakan batasan yang perlu dicatat. File tersebut harus menjelaskan teks hasil pengambilan yang boleh memengaruhi kode dan teks yang hanya boleh dikutip kembali kepada Anda.

Kosakata. Jika kode menggunakan tenant sedangkan tim menggunakan customer, catat pemetaannya. Agent yang keliru menebak pemetaan ini dapat menghasilkan kode yang terbaca baik tetapi memodelkan hal yang salah. Kesalahan seperti ini paling sulit ditemukan saat review.

DESIGN.md yang dapat 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 bagian yang dapat Anda tulis dari ingatan hari ini, yaitu invariants dan alternatif yang ditolak, lalu biarkan bagian lainnya tetap sebagai heading. File dengan empat baris yang jujur akan berfungsi. File dengan empat puluh baris tebakan tidak akan berfungsi. Jika repository berisi beberapa package, satu file di root tidak akan cocok untuk semuanya. Pemisahan per direktori yang sama seperti file AGENTS.md bertingkat dalam monorepo juga berlaku di sini: file root yang singkat untuk keputusan yang berlaku bersama, dan file yang lebih kecil di samping setiap package yang memiliki keputusan sendiri.

Beberapa tool memuat setiap file markdown di root repository, sedangkan tool lainnya hanya memuat file yang ditentukan secara eksplisit. Karena itu, jangan berasumsi. Tambahkan rujukan ke AGENTS.md:

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

Pola anti: DESIGN.md yang mengulang README

Versi buruk yang paling umum terlihat rapi, tetapi tidak mengajarkan apa pun. Isinya diawali dengan penjelasan tentang fungsi project, dilanjutkan dengan daftar fitur, cara menginstalnya, lalu ditutup dengan lisensi. Semua informasi itu sudah ada di README, dan tidak ada yang menjelaskan alasan di balik setiap keputusan.

Hal ini membuat Anda menanggung biaya dua kali. Biaya pertama adalah konteks. File yang dibaca agent pada awal setiap task akan menggunakan sebagian konteks pada setiap task, sedangkan bagian instalasi yang diduplikasi hanya menjadi beban tambahan dalam jendela yang ukurannya tetap. Pengelolaan jendela tersebut merupakan keterampilan tersendiri, yang dibahas dalam mengelola jendela konteks di Claude Code. Intinya: semua hal yang dimuat secara otomatis harus menjadi teks dengan nilai tertinggi di repository.

Biaya kedua lebih buruk. Dua salinan pernyataan yang sama dapat berbeda seiring waktu. README menyatakan bahwa service mendengarkan pada port 8080, sedangkan DESIGN.md masih menyatakan 3000. Agent tidak memiliki cara untuk menentukan mana yang lebih utama, sehingga agent memilih salah satunya lalu menulis code berdasarkan pilihan tersebut. File yang terkadang salah akan dikonsultasikan dengan tingkat keyakinan yang sama seperti file yang selalu benar.

Pengujiannya cepat. Jika sebuah paragraf dapat ditempatkan dengan wajar di README, hapus paragraf itu dari DESIGN.md. Sisanya harus berisi hal-hal yang akan Anda sampaikan langsung dalam code review, yaitu bagian yang dimulai dengan "kita sudah pernah mencoba itu".

Bagaimana Anda mengetahui bahwa file tersebut berfungsi?

Tidak ada linter untuk file ini. Ada pemeriksaan yang dapat Anda jalankan dalam satu menit.

Berikan tugas kepada agent yang langsung menguji invariant. “Tambahkan background job yang menandai baris kedaluwarsa sebagai expired.” File yang berfungsi akan terlihat dalam jawaban sebelum kode apa pun ditulis: agent seharusnya memberi tahu Anda bahwa job tersebut menulis melalui queue.enqueue(), karena penulisan langsung akan melewati audit log. Jika agent membuka koneksi database lalu menulis, salah satu dari dua hal berikut benar. File tersebut sama sekali tidak dibaca, atau invariant dirumuskan terlalu longgar sehingga masih dapat diperdebatkan.

Perhatikan juga jumlah token, karena file ini dimuat pada setiap giliran. Jika penggunaan konteks meningkat setelah Anda menambahkan DESIGN.md tetapi jawabannya tidak menjadi lebih baik, file tersebut memuat prosa yang sebenarnya sudah diketahui agent. Membaca penghitung token di Claude Code menunjukkan ke mana anggaran tersebut digunakan.

Hal ini paling penting ketika agent berjalan di server, bukan di laptop Anda. Agent yang bekerja dalam session jangka panjang, seperti konfigurasi pada workspace Claude Code di VPS dengan tmux, tidak memiliki ingatan tentang percakapan kemarin. Repository adalah memorinya. Semua hal yang Anda jelaskan melalui chat tetapi tidak pernah di-commit akan hilang pada session berikutnya, dan DESIGN.md adalah tempat untuk menyimpan penjelasan tersebut agar tetap tersedia.

Mulai dari keputusan yang sering diperdebatkan

Versi pertama dapat diselesaikan dalam dua puluh menit. Buka beberapa pull request terakhir yang memuat komentar reviewer seperti "tidak, di sini kami melakukannya dengan cara berbeda". Setiap komentar tersebut adalah invariant yang belum pernah ditulis, sekaligus titik tempat agent akan melakukan kesalahan yang sama dengan lebih cepat dan lebih sering daripada manusia. Tambahkan aturan ke file ketika aturan tersebut gagal mencegah kesalahan, bukan berdasarkan jadwal. Jika Anda masih menentukan posisi agent dalam alur kerja pengembangan yang normal, panduan mempelajari AI agent pada 2026 dapat menjadi langkah berikutnya yang tepat.

FAQ

Apakah DESIGN.md merupakan standar resmi?

Tidak dalam pengertian yang sama seperti AGENTS.md. AGENTS.md memiliki situs di agents.md, digunakan oleh lebih dari 60,000 proyek open source, dan berada di bawah pengelolaan Agentic AI Foundation, bagian dari Linux Foundation. Per Agustus 2026, DESIGN.md tidak memiliki badan pengelola maupun spesifikasi yang dipublikasikan. Yang dimilikinya adalah adopsi langsung dari pengembang: tujuh perusahaan, termasuk Vercel, Nuxt, Atlassian, dan Resend, menerbitkannya pada URL publik, sementara sebuah koleksi komunitas memuat 73 dokumen lain yang direkayasa balik dari situs publik. Perlakukan ini sebagai konvensi yang dapat Anda adopsi sekarang dan kembangkan secara bebas, karena tidak ada mekanisme yang memvalidasi nama bagian Anda.

Apakah DESIGN.md sebaiknya hanya menjadi bagian dari AGENTS.md?

Untuk repositori kecil, ya. Satu file yang pasti dibaca oleh agent lebih baik daripada dua file yang salah satunya diabaikan. Pisahkan keduanya ketika AGENTS.md tidak lagi mudah dipindai, atau ketika Anda melihat kedua bagian tersebut berubah dengan frekuensi berbeda. AGENTS.md berubah ketika proses build berubah. DESIGN.md berubah ketika sebuah keputusan berubah, yang lebih jarang terjadi dan memiliki dampak lebih besar. Setelah memisahkannya, tambahkan satu baris ke AGENTS.md yang meminta agent membaca DESIGN.md sebelum mengedit kode, karena tidak semua tool memuat setiap file markdown di root.

Apa perbedaan DESIGN.md dan architecture decision record?

ADR (architecture decision record) adalah catatan bertanggal tentang satu keputusan, dan proyek yang dikelola dengan baik akan mengumpulkan puluhan ADR dalam sebuah folder. Itu merupakan riwayat, dan riwayat mahal untuk dimuat karena agent harus membaca semuanya untuk menentukan mana yang masih berlaku. DESIGN.md berisi kondisi saat ini dan ditulis agar dibaca seluruhnya pada setiap tugas. Tetap gunakan keduanya jika Anda sudah menulis ADR. ADR menjelaskan apa yang diputuskan dan kapan. DESIGN.md menjelaskan apa yang benar saat ini, dan file inilah yang Anda arahkan untuk dibaca oleh agent.

Seberapa panjang DESIGN.md seharusnya?

Cukup pendek agar dapat dimuat pada setiap giliran tanpa menimbulkan beban. Contoh yang dipublikasikan berukuran panjang karena menjelaskan seluruh bahasa visual: file Nuxt berisi sekitar 2,100 kata dan file Vercel sekitar 6,500 kata per Agustus 2026. Service backend biasanya membutuhkan jauh lebih sedikit. Mulailah dari satu halaman dan tambah isinya hanya ketika agent melakukan kesalahan yang seharusnya dapat dicegah oleh satu kalimat. Panjang bukanlah ukurannya. Setiap baris harus menjelaskan sesuatu yang mungkin salah dilakukan agent jika tidak diberi informasi tersebut.