Ada satu jebakan yang mulai sering kejadian: developer merasa sudah “pakai AI”, tapi repo yang dikerjain tetap bikin pusing begitu dibuka minggu depan.
Artikel ini bahas kenapa AI coding tools seperti GitHub Copilot, Claude Code, atau Hermes Agent tetap butuh konteks repo yang jelas. Jawaban singkatnya: AI bisa mempercepat eksekusi, tapi ia nggak otomatis ngerti sejarah keputusan, batasan teknis, dan standar kerja tim kalau semua itu cuma hidup di kepala orang. Buat developer solo maupun tim kecil, dokumentasi ringan seperti README, instruksi AI, dan Architecture Decision Record bisa jadi multiplier yang lebih realistis daripada sekadar ganti tool baru.
Masalah utamanya bukan AI kurang pintar, tapi konteks repo terlalu tipis
Kalau lu buka project lama dan langsung mikir, “ini dulu kenapa dibuat begini ya?”, berarti masalahnya bukan cuma memori lu. Masalahnya adalah konteks kerja nggak pernah ditaruh di tempat yang bisa dibaca ulang.
AI coding assistant juga kena masalah yang sama. GitHub punya fitur repository custom instructions supaya Copilot bisa memahami aturan, preferensi, dan konteks project. Anthropic juga punya konsep CLAUDE.md untuk menyimpan memori project Claude Code. Dua contoh ini nunjukin pola yang sama: tool AI modern makin kuat, tapi vendor besar pun tetap butuh file instruksi eksplisit agar AI nggak nebak-nebak.
Menurut gua, ini sinyal penting buat developer: konteks bukan bonus. Konteks adalah bagian dari sistem kerja.
Apa itu “konteks repo” dalam praktik?
Konteks repo adalah semua informasi yang membantu orang atau AI memahami cara kerja project tanpa harus membongkar semua file satu per satu. Bentuknya bisa sederhana:
- README yang menjelaskan tujuan project, cara setup, dan command penting.
- Instruksi AI seperti
AGENTS.md,CLAUDE.md, atau custom instructions untuk aturan coding dan workflow. - Architecture Decision Record (ADR) untuk mencatat keputusan teknis penting dan alasan di baliknya.
- Changelog kecil untuk mencatat perubahan yang punya dampak ke user atau tim.
- Folder docs berisi API contract, edge case, atau cara deploy.
Ini bukan dokumentasi gaya korporat yang panjang dan kaku. Justru yang berguna biasanya pendek, spesifik, dan sering dibaca ulang.
Kenapa AI tanpa konteks gampang bikin utang maintenance?
AI bisa menghasilkan kode yang terlihat benar. Tapi “terlihat benar” beda dengan “cocok buat repo ini”.
Misalnya lu minta AI bikin service API baru. Kalau repo lu punya standar naming, wrapper request khusus, validasi tertentu, atau pola error handling yang sudah dipakai di fitur lain, AI harus tahu itu. Kalau nggak, hasilnya bisa jalan secara lokal tapi pelan-pelan bikin codebase punya banyak gaya berbeda.
Di sinilah maintenance cost mulai naik. Bukan karena AI jahat, tapi karena input yang kita kasih terlalu miskin konteks.
Martin Fowler pernah memuat contoh interaksi LLM untuk programming yang menarik: prompt yang bagus bukan cuma “buat fitur X”, tapi juga menjelaskan stack, struktur kode, testing, dan constraint. Buat gua, pelajaran praktisnya jelas: kalau prompt panjang yang sama sering lu ulang, berarti sebagian prompt itu harus naik kelas jadi dokumentasi repo.
Framework simpel: 3 file yang bikin AI lebih berguna
Kalau lu mau mulai tanpa ribet, gua akan mulai dari tiga file ini.
1. README yang menjawab “project ini apa dan jalaninnya gimana?”
README nggak perlu jadi novel. Minimal harus menjawab:
- Project ini buat apa?
- Stack utama apa?
- Cara install dan run lokal gimana?
- Command test, build, dan lint apa?
- Environment variable penting apa saja?
Kalau orang baru butuh nanya hal yang sama berulang kali, tulis di README. Kalau AI sering salah command, tulis di README juga.
2. AGENTS.md atau CLAUDE.md untuk aturan kerja AI
File ini isinya instruksi operasional buat AI agent. Contohnya:
- Jangan tulis production code sebelum test.
- Gunakan TypeScript strict.
- Komponen Vue pakai PascalCase.
- Service API harus lewat wrapper tertentu.
- Sebelum commit, jalankan command verifikasi tertentu.
GitHub Copilot dan Claude Code sama-sama punya mekanisme untuk membaca instruksi project. Jadi daripada setiap sesi lu ulang instruksi panjang, lebih masuk akal taruh standar itu di repo.
3. ADR untuk keputusan yang gampang dilupakan
Architecture Decision Record adalah catatan pendek tentang keputusan teknis. Biasanya mencakup konteks, pilihan yang dipertimbangkan, keputusan akhir, dan konsekuensinya.
Contoh sederhana:
- Konteks: Upload gambar mulai lambat dan storage database makin berat.
- Keputusan: Pindahkan media ke object storage.
- Alasan: Lebih cocok untuk file besar, biaya lebih terkontrol, dan lebih mudah di-cache.
- Konsekuensi: Perlu migrasi URL lama dan policy akses yang jelas.
ADR berguna banget karena banyak bug masa depan lahir dari keputusan lama yang alasan aslinya sudah hilang.
Checklist praktis buat repo yang ramah AI dan manusia
Lu bisa pakai checklist ini hari ini juga:
- Apakah README bisa dipakai orang baru buat run project tanpa nanya?
- Apakah command test, build, lint, dan deploy tertulis jelas?
- Apakah standar coding yang sering lu ulang ke AI sudah ditaruh di file instruksi?
- Apakah keputusan teknis besar punya catatan alasan?
- Apakah ada contoh pola kode yang benar untuk fitur umum?
- Apakah hal yang “jangan dilakukan” juga ditulis eksplisit?
Bagian terakhir sering diremehkan. AI perlu tahu bukan cuma pola yang benar, tapi juga jebakan yang harus dihindari.
Pengalaman gua: dokumen kecil sering lebih terasa efeknya daripada prompt panjang
Di workflow gua, AI agent paling terasa berguna saat konteksnya sudah disiapin. Misalnya project punya aturan service, struktur folder, command verifikasi, dan catatan migrasi. Begitu itu jelas, AI lebih jarang ngarang pola sendiri.
Sebaliknya, kalau repo kosong konteks, kerja bareng AI berubah jadi sesi koreksi tanpa henti. Lu minta satu fitur, AI bikin gaya baru. Lu revisi. Ia benerin satu bagian, tapi melanggar bagian lain. Akhirnya waktu yang harusnya dipakai buat berpikir malah habis buat jadi satpam output.
Opini gua: skill penting developer era AI bukan cuma “bisa prompt”. Skill yang lebih tahan lama adalah bisa mendesain konteks kerja supaya manusia dan AI sama-sama ngerti arah.
Takeaway: dokumentasi bukan kerja tambahan, tapi leverage
Kalau dokumentasi dibuat terlalu besar, memang jadi beban. Tapi kalau dibuat kecil, rutin, dan dekat dengan pekerjaan harian, ia jadi leverage.
- README membantu onboarding.
- Instruksi AI membantu output lebih konsisten.
- ADR membantu keputusan lama tetap bisa dipahami.
- Checklist membantu review lebih cepat.
AI makin pintar, tapi repo yang miskin konteks tetap mahal buat dirawat. Jadi sebelum ganti tool lagi, coba rapihin dulu konteks yang sudah ada.
FAQ singkat
Apakah semua project perlu ADR?
Nggak semua keputusan perlu ADR. Tapi keputusan yang mahal diubah, memengaruhi arsitektur, atau sering diperdebatkan sebaiknya dicatat.
Apakah dokumentasi harus lengkap dari awal?
Nggak. Mulai dari hal yang paling sering bikin orang atau AI salah. Dokumentasi yang berguna biasanya tumbuh dari masalah nyata.
Apakah AGENTS.md dan CLAUDE.md wajib dua-duanya?
Nggak wajib. Pilih yang sesuai tool yang lu pakai. Yang penting, aturan kerja project punya rumah yang jelas dan bisa dibaca ulang.
Apakah ini cuma relevan buat tim besar?
Nggak. Developer solo justru sering paling butuh ini, karena “timnya” adalah lu hari ini, lu tiga bulan lagi, dan AI agent yang lu pakai buat bantu kerja.
