Panduan praktis menulis CLAUDE.md: perintah, arsitektur, operasi terlarang, dan referensi file, dengan contoh proyek Rails nyata.
Setiap kali kamu membuka Claude Code, ia mulai dari nol — tidak mengingat percakapan sebelumnya, tidak tahu apa yang dilakukan proyekmu, tidak tahu apakah perintah test adalah rspec atau pytest, dan tidak tahu operasi mana yang dilarang.
CLAUDE.md menyelesaikan masalah ini. Ini adalah file instruksi permanen yang kamu tulis untuk Claude, dimuat secara otomatis di awal setiap percakapan. CLAUDE.md yang ditulis dengan baik membuat Claude langsung masuk mode kerja — tanpa pertanyaan yang tidak perlu, tanpa kesalahan dasar.
Claude Code mendukung sistem CLAUDE.md berlapis dengan tiga level:
~/.claude/CLAUDE.md: Konfigurasi global, berlaku untuk semua proyekmu. Gunakan untuk preferensi umum seperti "jangan pernah auto-commit git" atau "balas dalam bahasa Indonesia".CLAUDE.md di root project: Konfigurasi di level project. Lokasi yang paling umum.CLAUDE.md di subdirektori: Hanya dimuat saat Claude bekerja dengan file di direktori tersebut. Ideal untuk memberi instruksi khusus pada frontend/, api/, atau infra/.Beberapa file CLAUDE.md saling berlapis — yang lebih spesifik memiliki prioritas atas yang lebih umum.
Satu paragraf yang memberi tahu Claude apa proyek ini dan teknologi apa yang digunakan:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
Menyertakan nomor versi itu penting. Mengetahui ini Rails 8 mencegah Claude menyarankan pola-pola era Rails 6. Mengetahui ada 4 database mencegah kesalahan pada migration.
Ini adalah seksi dengan return on investment tertinggi di CLAUDE.md mana pun. Tanpanya, Claude menebak — dan tebakannya salah.
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
Daftar ini memberitahu Claude: test dijalankan dengan bundle exec rspec, bukan rails test; deployment menggunakan Kamal, bukan Capistrano atau Fly.io; linter adalah RuboCop yang dikonfigurasi dengan preset Rails Omakase. Tanpa ini, Claude harus menebak semuanya.
Tujuan catatan arsitektur adalah mendokumentasikan keputusan yang tidak terlihat dalam kode itu sendiri. Claude bisa membaca struktur direktori; ia tidak bisa tahu mengapa diorganisir seperti itu.
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
Tiga poin ini memberitahu Claude: jangan menumpuk business logic di controller; cari aturan permission di app/policies/; gunakan Solid Queue untuk apa pun yang membutuhkan pemrosesan asinkron.
Mengelompokkan domain model berdasarkan area fungsional juga berharga:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
Ini lebih efisien daripada membiarkan Claude memindai app/models/ sendiri, dan juga menyampaikan semantik bisnis — seperti fakta bahwa 400 poin adalah ambang batas VIP, yang tidak jelas hanya dari membaca kode.
Ini adalah seksi yang paling sering diabaikan, dan sering kali yang paling kritis:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
Ketiganya adalah informasi tipe "tidak ditulis maka menyesal": multi-database mengharuskan menentukan target migration secara eksplisit; Lexxy adalah gem beta dengan perilaku berbeda dari ActionText standar; Propshaft bekerja berbeda dari Sprockets.
Ini adalah seksi yang paling diremehkan. Memberitahu Claude apa yang tidak boleh dilakukan jauh lebih efisien daripada mengoreksinya setelah kejadian.
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
Poin pertama ada di hampir setiap proyek. Perintah deployment bahkan lebih penting — bin/kamal deploy yang salah langsung mengenai production.
CLAUDE.md mendukung referensi @ untuk menyertakan file lain:
Konfigurasi deployment: @config/deploy.yml
Skema database: @db/schema.rb
Claude membaca file-file ini saat diperlukan. db/schema.rb sangat berguna — dalam project Rails ini adalah satu-satunya sumber kebenaran untuk struktur database.
Menulis terlalu banyak: CLAUDE.md mengonsumsi jendela konteks. Menempelkan seluruh README menyisakan lebih sedikit ruang bagi Claude untuk bekerja dengan kode nyata. Tulis hanya apa yang tidak bisa Claude turunkan dari membaca codebase itu sendiri.
Panduan yang samar: "Tulis kode yang baik" tidak berguna. Jadilah spesifik: "Jangan menaruh business logic langsung di controller — delegasikan ke app/services/".
Lupa memperbarui: Jika kamu migrasi dari Sprockets ke Propshaft dan CLAUDE.md tidak mengikuti, Claude akan beroperasi dengan asumsi yang usang. Sertakan pembaruan CLAUDE.md dalam checklist refactoring besar mana pun.
Menulis contoh kode: Contoh mengonsumsi konteks, dan Claude membaca kode nyata dengan lebih akurat daripada snippet ilustratif. Gunakan referensi @ untuk menunjuk ke file nyata.
# [Nama Proyek]
[Deskripsi dalam satu kalimat]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[Bagaimana tanggung jawab dibagi antara Services / Jobs / Policies]
[Domain model dikelompokkan berdasarkan area fungsional]
## Important Notes
[Konfigurasi yang tidak obvious, perilaku khusus gem]
## Do Not
- Do NOT run git commit automatically
[Operasi berisiko tinggi lainnya]
Mulai dari template ini dan isi apa yang benar-benar dibutuhkan proyekmu. Tidak perlu mencakup segalanya — CLAUDE.md dengan lima poin yang tepat jauh lebih berharga daripada yang dipenuhi kebisingan.