README rapi membuat agent lebih patuh
Vibecoding dengan AI agent terasa menyenangkan saat demo kecil. Kita menulis satu instruksi, agent membuat file, memperbaiki bug, lalu aplikasi terlihat hidup. Masalahnya mulai muncul ketika proyek membesar. Agent lupa keputusan sebelumnya, membuat fitur yang tidak diminta, mengubah struktur folder sembarangan, atau menulis ulang bagian yang sebenarnya sudah stabil. Di titik itu, prompt saja tidak cukup. Kita butuh README.md yang berfungsi sebagai peta kerja agent.
Saya menganggap README untuk AI agent berbeda dari README publik biasa. README publik menjelaskan proyek kepada manusia yang ingin memakai atau memasang aplikasi. README untuk vibecoding harus lebih operasional: apa tujuan produk, bagaimana alur pengguna, aturan teknis apa yang tidak boleh dilanggar, perubahan terakhir apa, dan catatan implementasi mana yang wajib dibaca sebelum mengedit. Kalau dokumen ini rapi, agent punya konteks yang lebih stabil.
Hanya untuk edukasi dan workflow aman
Tutorial ini tidak menjanjikan agent selalu benar. AI agent tetap bisa salah membaca instruksi, salah menebak dependensi, atau membuat perubahan terlalu luas. README.md hanya mengurangi risiko, bukan menghapusnya. Tetap gunakan git, review diff, dan jangan memberi agent akses ke secret produksi.
Kenapa README Penting untuk Full AI Agent
Full AI agent biasanya bekerja dalam beberapa langkah: membaca file, membuat rencana, mengedit kode, menjalankan perintah, lalu memperbaiki error. Tanpa dokumen pusat, agent akan membangun asumsi dari potongan file yang kebetulan ia baca. Ini berbahaya karena repo besar jarang konsisten sempurna. Ada kode lama, pola baru, folder eksperimen, dan keputusan produk yang tidak terlihat dari satu file.
README.md menjadi sumber kebenaran ringan. Ia tidak perlu sepanjang dokumen korporat, tetapi harus menjawab pertanyaan penting: produk ini untuk siapa, fitur utama apa, alur pengguna bagaimana, batasan teknis apa, dan perubahan apa yang baru saja terjadi. Dengan begitu, saat Anda meminta agent membuat fitur, agent tidak mulai dari ruang kosong.
Isi README yang Saya Sarankan
Ada empat blok yang menurut saya wajib: flowchart, PRD atau Product Requirement Document, changelog, dan implementation notes. Flowchart membantu agent memahami alur. PRD menjelaskan tujuan dan batasan produk. Changelog memberi riwayat keputusan. Implementation notes memberi aturan teknis yang sering tidak tertangkap dari kode.
Langkah 1: Tulis Tujuan Produk
Langkah 2: Tambahkan Flowchart
Langkah 3: Susun PRD Ringkas
Langkah 4: Catat Changelog
Langkah 5: Tambahkan Implementation Notes
Template README untuk AI Agent
Template di bawah ini bisa Anda pakai sebagai titik awal. Saya sengaja membuatnya praktis, bukan terlalu formal. Anda boleh memangkas bagian yang tidak relevan, tetapi jangan menghapus konteks produk dan aturan implementasi.
# Nama Produk
## Ringkasan Produk
Produk ini membantu [target pengguna] menyelesaikan [masalah utama]
dengan cara [mekanisme utama]. Fokus proyek saat ini adalah [prioritas].
## Target Pengguna
- Pengguna utama: [siapa]
- Masalah yang dialami: [masalah]
- Kondisi sukses: [hasil yang diharapkan]
## Flowchart Utama
```mermaid
flowchart TD
A[User membuka aplikasi] --> B{Sudah login}
B -->|Ya| C[Masuk dashboard]
B -->|Tidak| D[Halaman login]
C --> E[User membuat item baru]
E --> F[Validasi input]
F -->|Valid| G[Simpan data]
F -->|Tidak valid| H[Tampilkan error]
```
## PRD Ringkas
### Tujuan
- [Tujuan bisnis atau produk]
### Fitur Utama
- [Fitur 1]
- [Fitur 2]
- [Fitur 3]
### Non Fitur
- Jangan membuat [fitur yang belum direncanakan]
- Jangan mengubah [area stabil]
### Acceptance Criteria
- [Kriteria yang bisa diuji]
- [Kriteria yang bisa diuji]
## Changelog
### 2026-05-21
- Menambahkan [perubahan]
- Memutuskan [keputusan teknis]
## Implementation Notes
- Gunakan struktur folder: [aturan]
- Gunakan naming: [aturan]
- Jangan menyimpan secret di repo.
- Semua perubahan harus kecil dan mudah direview.
- Jika ragu, buat rencana sebelum edit.Jika komponen markdown di proyek Anda tidak mendukung nested fence dengan rapi, pisahkan blok Mermaid ke file dokumentasi lain atau tulis flowchart dalam bentuk bullet. Yang penting bukan gaya visualnya, tetapi relasi alurnya terbaca. Agent perlu tahu apa yang terjadi setelah user klik, kapan validasi muncul, dan apa hasil akhir tiap jalur.
Cara Menulis Flowchart yang Berguna
Flowchart untuk agent tidak harus cantik. Saya lebih memilih flowchart kasar tetapi lengkap daripada diagram indah yang cuma menjelaskan halaman awal. Minimal, tulis jalur utama, jalur gagal, dan keputusan penting. Misalnya pada aplikasi checkout, jangan hanya menulis “user bayar”. Pecah menjadi pilih produk, isi data, validasi stok, pilih metode bayar, buat invoice, cek status pembayaran, lalu tampilkan hasil.
Flowchart yang baik mengurangi kebiasaan agent menciptakan alur sendiri. Saat agent diminta membuat halaman baru, ia bisa mencocokkan fitur dengan alur yang sudah ada. Ini sangat membantu jika Anda memakai agent untuk beberapa sesi berbeda.
PRD Jangan Terlalu Tebal
PRD untuk vibecoding tidak perlu menjadi dokumen 40 halaman. Justru agent bisa kehilangan fokus jika konteks terlalu panjang. Buat ringkas tetapi tajam. Tulis tujuan, target pengguna, fitur utama, non fitur, dan acceptance criteria. Bagian non fitur sangat penting karena agent sering terlalu proaktif. Jika Anda tidak ingin sistem pembayaran, tulis jelas “jangan membuat payment gateway”. Jika belum ingin multi bahasa, tulis juga.
Acceptance criteria adalah bagian yang membuat output bisa dinilai. Daripada menulis “fitur login harus bagus”, tulis “user melihat error jika email kosong”, “password minimal 8 karakter”, dan “setelah login berhasil user diarahkan ke dashboard”. Kriteria seperti ini membantu agent menulis kode yang lebih terarah.
Changelog sebagai Memori Proyek
Changelog bukan cuma daftar versi. Untuk AI agent, changelog adalah memori keputusan. Misalnya, Anda pernah memutuskan pindah dari local storage ke database, mengganti nama model data, atau menghapus fitur tertentu. Jika keputusan itu tidak dicatat, agent bisa menghidupkan kembali pola lama saat membaca file usang.
Saya menyarankan changelog ditulis singkat per tanggal. Fokus pada keputusan yang memengaruhi implementasi. Tidak perlu mencatat setiap typo. Catat hal yang membuat agent harus berhati-hati.
Implementation Notes untuk Mencegah Edit Liar
Bagian ini berisi aturan teknis yang harus dipatuhi. Contohnya: jangan membuat helper baru jika fungsi hanya dipakai sekali, jangan mengubah schema tanpa migrasi, gunakan komponen desain yang sudah ada, atau jangan menjalankan perintah build tertentu. Semakin spesifik catatan ini, semakin kecil kemungkinan agent membuat solusi yang terlihat pintar tetapi menyulitkan maintenance.
README yang baik bukan dokumen pajangan, tetapi pagar kerja untuk agent.Cara Memakai README Saat Prompting Agent
Setelah README siap, jangan berharap agent otomatis selalu membacanya. Di prompt awal, minta agent membaca README.md terlebih dahulu, menyebutkan pemahamannya, lalu membuat rencana singkat sebelum edit. Untuk perubahan kecil, rencana bisa 3 poin saja. Untuk perubahan besar, minta agent menyebutkan file yang akan disentuh.
Saya juga suka menambahkan kalimat: “Jika permintaan saya bertentangan dengan README, jelaskan konflik sebelum mengedit.” Ini membantu karena kadang kita sendiri lupa keputusan lama. Agent yang baik bukan hanya mengeksekusi, tetapi juga menahan perubahan yang berisiko.
Apakah README ini menggantikan dokumentasi teknis?
Tidak. README untuk agent adalah ringkasan operasional. Dokumentasi detail tetap bisa dipisah jika proyek besar.
Apakah wajib memakai Mermaid untuk flowchart?
Tidak wajib. Bullet alur juga cukup selama keputusan dan jalur gagal tertulis jelas.
Seberapa sering changelog diperbarui?
Perbarui setiap ada keputusan yang memengaruhi cara agent mengedit atau memahami proyek.
Lanjut Belajar AI Agent
Baca tutorial Sitemas lainnya untuk membangun workflow coding AI yang tetap aman dan mudah direview.
Membangun ekosistem digital yang edukatif melalui Sitemas. Berfokus pada inovasi teknologi, AI, dan pengembangan konten kreatif yang berdampak.
Komentar