Pentingnya MD File dalam AI Coding: CLAUDE.md, AGENTS.md, dan README yang Ramah AI

File Markdown (.md) seperti CLAUDE.md, AGENTS.md, README.md, dan CONTRIBUTING.md bukan sekadar dokumentasi untuk manusia. Di era AI coding 2026, file-file ini menjadi memori permanen yang membentuk cara AI agent bekerja di dalam codebase Anda. Memahami pentingnya MD file adalah kunci agar AI benar-benar membantu — bukan malah membuat kekacauan.

Mengapa AI Agent Butuh MD File?

AI coding agent seperti Claude Code, GitHub Copilot Workspace, dan Cursor Agent tidak punya memori permanen secara default. Setiap sesi dimulai dari nol. Tanpa panduan tertulis, agent harus menebak: konvensi naming yang dipakai, framework apa yang jadi standar, aturan mana yang tidak boleh dilanggar, dan konteks bisnis di balik setiap keputusan teknis.

MD file menjembatani gap ini. Saat agent membaca CLAUDE.md atau AGENTS.md di root repository, ia langsung mendapat konteks yang dibutuhkan tanpa harus menganalisis seluruh codebase dari awal. Hasilnya: saran lebih akurat, perubahan lebih konsisten, dan lebih sedikit revisi bolak-balik.

Hierarki MD File untuk AI Coding

• README.md — gambaran umum project: tujuan, cara setup, cara menjalankan. Dibaca AI saat pertama kali masuk ke repository.
• CLAUDE.md — instruksi spesifik untuk Claude Code: perintah build/test, arsitektur high-level, konvensi yang harus diikuti, hal yang tidak boleh dilakukan.
• AGENTS.md — panduan untuk semua AI agent (bukan hanya Claude): standar kode, workflow approval, batasan akses tool.
• CONTRIBUTING.md — aturan kontribusi yang juga dibaca AI: format commit, branching strategy, review process.
• ARCHITECTURE.md — penjelasan arsitektur sistem untuk membantu AI memahami keputusan desain yang sudah ada.

Anatomi CLAUDE.md yang Efektif

File CLAUDE.md adalah instruksi langsung ke Claude Code. Kontennya dibaca otomatis setiap kali Claude bekerja di dalam repository tersebut. Struktur yang efektif mencakup:

• Perintah umum: cara build, run test, lint, dan deploy. Contoh: npm run test:unit untuk unit test, npm run build:prod untuk production build.
• Arsitektur high-level: komponen utama dan hubungannya. Cukup beberapa paragraf — tidak perlu mendetail setiap file.
• Konvensi kode: naming convention, pola yang disukai, library yang jadi standar (misalnya “gunakan Zod untuk validasi, bukan Yup”).
• Hal yang dilarang: misalnya “jangan ubah file migrasi database yang sudah ada”, “jangan commit langsung ke main”, “jangan hapus console.log tanpa konfirmasi”.
• Konteks bisnis: alasan di balik keputusan teknis yang tidak obvious dari kode.

Contoh CLAUDE.md untuk Project Python

Berikut contoh CLAUDE.md sederhana untuk project Python FastAPI:

# CLAUDE.md

## Setup & Commands
- Install: pip install -r requirements.txt
- Run dev: uvicorn main:app --reload
- Test: pytest tests/ -v
- Lint: ruff check . && mypy .

## Architecture
- main.py — entry point FastAPI
- routers/ — endpoint per domain (users, orders, products)
- services/ — business logic, tidak boleh akses DB langsung
- repositories/ — semua query database via SQLAlchemy
- schemas/ — Pydantic models untuk request/response

## Conventions
- Gunakan async/await untuk semua endpoint
- Validasi input via Pydantic, bukan manual
- Error handling dengan HTTPException, bukan raise langsung
- Semua fungsi baru harus ada type hint

## Do NOT
- Jangan ubah alembic migration yang sudah ada
- Jangan commit secret atau API key
- Jangan bypass authentication middleware

MD File di Sub-Direktori: Konteks Berlapis

AI agent modern seperti Claude Code mendukung MD file berlapis. Selain CLAUDE.md di root, Anda bisa menempatkan CLAUDE.md di sub-direktori untuk konteks yang lebih spesifik. Contoh:

• /CLAUDE.md — aturan umum seluruh project.
• /frontend/CLAUDE.md — konvensi React, state management, komponen library yang dipakai.
• /backend/CLAUDE.md — konvensi API, aturan database, cara menjalankan migration.
• /scripts/CLAUDE.md — penjelasan setiap script automation dan kapan boleh dijalankan.

Agent akan membaca file dari root ke direktori tempat ia bekerja, menggabungkan semua instruksi. Konteks yang lebih spesifik (sub-direktori) mengalahkan konteks yang lebih umum (root) jika ada konflik.

README.md yang Ramah AI

README biasa ditulis untuk manusia. README yang ramah AI menambahkan informasi yang membantu agent langsung bekerja tanpa bertanya:

• Dependency yang tidak obvious: misalnya “butuh Redis running di port 6379” atau “butuh file .env dari tim ops”.
• Urutan setup yang kritis: jika langkah harus berurutan, tulis eksplisit — AI cenderung mencoba paralel jika tidak dijelaskan.
• Peringatan: “menjalankan script reset-db.sh akan menghapus semua data local” — informasi seperti ini mencegah agent melakukan tindakan destruktif tanpa sadar.
• Glossary istilah domain: kata-kata spesifik bisnis yang maknanya berbeda dari makna umum.

Memory MD File vs Context Window

Setiap kali Anda berbicara dengan AI coding assistant, ada batas jumlah teks yang bisa diproses sekaligus (context window). Semakin besar codebase, semakin banyak konteks yang “terbuang” untuk memahami struktur dasar, menyisakan sedikit ruang untuk tugas yang sebenarnya.

MD file yang baik memampatkan informasi penting ke dalam teks ringkas. Alih-alih agent harus membaca 50 file untuk memahami arsitektur, sebuah ARCHITECTURE.md yang baik bisa menyampaikan inti dalam 500 kata. Ini menghemat context window untuk hal yang lebih penting: memahami bug yang dilaporkan atau menulis fitur baru.

Kesalahan Umum dalam Menulis MD File untuk AI

• Terlalu panjang dan tidak terstruktur: AI kesulitan mengekstrak instruksi dari teks naratif panjang. Gunakan heading, bullet point, dan contoh kode pendek.
• Informasi yang sudah ada di kode: jangan copy-paste kode ke MD file. Cukup jelaskan mengapa keputusan itu dibuat — what dan how sudah ada di kode itu sendiri.
• Tidak diupdate: MD file yang outdated lebih berbahaya dari tidak ada MD file. AI akan mengikuti instruksi lama yang sudah tidak relevan. Jadikan update MD file bagian dari checklist PR.
• Tidak menyebut hal yang dilarang: manusia bisa menebak bahwa “jangan hapus production database” adalah hal yang obvious. AI tidak punya intuisi tersebut — tulis eksplisit.
• Bahasa ambigu: hindari kata seperti “biasanya”, “sebaiknya”, “kalau bisa”. Gunakan “selalu”, “jangan pernah”, atau “wajib” untuk aturan yang tidak boleh dilanggar.

MD File sebagai Dokumentasi Keputusan (ADR)

Architecture Decision Record (ADR) adalah praktik menulis keputusan arsitektur dalam file Markdown terpisah, biasanya di folder docs/decisions/. Contoh: 0001-pilih-postgresql-bukan-mongodb.md berisi konteks, keputusan, konsekuensi, dan alasan di balik pilihan tersebut.

Bagi AI agent, ADR sangat berharga. Saat agent melihat kode yang memakai PostgreSQL dan bertanya-tanya kenapa tidak pakai MongoDB, ia bisa membaca ADR dan langsung memahami konteks historisnya — tanpa perlu tanya developer atau menebak-nebak. Ini mencegah agent “memperbaiki” sesuatu yang sebenarnya sudah disengaja.

Template AGENTS.md untuk Tim

AGENTS.md adalah standar yang muncul untuk memberikan instruksi ke semua AI agent — bukan hanya Claude. Struktur yang disarankan:

# AGENTS.md

## Scope
AI agent boleh membaca dan memodifikasi kode di direktori ini.
AI agent TIDAK BOLEH mengakses direktori /infra dan /secrets.

## Workflow
1. Buat branch baru sebelum melakukan perubahan
2. Jalankan test suite sebelum commit
3. Minta review manusia sebelum merge ke main

## Tools yang Diizinkan
- Read/write file di src/, tests/, docs/
- Jalankan: npm test, npm run lint
- DILARANG: git push, deployment script, akses ke env production

## Standar Kode
- TypeScript strict mode wajib
- Tidak ada any type
- Test coverage minimum 80% untuk kode baru

Latihan Praktis

Ambil salah satu project yang sedang Anda kerjakan dan buat CLAUDE.md atau AGENTS.md dari awal. Mulai dengan tiga bagian saja: (1) perintah untuk menjalankan dan test project, (2) dua atau tiga aturan konvensi yang paling sering dilanggar AI, (3) satu hal yang TIDAK BOLEH dilakukan agent. Setelah dibuat, minta AI coding assistant untuk menjalankan task sederhana dan bandingkan hasilnya dengan sebelum ada MD file. Perbedaan kualitas dan konsistensinya akan langsung terasa.

Ringkasan

MD file adalah investasi kecil dengan dampak besar pada kualitas AI coding. File seperti CLAUDE.md, AGENTS.md, dan ADR mengubah AI dari asisten generik menjadi mitra yang benar-benar memahami konteks project Anda. Kuncinya: tulis ringkas, gunakan struktur yang jelas, sertakan hal yang dilarang secara eksplisit, dan jadikan update MD file sebagai kebiasaan rutin tim. Semakin baik MD file Anda, semakin sedikit waktu yang habis untuk mengoreksi AI — dan semakin banyak waktu untuk membangun hal yang benar-benar penting.

Lanjut Belajar AI

Jika artikel ini membantu, lanjutkan ke materi terstruktur agar pemahaman AI lebih rapi dan praktis.

Buka Materi Belajar AILihat AI Tools