Analisis struktur folder .claude/

• Folder .claude/ adalah direktori kontrol inti untuk Claude Code yang mengelola aturan, perintah, izin, dan status memori per proyek
• CLAUDE.md adalah file pusat yang mendefinisikan prinsip perilaku dan aturan proyek Claude, dengan penerapan melalui penggabungan beberapa lapisan konfigurasi
• Folder commands/, skills/, dan agents/ masing-masing menyusun perintah kustom, workflow otomatis, dan subagen spesialis untuk meningkatkan efisiensi kolaborasi
• settings.json mengontrol izin eksekusi perintah dan cakupan akses file, dan override per pengguna dimungkinkan melalui settings.local.json
• Seluruh struktur berfungsi sebagai protokol yang menyampaikan identitas dan aturan proyek kepada Claude, sehingga konfigurasi yang jelas memaksimalkan produktivitas dan efisiensi kolaborasi

---

Struktur folder .claude/ dan komponennya

• Folder .claude/ adalah direktori inti yang mengendalikan cara kerja Claude Code dan mengelola aturan, perintah, izin, serta status memori per proyek
• Folder di root proyek berisi konfigurasi tingkat tim dan di-commit ke Git
• Folder di home directory (~/.claude/) menyimpan konfigurasi pribadi dan riwayat sesi, termasuk memori otomatis dan perintah pribadi

• CLAUDE.md — panduan instruksi Claude

  • File pertama yang dibaca saat sesi Claude Code dimulai, yang mendefinisikan prinsip perilaku Claude dan aturan proyek
  • CLAUDE.md di root proyek menangani aturan bersama tim, ~/.claude/CLAUDE.md menangani aturan pribadi global, dan CLAUDE.md di subfolder menangani aturan per folder
  • Claude menggabungkan dan menerapkan beberapa file CLAUDE.md
  • Isi yang direkomendasikan mencakup perintah build dan test, keputusan arsitektur utama, batasan yang tidak intuitif, serta aturan penamaan dan penanganan error
  • Disarankan tetap di bawah 200 baris, karena terlalu panjang menurunkan tingkat kepatuhan Claude terhadap instruksi

• CLAUDE.local.md — override per pengguna

  • File untuk mencerminkan preferensi pribadi secara terpisah dari aturan bersama tim
  • Jika membuat CLAUDE.local.md di root proyek, Claude akan membacanya bersama file lain
  • Otomatis masuk ke .gitignore sehingga tidak di-commit ke repositori

• rules/ folder — pengelolaan aturan modular

  • Jika CLAUDE.md membesar, pengelolaannya bisa dipisah ke folder .claude/rules/
  • Setiap file aturan dipisahkan berdasarkan topik sehingga lebih mudah dirawat
    • Contoh: code-style.md, testing.md, api-conventions.md, security.md
  • Dengan memakai field paths pada YAML frontmatter, kita bisa menetapkan aturan yang hanya berlaku untuk path tertentu
    • Contoh: menerapkan aturan API hanya ke path src/api/**/*.ts
  • Aturan tanpa penetapan path akan selalu dimuat di semua sesi

• commands/ folder — perintah slash kustom

  • Setiap file Markdown di folder .claude/commands/ didaftarkan sebagai perintah slash (/)
    • Contoh: review.md → /project:review, fix-issue.md → /project:fix-issue
  • Dengan sintaks backtick !, hasil eksekusi perintah shell dapat disisipkan ke prompt Claude
    • Contoh: !git diff main...HEAD
  • Dengan variabel $ARGUMENTS, argumen dapat diteruskan saat menjalankan perintah
    • Contoh: /project:fix-issue 234 → otomatis memuat isi GitHub issue 234
  • Perintah proyek dibagikan ke tim, sedangkan perintah pribadi disimpan di ~/.claude/commands/ dan dapat digunakan di semua proyek

• skills/ folder — workflow yang berjalan otomatis

  • Berfungsi sebagai workflow yang mirip perintah tetapi dipicu secara otomatis
  • Claude menganalisis isi percakapan dan menjalankannya otomatis dalam situasi yang sesuai
  • Tiap skill didefinisikan lewat file SKILL.md di subfolder, dan YAML frontmatter menetapkan kondisi trigger serta tool yang diizinkan
    • Contoh: skill security-review berjalan otomatis saat ada percakapan terkait keamanan
  • Folder skill juga dapat memuat dokumen pendukung atau file template seperti DETAILED_GUIDE.md
  • Skill pribadi disimpan di ~/.claude/skills/ dan bisa digunakan secara global

• agents/ folder — subagen spesialis

  • Folder .claude/agents/ mendefinisikan subagen (persona) yang menjalankan peran tertentu
  • Setiap agen memiliki system prompt, model, dan izin akses tool yang terpisah
    • Contoh: code-reviewer.md, security-auditor.md
  • Pembatasan tool yang bisa diakses melalui field tools mewujudkan keamanan dan pemisahan peran
  • Melalui field model, bisa dipilih model Claude yang sesuai tugas (misalnya Haiku, Sonnet, Opus)
  • Saat diperlukan, Claude menjalankan agen tersebut dalam konteks terpisah lalu hanya melaporkan ringkasan hasilnya

• settings.json — izin dan konfigurasi proyek

  • .claude/settings.json mendefinisikan izin eksekusi perintah dan cakupan akses file Claude
  • Field $schema mendukung autocomplete dan validasi di VS Code dan sebagainya
  • Daftar allow menetapkan perintah yang disetujui otomatis, sedangkan daftar deny menetapkan perintah yang diblokir sepenuhnya
    • Contoh: diizinkan — Bash(npm run *), Read, Write, Edit
    • Diblokir — Bash(rm -rf *), Bash(curl *), membaca file .env
  • Perintah yang tidak ada dalam daftar akan meminta konfirmasi pengguna sebelum dijalankan
  • Perubahan izin per pengguna disimpan di .claude/settings.local.json dan tidak dimasukkan ke Git

• ~/.claude/ folder — konfigurasi global dan memori

  • ~/.claude/CLAUDE.md adalah instruksi pribadi yang berlaku untuk semua proyek
  • ~/.claude/projects/ menyimpan riwayat sesi dan memori otomatis per proyek
    • Menjaga perintah, pola, dan wawasan struktural yang dipelajari Claude
    • Dapat dilihat dan diubah dengan perintah /memory
  • ~/.claude/commands/, ~/.claude/skills/, dan ~/.claude/agents/ adalah repositori perintah, skill, dan agen pribadi global

• Contoh keseluruhan struktur

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Tahap pengaturan awal

  • Langkah 1: buat CLAUDE.md dasar dengan perintah /init, lalu sisakan hanya isi inti
  • Langkah 2: tulis .claude/settings.json, lalu definisikan aturan izin dan pemblokiran eksekusi

  • Langkah 3:tambahkan perintah yang sesuai dengan workflow yang sering dipakai (misalnya code review, perbaikan issue)

    • Langkah 4: jika CLAUDE.md membesar, pisahkan ke .claude/rules/
    • Langkah 5: tambahkan aturan preferensi pribadi ke ~/.claude/CLAUDE.md

Insight utama

• Folder .claude/ adalah protokol yang menyampaikan identitas dan aturan proyek kepada Claude
• CLAUDE.md adalah file yang paling penting, dan semakin jelas didefinisikan, semakin maksimal produktivitas Claude
• Komponen lainnya adalah lapisan optimasi pelengkap yang bisa diperluas secara bertahap
• Konfigurasi yang jelas menghasilkan lebih sedikit permintaan revisi ke Claude dan kolaborasi yang lebih efisien

Diskusi tambahan

• Daftar deny pada settings.json aman saat digunakan manusia, tetapi dalam agent mode perlindungan tambahan diperlukan karena adanya akses Bash
• OneCLI menyediakan lapisan proxy di tingkat jaringan yang menggantikan token kredensial untuk mencegah kebocoran rahasia
• Ke depan, muncul kebutuhan akan konfigurasi .claude khusus agent mode (pemisahan aturan, izin, dan skill)
• Menurut dokumentasi terbaru, commands dan skills telah disatukan, sehingga .claude/commands/deploy.md dan .claude/skills/deploy/SKILL.md sama-sama membuat perintah /deploy, sementara skill mendukung fungsi tambahan seperti file pendukung dan trigger otomatis

[GN⁺]

Komentar Hacker News

• Membangun toolkit agen AI terasa seperti mencari setup produktivitas yang sempurna
  Kita menonton blog post dan YouTube untuk membuat rutinitas, tetapi pada akhirnya orang yang konsisten bekerja dengan daftar tugas sederhana justru lebih unggul
  Dalam pengalaman saya, pendekatan sederhana dengan meminta Plain Claude menyusun rencana, meninjau, lalu mengeksekusinya masih yang paling efektif

  • Untuk codebase besar atau sistem terdistribusi, ceritanya berbeda
    Keahlian teknis agen dalam mem-pipe data, membuat request, melacak sistem, dan memperbarui kode bisa meningkatkan efisiensi pengembangan secara drastis
    Pada kode berskala 10 juta baris, produktivitas meningkat besar, dan porsi yang benar-benar berasal dari pembuatan kode bahkan kurang dari 5%
    Sebagian besar datang dari kemampuan membuat toolchain untuk pengujian dan verifikasi dengan cepat
  • Banyak orang terjebak dalam jebakan ini dan menghabiskan uang
    Padahal kalau seseorang jelas tahu apa yang diinginkan dan bisa menyampaikannya dengan baik, banyak hal sudah bisa dilakukan dengan AI
    Kebanyakan orang tidak tahu itu. Karena itu, proses meminta AI membuat rencana menjadi jalan pintas untuk memperoleh pemahaman
  • Sebagai PM, saya ingin agen menghemat waktu dan memberi efek compounding pada output
    Tetapi ada inefisiensi karena harus mengulang konteks di setiap sesi dan menyalin file .md
    Tujuan saya sekarang adalah menghilangkan pengulangan ini.
    Saya penasaran bagaimana orang mengelola 'context bank' yang mengakumulasi konteks — misalnya info dasar seperti “peran saya, produk yang saya tangani, dokumen terbaru”
    Dokumennya banyak yang duplikat dan usang, jadi saya juga tidak bisa sekadar menghubungkan seluruh Drive
    Kalau konteks yang sama muncul lebih dari dua kali, saya masih bingung apakah perlu membuat file Skill atau mengumpulkan dokumen dan mengelolanya dalam satu folder
  • Saya juga punya pengalaman serupa. Artefak yang dihasilkan selama bekerja kebanyakan akhirnya dibuang
    Over-configuration menyebabkan penurunan kualitas dan masalah loop
    Karena model terus membaik, instruksi yang dulu perlu justru kadang menghambat performa
    Saya juga pernah dengar tim Anthropic mereset claude.md setiap 30 hari
  • Sebaliknya, saya sedang mengerjakan proyek yang harus mengintegrasikan API akuntansi lokal, dan ini API yang sepenuhnya kustom sehingga tidak dikenal LLM
    Jadi saya meminta Claude membuat server MCP, dan sekarang ia menangani pekerjaan akuntansi secara otomatis
    Setelah tutup buku bulanan, saya meminta Claude mengekstrak tugas-tugas utama dan menjadikannya Skill, dan hasilnya bekerja seperti punya akuntan junior
    MCP kustom dan Skill terasa sangat berguna

• Terasa seperti banyak orang membangun tembok konfigurasi besar sebelum mulai agentic coding
  Namun pada awalnya seharusnya cukup mulai dengan .claude kosong dan AGENTS.md lalu belajar cara mengendalikannya sendiri

  • Saya bahkan berpikir sebaiknya hanya memakai skill buatan sendiri
    Kalau asal memasang skill buatan orang lain, nondeterminism akan meningkat dan context window juga terbuang
    Satu-satunya pengecualian yang layak direkomendasikan dari luar mungkin hanya playwright-cli
  • Dalam tim besar, diperlukan guardrail (aturan) yang konsisten
    Misalnya, jika diatur untuk memeriksa prasyarat seperti aturan ini, hasilnya lebih stabil
    Saya rasa tim keamanan juga akan menyukai pendekatan seperti ini
    Saat mendefinisikan aturan, saya juga membuat Claude tidak bisa commit tanpa tanda tangan GPG
    Tapi aturan seperti ini bukan sesuatu yang tetap, melainkan harus terus berevolusi
  • Tulisan ini bukan memaksa orang membuat setup besar
    Justru berulang kali menekankan untuk memulai dari kecil dan tetap singkat
    Bahkan pemula pun cukup menambahkan beberapa baris ke AGENTS.md agar AI lebih memahami maksud pengguna
    Setup sederhana dapat sangat mengurangi malfungsi AI
  • Menangani kode sendirian dan menangani proyek bersama dalam skala tim adalah hal yang sepenuhnya berbeda
    Jika tiap developer memakai alat agentic, cara kolaborasinya sendiri akan berubah
  • Untuk awal, memakai mode plan saja sudah menyelesaikan 90% masalah
    Diskusi setup rumit seperti ini sepertinya akan mostly hilang dalam setahun seiring model makin maju

• Folder ~/.claude/projects adalah bagian yang benar-benar menarik

• Menurut saya, hasilnya lebih baik ketika konfigurasi yang tidak perlu lebih sedikit
  Orang sering membuat dokumen terlalu preskriptif, tetapi AI itu seperti orang dewasa yang kompeten tapi gugup
  Kalau diberi terlalu banyak instruksi, malah jadi lebih bodoh

• Tulisan ini terasa seperti hasil generatif ketimbang pengalaman nyata
  Claude.md sebaiknya singkat, cukup taruh beberapa link
  Saat konteks menumpuk, performa menurun, jadi perencanaan dan implementasi harus dipisahkan lalu direset setiap kali

  • Bagian pembukanya terlalu mirip gaya bahasa Claude, jadi saya merasa bisa langsung bertanya ke Claude saja
  • Perbedaan antara skill dan command membingungkan
    Tidak jelas apakah skill selalu ada di konteks, sedangkan command hanya bisa dipanggil manual

• Akan bagus jika semua penyedia model berbagi set file standar
  Dengan begitu, berpindah antara Claude, Codex, Cursor, dan Opencode akan lebih mudah

  • Namun kombinasi model dan harness sangat memengaruhi hasil
    Bahkan untuk prompt yang sama, respons tiap model berbeda, jadi prompt tuning harus berbeda per model
  • Bisa saja membuat satu agents.md lalu membiarkan Claude.md merujuk ke sana, dan menghubungkannya antarfolder dengan symlink (sync)
    Tidak sempurna, tetapi cukup efektif
  • Sekarang ini rasanya seperti era awal browser. Justru karena belum distandardisasi, inovasi seperti AJAX bisa muncul
    Jadi keragaman saat ini malah positif
  • Untuk sementara saya memakai dotagents by Sentry untuk menyelesaikan masalah ini
  • Saya rasa penyedia model memang tidak punya alasan untuk sengaja mempermudah perpindahan

• Dokumen alternatif untuk Claude Fast sangat berguna
  Saya tidak mengerti kenapa orang harus membenci definisi folder .claude
  Kita bisa membuat agen utama menulis file secara langsung, memperbaruinya berulang kali, dan membangun sistem yang memperbaiki diri sendiri
  Saat ini .claude menyalin, mengevaluasi, dan memperbarui dirinya sendiri — rasanya saya bukan menulis kode, melainkan mengodekan .claude

  • Singkatnya, CLAUDE.md bukan sekadar dokumen, melainkan sistem operasi Claude
    Intinya adalah mendefinisikan perilaku, mendelegasikan pengetahuan ke skill, dan membangun sistem yang terus memperbaiki dirinya seiring waktu

• Hambatan yang tidak banyak diketahui orang adalah, meskipun Claude diminta memodifikasi file, perubahan itu tidak akan tercermin jika tidak secara eksplisit diminta membacanya lagi
  Misalnya, jika baru menulis CLAUDE.md, Claude perlu di-reload agar mengenalinya sebagai instruksi baru

• Di folder ~/.claude/plans, disimpan file rencana yang dibuat saat menjalankan mode plan
  Saya sering membuka direktori ini untuk backup atau sebagai referensi

• Saya membangun setup dengan berpusat pada server MCP global dan composite agent
  Tiap server MCP mendefinisikan satu set tool, dan agen bekerja secara otonom di dalamnya
  .agent.md hanyalah dokumen yang menjelaskan tool yang tersedia, jadi setup rumit tidak diperlukan
  Menurut saya skill atau prompt yang dapat dipakai ulang nilainya rendah
  Model sudah cukup pintar, jadi yang dibutuhkan hanyalah orientasi