DESIGN.md: File Penting Setelah AGENTS.md

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

DESIGN.md adalah file markdown di root repositori Anda yang menjelaskan kepada agen coding AI mengapa kode disusun seperti itu. AGENTS.md menjawab pertanyaan yang berbeda: cara 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 dan hal-hal yang rusak jika salah satunya dibatalkan.

Agen coding, yaitu alat seperti Claude Code atau Cursor yang membaca dan mengedit repositori Anda secara mandiri, secara default bertindak dengan yakin. Agen tersebut menemukan pola yang tidak dikenalnya lalu memperbaiki pola itu. Cache yang ditulis secara manual dapat diubah menjadi Redis (penyimpanan data dalam memori), karena itulah bentuk cache yang terdapat di 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 agen.

Jika Anda belum menulis file pertama, mulailah dari sana. AGENTS.md dan HUMAN.md yang berada di sebelahnya menjelaskan format dan lokasi yang diperiksa oleh setiap alat. 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 diri mereka sendiri. Repositori official-design-md hanya melacak file tersebut. Aturan penyertaannya hanya satu baris, dan baris itu adalah 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 sekarang melalui terminal.

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

Keduanya adalah dokumen sistem desain. Dokumen tersebut menjelaskan tampilan produk: warna, tipografi, jarak, dan gerakan. Abaikan bidang yang dibahas, karena bagian yang berguna adalah struktur penulisannya, bukan topiknya.

File Nuxt berisi sekitar 2,100 kata, dan sebagian besar isinya adalah aturan yang disertai 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 mengambil satu langkah lebih jauh. Salah satu judulnya adalah Reject generated-design reflexes. Di bawahnya terdapat daftar hal yang akan digunakan generator yang andal jika 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. Isinya adalah daftar tertulis tentang default yang dihasilkan model yang percaya diri, lalu dipublikasikan agar model berhenti menghasilkannya. Setiap DESIGN.md yang layak di-commit adalah daftar tersebut untuk suatu domain.

Mengapa perusahaan menerbitkan DESIGN.md mereka sendiri?

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

File pihak pertama berbeda karena merupakan sumbernya, bukan interpretasi atas hasil akhirnya. Saat Vercel mengubah skala tipografinya, vercel.com/design.md ikut berubah. Salinan yang diambil pada bulan Maret akan terus mengajarkan skala lama kepada agen Anda. Tidak ada hal di repositori Anda yang memberi tahu bahwa salinan tersebut sudah kedaluwarsa.

Tujuh penerbit adalah jumlah yang kecil, dan repositori tersebut menyatakannya demikian: standarnya masih baru dan adopsi resmi terus berkembang. Kedua koleksi dikelola oleh VoltAgent, framework agen open source yang juga menerbitkan file miliknya sendiri. Karena itu, anggap daftar tersebut sebagai pelacak, bukan sensus yang netral. Daftar ini tetap layak dipantau karena identitas ketujuh perusahaan tersebut. Mereka adalah perusahaan yang kode front-end-nya paling sering disalin oleh pengembang lain. File mereka menjadi contoh penerapan tentang DESIGN.md. Bandingkan dengan perkembangan AGENTS.md: agents.md kini mencatat lebih dari 60,000 proyek open source yang menggunakan format tersebut. Pengelolaannya berada di bawah Agentic AI Foundation dalam Linux Foundation. Konvensi untuk file yang dapat dibaca agen berkembang pesat, dan pembentukannya dimulai dari perusahaan-perusahaan terkemuka.

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

Sebagian besar perangkat lunak yang berjalan di VPS tidak memiliki bahasa visual yang perlu ditentukan. File ini tetap diperlukan karena mekanismenya tidak berkaitan dengan warna. Isinya adalah pencatatan batasan yang mungkin dilanggar oleh editor yang percaya diri tanpa menyadarinya.

Invarian. Tulis satu kalimat untuk setiap invarian yang menyatakan sesuatu yang harus tetap benar setelah pengeditan apa pun. "Setiap penulisan dilakukan melalui queue.enqueue(). Penulisan langsung ke database melewati log audit, sedangkan ekspor kepatuhan membaca log audit tersebut." Invarian yang disertai alasannya tetap berlaku saat menghadapi tugas yang tidak pernah Anda perkirakan. Invarian tanpa alasan akan terlihat seperti preferensi, dan preferensi biasanya dihapus demi optimasi.

Alternatif yang ditolak. Jelaskan opsi yang paling jelas dan alasan opsi tersebut tidak dipilih. "Kami tidak menggunakan Redis untuk caching. Layanan 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, agen yang diminta mempercepat cache akan menambahkan Redis, dan tindakannya benar: Anda tidak pernah memberitahukan batasannya. Bagian ini yang membuat seluruh file tersebut berguna.

Batasan. Cantumkan bagian yang dapat menimbulkan dampak besar akibat pengeditan kecil. Skema database. Awalan rute publik yang sudah digunakan dalam skrip pelanggan. File konfigurasi yang dibaca oleh proses deploy sebelum aplikasi dimulai. Entri cron yang mengasumsikan hanya satu salinannya berjalan. Sebutkan semuanya dan jelaskan dampak perubahan pada masing-masing bagian.

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

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 invariant dan alternatif yang ditolak, lalu biarkan bagian lainnya tetap sebagai heading. File dengan empat baris yang jujur sudah memadai. File dengan empat puluh baris tebakan tidak.

Beberapa alat memuat setiap file markdown di root repositori, sedangkan alat lainnya hanya memuat file yang ditentukan. Jadi, jangan berasumsi. Tambahkan referensi ke AGENTS.md:

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

Antipola: DESIGN.md yang mengulang README

Versi buruk yang paling umum tampak baik saat dibaca, tetapi tidak mengajarkan apa pun. Isinya diawali dengan penjelasan tentang fungsi proyek, dilanjutkan dengan daftar fitur, petunjuk instalasi, lalu ditutup dengan lisensi. Semua informasi itu sudah ada di README, dan tidak ada yang menjelaskan alasan di balik keputusan tersebut.

Hal ini menimbulkan dua kerugian. Kerugian pertama adalah konteks. File yang dibaca agent pada awal setiap tugas akan menggunakan anggaran konteks pada setiap tugas, dan bagian instalasi yang diduplikasi hanya menjadi beban terhadap jendela konteks yang ukurannya tetap. Pengelolaan jendela tersebut merupakan keterampilan tersendiri, yang dibahas dalam mengelola jendela konteks di Claude Code. Ringkasnya: semua yang dimuat secara otomatis harus menjadi teks dengan nilai tertinggi di repositori.

Kerugian kedua lebih serius. Dua salinan pernyataan yang sama dapat berbeda seiring waktu. README menyatakan bahwa service mendengarkan pada 8080, sedangkan DESIGN.md masih menyatakan 3000. Agent tidak memiliki cara untuk menentukan mana yang lebih diutamakan, sehingga agent memilih salah satunya dan menulis kode berdasarkan pilihan tersebut. File yang kadang-kadang 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 tersebut dari DESIGN.md. Bagian yang tersisa harus berupa hal yang akan Anda sampaikan secara langsung dalam code review, yaitu bagian yang dimulai dengan "kami sudah pernah mencoba cara itu".

Bagaimana Anda mengetahui bahwa file tersebut berfungsi?

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

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

Pantau juga jumlah token, karena file ini dimuat pada setiap giliran. Jika penggunaan konteks meningkat setelah Anda menambahkan DESIGN.md, tetapi jawabannya tidak membaik, file tersebut memuat uraian yang sudah diketahui agent. Membaca penghitung token di Claude Code menunjukkan penggunaan anggaran tersebut.

Hal ini paling penting ketika agent berjalan di server, bukan di laptop Anda. Agent yang bekerja dalam session yang berjalan lama, seperti konfigurasi pada workspace Claude Code di VPS dengan tmux, tidak memiliki memori 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 menyimpan penjelasan tersebut agar tetap tersedia.

Mulai dari keputusan yang sering diperdebatkan

Versi pertama dapat dibuat 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 merupakan invarian yang belum pernah didokumentasikan. Setiap komentar juga menunjukkan hal yang akan kembali disalahpahami oleh agen, dengan lebih cepat dan lebih sering daripada manusia. Tambahkan ke file tersebut saat file itu tidak membantu Anda, bukan berdasarkan jadwal. Jika Anda masih menentukan posisi agen dalam alur kerja pengembangan normal, panduan mempelajari agen AI tahun 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 resmi di agents.md, digunakan oleh lebih dari 60,000 proyek open source, dan dikelola oleh Agentic AI Foundation yang merupakan bagian dari Linux Foundation. Hingga August 2026, DESIGN.md tidak memiliki badan pengelola maupun spesifikasi yang diterbitkan. Yang dimilikinya adalah adopsi pihak pertama: tujuh perusahaan, termasuk Vercel, Nuxt, Atlassian, dan Resend, menerbitkan file tersebut di URL publik, dan sebuah koleksi komunitas memuat 73 file lain yang direkayasa balik dari situs publik. Anggap DESIGN.md 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 ketika salah satunya diabaikan. Pisahkan keduanya ketika AGENTS.md tidak lagi mudah dipindai, atau ketika Anda melihat bahwa kedua bagian tersebut berubah dengan laju yang berbeda. AGENTS.md berubah ketika build berubah. DESIGN.md berubah ketika suatu keputusan berubah, yang lebih jarang terjadi dan dampaknya lebih besar. Setelah memisahkannya, tambahkan satu baris ke AGENTS.md yang meminta agent membaca DESIGN.md sebelum mengedit kode, karena tidak setiap tool memuat setiap file markdown di root.

Apa perbedaan DESIGN.md dengan architecture decision record?

ADR (architecture decision record) adalah catatan bertanggal tentang satu keputusan, dan proyek yang dikelola dengan baik mengumpulkan puluhan ADR dalam sebuah direktori. Itu merupakan riwayat, dan riwayat mahal untuk dimuat karena agent harus membaca semuanya untuk mengetahui mana yang masih berlaku. DESIGN.md berisi kondisi saat ini dan ditulis agar dibaca secara menyeluruh pada setiap tugas. Pertahankan keduanya jika Anda sudah menulis ADR. ADR menjelaskan apa yang diputuskan dan kapan keputusan itu dibuat. DESIGN.md menjelaskan apa yang berlaku saat ini, dan itulah file yang Anda tunjukkan kepada agent.

Seberapa panjang DESIGN.md seharusnya?

Cukup singkat untuk dimuat pada setiap giliran tanpa menimbulkan penyesalan. Contoh yang diterbitkan panjang karena menetapkan keseluruhan bahasa visual: file Nuxt berisi sekitar 2,100 kata dan file Vercel sekitar 6,500 kata hingga August 2026. Layanan backend biasanya membutuhkan jauh lebih sedikit. Mulailah dengan satu halaman dan tambahkan isinya hanya ketika agent melakukan kesalahan yang sebenarnya dapat dicegah oleh satu kalimat. Panjang bukanlah ukurannya. Setiap baris harus memuat hal yang mungkin akan dilakukan agent secara keliru jika tidak ada baris tersebut.