DESIGN.md: File Setelah AGENTS.md untuk Coding Agent

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

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

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

Jika Anda belum menulis file pertama tersebut, mulai dari sana. AGENTS.md dan HUMAN.md yang berada di sebelahnya menjelaskan format dan lokasi yang dicari oleh setiap tool. Bagian berikut 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. Repository official-design-md hanya melacak file-file tersebut. Aturan penyertaannya hanya satu baris, dan baris itu adalah inti dari 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 Oktober 2026, repository tersebut mencantumkan sebelas file: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel, dan VoltAgent. Setiap file berada di URL publik, sebagian besar pada domain milik penerbitnya sendiri dan sisanya dalam repository GitHub publik, sehingga Anda dapat membacanya melalui terminal sekarang juga.

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 sebuah produk: warna, tipografi, spasi, dan animasi. Perhatikan struktur penulisannya, bukan hanya topiknya, karena bagian yang berguna adalah bentuk penulisannya.

File Nuxt berisi sekitar 2.000 kata per 27 Oktober 2026, dan sebagian besar isinya berupa aturan yang disertai alasannya. File tersebut dibuka dengan pernyataan bahwa mode gelap adalah tema default. File tersebut mencantumkan warna hijau merek #00DC82 dengan catatan bahwa warna merek tersebut adalah "Untuk logo, gambar media sosial, dan cetak. Jangan gunakan nilai mentahnya dalam kode UI." Di dekat bagian akhir, terdapat bagian dengan judul Reject these yang berisi:

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

File Vercel lebih panjang, sekitar 6.000 kata per Oktober 2026, dan melangkah lebih jauh. Salah satu judulnya adalah Reject generated-design reflexes. Di bawahnya terdapat daftar hal-hal yang akan dipilih generator yang andal 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 yang percaya diri, 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 memuat 84 file yang diambil dari situs web publik, berdasarkan jumlah dalam README per 27 Oktober 2026. Setiap file ditulis dalam format sembilan bagian yang sama, sehingga agen dapat diarahkan ke salah satunya dan menghasilkan sesuatu yang mendekati tampilan tersebut. File-file itu berguna, tetapi tetap berupa perkiraan. Tidak ada pihak dari perusahaan terkait yang meninjau file-file tersebut.

File pihak pertama berbeda karena merupakan sumbernya, bukan pembacaan atas hasil akhirnya. Saat Vercel mengubah skala tipografinya, vercel.com/design.md ikut berubah. Salinan yang di-scrape pada Maret tetap mengajarkan skala lama kepada agen Anda, dan tidak ada sesuatu pun dalam repository yang memberi tahu bahwa salinan tersebut sudah kedaluwarsa.

Sebelas penerbit masih merupakan jumlah yang kecil, dan repository tersebut menyatakan hal yang sama: standarnya masih baru dan adopsi resmi terus meningkat. 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 pihak-pihak yang tercantum di dalamnya. Beberapa di antaranya adalah perusahaan yang kode frontend-nya paling sering disalin oleh developer lain. Entri yang lebih baru, yaitu Ant Design, Microsoft FAST, Juspay, dan Oxide Computer, merupakan sistem desain yang menjadi dasar pengembangan tim lain. File mereka mulai menjadi contoh penerapan DESIGN.md. Bandingkan dengan perkembangan AGENTS.md: agents.md kini mencatat lebih dari 60,000 project open source yang menggunakan format tersebut, dan pengelolaannya berada di bawah Agentic AI Foundation dalam Linux Foundation. DESIGN.md mulai menempuh jalur yang sama. Pada 21 April 2026, Google merilis draft spesifikasi format tersebut sebagai open source. Spesifikasi itu diterbitkan sebagai google-labs-code/design.md, lengkap dengan skema token dan CLI di bawah lisensi Apache-2.0. Per Oktober 2026, format tersebut berada pada versi alpha dan masih aktif dikembangkan. Format ini dikelola oleh Google Labs, bukan foundation netral, dan menjelaskan identitas visual. Karena itu, format tersebut tidak menjelaskan invariant yang diperlukan file backend. Konvensi untuk file yang dapat dibaca agen sedang ditetapkan dengan cepat, dan penetapannya berasal dari pihak-pihak utama.

Apa yang harus ditulis 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 ditulis secara eksplisit, yang jika tidak ditulis dapat dilanggar 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 harus melalui queue.enqueue(). Penulisan langsung ke database melewati audit log, sedangkan audit log digunakan oleh ekspor kepatuhan." Invarian yang disertai alasannya tetap berguna ketika menghadapi tugas yang tidak pernah Anda antisipasi. Invarian tanpa alasan hanya terlihat seperti preferensi, dan preferensi akan dihapus saat 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 sudah ada application server kedua." Tanpa paragraf tersebut, agent yang diminta mempercepat cache akan menambahkan Redis, dan tindakan itu benar: Anda tidak pernah menyampaikan batasannya. Inilah bagian yang membuat seluruh file ini bernilai.

Batasan. Cantumkan bagian yang dapat menimbulkan dampak besar akibat pengeditan kecil. Misalnya, skema database. Prefix route publik yang sudah digunakan dalam script pelanggan. File konfigurasi yang dibaca oleh proses deploy sebelum aplikasi dijalankan. Entri cron yang mengasumsikan hanya satu salinannya berjalan. Sebutkan semuanya dan jelaskan biaya setiap perubahan. Jika agent juga dapat mengakses web terbuka, misalnya melalui instance SearXNG yang di-host sendiri dan dikonfigurasi sebagai backend pencariannya, hal itu juga merupakan batasan yang perlu ditulis. File tersebut harus menyatakan 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, tuliskan pemetaannya. Agent yang salah menebak akan menghasilkan kode yang terlihat benar tetapi memodelkan hal yang keliru. Kesalahan seperti ini paling sulit ditemukan saat code 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 invarian dan alternatif yang ditolak, lalu biarkan bagian lainnya hanya sebagai heading. File dengan empat baris yang jujur lebih baik daripada file dengan empat puluh baris tebakan. Jika repositori berisi beberapa package, satu file di root tidak akan cocok untuk semuanya. Dalam hal ini, gunakan pemisahan per direktori yang sama seperti file AGENTS.md bertingkat dalam monorepo: file root yang singkat untuk keputusan yang berlaku bersama, dan file yang lebih kecil di samping setiap package yang memiliki keputusan sendiri.

Sebagian tool memuat setiap file markdown di root repositori, sedangkan sebagian lainnya hanya memuat file yang ditentukan secara eksplisit. Karena itu, 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.

Antipattern: DESIGN.md yang mengulang README

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

Hal ini menimbulkan dua biaya. Biaya pertama adalah konteks. File yang dibaca agent pada awal setiap task menggunakan anggaran pada setiap task, dan bagian instalasi yang diduplikasi hanya menjadi beban terhadap jendela waktu yang terbatas. Mengatur anggaran jendela tersebut merupakan keterampilan tersendiri, yang dibahas dalam mengelola jendela konteks di Claude Code. Ringkasnya: apa pun 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 8080, sedangkan DESIGN.md masih menyatakan 3000. Agent tidak memiliki cara untuk menentukan mana yang lebih diutamakan, sehingga agent memilih salah satunya lalu menulis code berdasarkan pilihan tersebut. File yang 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. Yang tersisa seharusnya adalah hal yang akan Anda sampaikan secara langsung dalam code review, yaitu bagian yang dimulai dengan "kita sudah mencoba cara itu".

Bagaimana mengetahui bahwa file tersebut berfungsi?

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

Berikan tugas kepada agent yang langsung menguji sebuah invariant. "Tambahkan background job yang menandai baris kedaluwarsa sebagai expired." File yang berfungsi akan terlihat dari jawabannya 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 ditulis terlalu longgar sehingga dapat diperdebatkan.

Pantau juga jumlah token, karena file ini dimuat pada setiap turn. Jika penggunaan konteks meningkat setelah Anda menambahkan DESIGN.md, tetapi jawabannya tidak membaik, 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 sesi yang berjalan lama, seperti setup 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 sesi berikutnya, dan DESIGN.md adalah tempat menyimpan penjelasan tersebut agar tetap tersedia.

Mulai dari keputusan yang paling sering diperdebatkan

Versi pertama selesai dalam dua puluh menit. Buka beberapa pull request terakhir yang memiliki komentar reviewer seperti "tidak, di sini kita melakukannya dengan cara berbeda". Setiap komentar tersebut merupakan invariant yang belum pernah didokumentasikan. Setiap komentar juga menunjukkan kondisi ketika 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 normal, panduan 2026 untuk mempelajari AI agent 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 sumber terbuka, dan berada di bawah pengelolaan Agentic AI Foundation, bagian dari Linux Foundation. DESIGN.md memiliki spesifikasi yang dipublikasikan, tetapi tidak memiliki pengelola netral. Google membuka kode sumber spesifikasi draf pada April 21, 2026, dan spesifikasi tersebut berada di repositori google-labs-code/design.md di bawah lisensi Apache-2.0. Per Oktober 2026, spesifikasi ini berada pada versi alpha dan masih dalam pengembangan aktif. Isinya menjelaskan identitas visual: warna, tipografi, tata letak, dan komponen. DESIGN.md juga telah diadopsi oleh pihak pertama: sebelas perusahaan dan proyek, termasuk Vercel, Nuxt, Atlassian, dan Resend, menerbitkan file tersebut. Selain itu, koleksi komunitas telah menghimpun 84 file lain yang diekstrak dari situs publik per October 27, 2026. Untuk file backend yang berisi invariant dan alternatif yang ditolak, perlakukan file ini sebagai konvensi yang dapat Anda adopsi sekarang dan kembangkan secara bebas, karena tidak ada spesifikasi yang mencakup nama-nama bagian tersebut.

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 bahwa kedua bagian tersebut berubah dengan laju yang berbeda. AGENTS.md berubah ketika proses build berubah. DESIGN.md berubah ketika suatu 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 dengan architecture decision record?

ADR (architecture decision record) adalah catatan bertanggal tentang satu keputusan, dan proyek yang dikelola dengan baik akan mengumpulkan puluhan ADR dalam satu direktori. Itu merupakan riwayat, dan riwayat membutuhkan biaya pemuatan yang besar, karena agent harus membaca semuanya untuk menentukan keputusan mana yang masih berlaku. DESIGN.md berisi keadaan saat ini dan ditulis agar dibaca sepenuhnya 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 file inilah yang Anda tunjukkan kepada agent.

Seberapa panjang DESIGN.md seharusnya?

Cukup pendek agar dapat dimuat pada setiap giliran tanpa menimbulkan penyesalan. Contoh yang dipublikasikan berukuran panjang karena menjelaskan seluruh bahasa visual: file Nuxt berisi sekitar 2,000 kata dan file Vercel sekitar 6,000 kata per October 2026. Service backend biasanya membutuhkan jauh lebih sedikit. Mulailah dari satu halaman dan tambah panjangnya hanya ketika agent melakukan kesalahan yang seharusnya dapat dicegah oleh satu kalimat. Panjang bukan ukurannya. Setiap baris harus berisi hal yang kemungkinan akan salah dilakukan agent.