Instruksi proyek dan izin awal

Setiap sesi agen dimulai tanpa ingatan tentang proyekmu. Supaya ia tidak perlu diberi tahu hal yang sama setiap kali, kebanyakan alat agen membaca satu berkas instruksi (instruction file, misalnya AGENTS.md) milik proyek di awal sesi. Isinya menjadi bagian dari system prompt (instruksi sistem): aturan yang berlaku untuk semua permintaan di proyek itu.

Berkas instruksi yang baik itu pendek dan bisa diperiksa. Bandingkan "tulis kode yang rapi" dengan "jalankan tes yang relevan dan type check (pemeriksaan tipe) sebelum menyatakan selesai". Yang pertama tidak bisa dicek; yang kedua bisa. Tulis aturan yang, kalau dilanggar, pelanggarannya terlihat.

Isi yang paling berguna biasanya:

• Cara memeriksa pekerjaan: perintah tes, type check, build (langkah yang mengubah kode menjadi aplikasi siap jalan), dan kapan masing-masing wajib dijalankan.
• Cara kerja tim: satu branch (cabang) per tugas, pesan commit (menyimpan satu set perubahan ke riwayat git), berkas mana yang dimiliki siapa.
• Larangan yang jelas: jangan pernah menambahkan semua berkas sekaligus ke commit, jangan menyentuh basis data (database) di port bawaan, jangan menggabung ke branch utama.
• Hal yang mudah salah di proyek ini: pelajaran dari kejadian sebelumnya, ditulis satu baris per pelajaran.

Yang tidak perlu ditulis: penjelasan panjang tentang bahasa pemrograman, motivasi, atau hal yang bisa agen baca sendiri dari kode. Setiap baris di berkas instruksi dibaca ulang di setiap sesi dan memakan konteks, jadi pangkas yang tidak dipakai.

Instruksi memberi tahu agen apa yang sebaiknya ia lakukan. Aturan izin menentukan apa yang bisa ia lakukan. Bedanya penting: model bisa salah membaca atau terkecoh instruksi, tetapi aturan izin dijalankan oleh aplikasi, di luar model.

Susun aturan izin awal dalam tiga tingkat:

1. Izinkan tanpa bertanya: tindakan yang murah dan aman, seperti membaca berkas proyek atau menjalankan perintah tes tertentu. Inilah daftar izin (allowlist): tertutup, hanya yang disebut yang boleh.
2. Tanya dulu: tindakan yang mengubah sesuatu di luar ruang kerja, seperti mendorong perubahan ke repositori (repository) bersama atau memasang paket baru.
3. Tolak: tindakan yang tidak boleh terjadi dalam sesi ini, seperti membaca berkas rahasia atau menghapus folder.

Mulailah sempit. Kalau agen terlalu sering bertanya untuk tindakan yang ternyata aman, pindahkan tindakan itu ke daftar izinkan, satu per satu, setelah kamu melihatnya. Jangan mulai dari "izinkan semua" lalu berharap menambal belakangan. Ingat juga bahwa aturan izin sama pentingnya dengan isi berkas instruksi: keduanya disimpan di repositori, ditinjau seperti kode, dan diubah dengan alasan yang tertulis.

Sebagai contoh yang dikerjakan, begini bentuknya di Claude Code. Berkas instruksi proyek bernama CLAUDE.md di akar proyek dan dibaca di awal sesi. Aturan izin disimpan di .claude/settings.json (dibagikan ke tim lewat repositori) atau di berkas pengaturan lokal pribadi di folder yang sama (hanya untukmu, untuk satu proyek), di bawah kunci permissions dengan daftar allow, ask, dan deny:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

Aturan deny dan ask di berkas proyek berlaku segera; aturan allow dari berkas yang di-commit baru berlaku setelah folder itu dipercaya oleh setiap anggota tim. Perintah /status menunjukkan berkas pengaturan mana yang terbaca. Langkah khusus Anthropic; cek versi terbaru di dokumentasinya karena nama dan perilaku pengaturan bisa berubah.