File Rules untuk AI Coding: Bikin Cursor & Claude Nurut Konvensi (.cursorrules, CLAUDE.md, AGENTS.md)

Kamu minta Cursor bikin komponen. Dia pakai default export, styled-components, dan fetch di dalam useEffect. Sesi kemarin dia pakai named export, Tailwind, dan React Query. Kode-nya jalan, tapi tiap sesi seperti onboarding developer baru yang belum baca satu pun konvensi tim. Kamu abisin waktu bukan buat mikir logika, tapi buat betulin gaya.

Akar masalahnya sederhana: model ga punya memori soal proyekmu. Tiap prompt dia nebak konvensi dari pola paling umum di internet, bukan dari repo-mu. File rules ada buat nutup celah itu. Kamu tulis sekali aturan main proyek, agent baca tiap sesi, dan output-nya berhenti ngawur.

Apa itu file rules

File rules itu berkas teks di root repo yang dibaca AI coding sebelum dia mulai kerja. Isinya konteks proyek: stack, konvensi, larangan. Tiap tool punya nama file sendiri, tapi idenya sama.

• .cursorrules: format lama Cursor. Satu file di root, otomatis masuk konteks tiap kali kamu prompt. Statusnya sekarang legacy. Cursor sudah menandainya deprecated dan mengarahkan ke folder .cursor/rules/ berisi banyak file .mdc dengan scope per-path. File lama masih dibaca, tapi kalau mulai dari nol, pakai format folder yang direkomendasikan.
• CLAUDE.md: dibaca Claude Code. Ditaruh di root, dan bisa juga per-subfolder. Waktu agent menyentuh file di suatu subfolder, CLAUDE.md di situ ikut ke-load, jadi konteks lokal menempel di atas aturan root.
• AGENTS.md: standar lintas-agent yang mulai diadopsi banyak tool (Cursor, Zed, dan lainnya). Satu file dibaca berbagai agent, jadi kamu ga perlu nulis aturan sama di beberapa tempat.

Bedanya tipis dan makin ke sini makin konvergen. Yang penting bukan nama file-nya, tapi apa yang kamu tulis di dalamnya.

Anatomi file rules yang bagus

File rules jelek isinya basa-basi: "tulis kode yang bersih dan mudah dibaca". Itu ga ngasih info apa-apa ke model, dia udah nganggap dirinya nulis kode bersih. File rules bagus itu spesifik sampai bisa dieksekusi. Empat bagian yang wajib ada:

1. Stack dan versi. Bukan cuma "React", tapi "React 19, Next.js App Router, TypeScript strict, Tailwind v4". Versi penting karena API berubah antar mayor.
2. Konvensi folder. Di mana komponen, di mana util, di mana tipe. Model suka bikin folder baru random kalau ga dikasih tahu struktur yang ada.
3. Gaya kode. Named vs default export, cara handle error, library data-fetching yang dipakai, format nama file. Hal-hal yang di tim kalian udah jadi kesepakatan diam-diam.
4. Larangan eksplisit. Ini yang paling sering dilupa dan paling ampuh. "Jangan pakai any", "jangan install library baru tanpa nanya", "jangan pakai default export". Larangan mencegah model kabur ke pola favoritnya.

Contoh isi .cursorrules untuk proyek nyata

Ini contoh yang bukan boilerplate. Formatnya masih file .cursorrules tunggal biar gampang dibaca sekilas; kalau proyekmu baru, isi yang sama tinggal kamu pecah ke .cursor/rules/*.mdc. Perhatikan seberapa spesifik tiap baris, dan bagian larangannya yang bikin beda:

# Proyek: dashboard-internal

## Stack
- Next.js 15 (App Router), React 19, TypeScript strict mode
- Tailwind v4, komponen dari shadcn/ui (jangan bikin dari nol)
- Data: TanStack Query untuk client, server actions untuk mutasi
- DB: Drizzle ORM + Postgres

## Struktur folder
- src/app/        -> route + page
- src/components/ -> komponen reusable (named export, satu komponen per file)
- src/lib/        -> util & helper murni, tanpa efek samping
- src/db/         -> schema & query drizzle

## Konvensi
- Named export selalu, dilarang default export
- Nama file komponen kebab-case: user-card.tsx
- Error di server action: return { ok: false, error } bukan throw
- Fetch data di client lewat TanStack Query, bukan useEffect + fetch manual.
  Data yang bisa diambil di server, ambil di server component.
- Validasi input pakai zod di boundary (server action & API route)

## Larangan
- Jangan pakai tipe any. Kalau buntu, pakai unknown lalu narrow.
- Jangan install dependency baru tanpa konfirmasi dulu.
- Jangan sentuh file di src/db/migrations/ (auto-generated).
- Jangan pakai 'use client' kecuali komponen butuh state/efek.

File selevel ini langsung ngubah output Cursor. Dia berhenti nawarin default export, berhenti bikin folder acak, dan nanya dulu sebelum nambah library. Bandingin sama repo tanpa rules yang tiap PR gaya-nya beda.

Contoh CLAUDE.md dan cara agent membacanya

CLAUDE.md dipakai Claude Code. Struktur isinya mirip, tapi ada satu hal yang bikin beda: konteks berlapis. Kamu bisa taruh CLAUDE.md di root buat aturan umum, lalu CLAUDE.md lain di dalam packages/api/ yang khusus backend. Waktu agent menyentuh file di packages/api/, CLAUDE.md di situ ikut ke-load bareng yang root. Konteks backend jadi menempel di atas aturan umum. Ini bukan mekanisme override otomatis kalau dua aturan bentrok, tapi kamu bisa nulis aturan lokal yang lebih spesifik buat subtree itu, dan agent membacanya dengan konteks yang lebih dekat ke file yang lagi dia kerjain.

# CLAUDE.md (root)

Monorepo pnpm. Package: apps/web (Next.js), packages/api (Hono), packages/db.

## Aturan global
- TypeScript strict. Jangan matikan lint rule buat lolos, betulin sumbernya.
- Commit message: conventional commits (feat:, fix:, chore:).
- Sebelum bilang "selesai", jalankan `pnpm typecheck` dan `pnpm test`.

## Perintah penting
- pnpm dev      -> semua app
- pnpm test     -> vitest
- pnpm db:push  -> sync schema drizzle ke db lokal

## Larangan
- Jangan edit file .env atau .env.local.
- Jangan bikin package baru tanpa diskusi arsitektur dulu.

Bagian "jalankan typecheck dan test sebelum bilang selesai" itu emas. Tanpa itu, agent sering ngaku beres padahal build merah. Aturan verifikasi bikin dia nutup loop-nya sendiri.

Kalau kamu masih baru pakai Claude Code, alur setup file rules dan cara agent baca konteks kami bahas lebih dalam di panduan cara pakai Claude Code untuk ngoding.

AGENTS.md dan standar lintas-agent

Masalah muncul begitu tim kalian ga seragam tool-nya. Sebagian pakai Cursor, sebagian Claude Code, sebagian lain Zed atau Windsurf. Tiga file rules dengan isi yang harusnya sama, tapi realitanya cepet melenceng. Seseorang update .cursorrules, lupa CLAUDE.md. Dua minggu kemudian aturannya udah beda dan ga ada yang sadar.

AGENTS.md lahir buat itu: satu file yang disepakati banyak agent sebagai sumber konteks. Isinya format bebas markdown, sama seperti yang lain. Sebagian tool sudah baca AGENTS.md secara native, dan Cursor salah satunya, jadi buat Cursor kamu ga butuh file jembatan tambahan. Yang perlu ditangani cuma tool yang belum support: di situ kamu bikin file rules native mereka berisi satu baris pengarah, "Baca AGENTS.md untuk semua konteks proyek." Dengan begitu tetap ada satu sumber kebenaran, dan file jembatan cuma dipasang di tempat yang memang butuh. Anatominya, aturan file bertingkat per folder, dan kesalahan yang bikin file ini malah diabaikan kami bahas terpisah di panduan AGENTS.md.

# AGENTS.md

Sumber konteks tunggal untuk semua AI agent di repo ini.
Tool yang belum baca file ini native diarahkan ke sini.

## Isi lengkap
(... stack, struktur folder, gaya kode, dan larangan
     seperti contoh di atas ...)

Masalah rules tercecer

Sekalipun kamu rajin, pendekatan file-per-tool punya cacat bawaan. Rules ditulis manual, jadi dia cuma seakurat ingatan orang yang terakhir nyentuh. Keputusan arsitektur diambil di meeting, ga masuk file. Konvensi berubah, file ketinggalan. Lama-lama file rules jadi dokumentasi basi yang malah nyesatin agent.

Dan yang lebih dalam: file rules cuma ngatur gaya, bukan maksud. Dia bilang "pakai named export", tapi ga bilang "fitur ini harus handle kasus user tanpa langganan". Agent nurut gaya, tapi tetap salah bikin fitur karena ga tahu spesifikasinya. Konsistensi kode doang ga cukup kalau konteks produk-nya hilang.

Turunkan file rules dari satu PRD

Cara yang lebih tahan lama: taruh sumber kebenaran di atas file rules, lalu turunkan file-file itu darinya. Sumber yang paling masuk akal adalah PRD, dokumen yang udah memuat stack, keputusan arsitektur, batasan, dan yang harus dibangun. Dari satu PRD, kamu bisa generate .cursorrules (atau .cursor/rules/*.mdc), CLAUDE.md, dan AGENTS.md yang isinya konsisten, plus konteks fitur yang ga muat di file rules manual.

Ini pendekatan yang dipakai Skematik: kamu tulis PRD sekali, dan hasilnya bisa diserahkan langsung ke agent sebagai konteks. Bukan cuma "gaya kode", tapi "apa yang dibangun, kenapa, dan batasannya apa". Agent jadi konsisten di dua level sekaligus: konvensi dan maksud.

Kalau kamu penasaran kenapa spec di depan ngalahin nge-prompt sambil jalan, baca vibe coding vs spec-driven development. Dan buat naikin kualitas instruksimu, prompt untuk AI coding ngebahas pola prompt yang bikin agent ga meleset.

Kunci konvensimu di satu tempat

File rules itu upgrade nyata dibanding ngeprompt telanjang. .cursorrules, CLAUDE.md, dan AGENTS.md bikin agent berhenti nebak dan mulai nurut. Tapi kalau ketiganya kamu tulis manual, kamu cuma mindahin beban sinkronisasi ke dirimu sendiri. Naikkan satu level: taruh maksud dan konvensi di PRD, generate file rules dari sana, dan biarin satu dokumen yang jadi rujukan semua agent.

Butuh referensi bentuk PRD-nya seperti apa? Lihat cara membuat PRD untuk aplikasi atau contoh jadi di halaman contoh.

Berhenti benerin gaya kode tiap sesi. Kunci konvensinya sekali, di sumber yang tiap agent baca.