CLAUDE.md: Cara Membuat AI Selalu Paham Konteks Proyek Golang

CLAUDE.md: Memori Proyek yang Membuat AI Paham Konteksmu

Ada satu frustrasi yang hampir universal di antara developer yang mulai pakai Claude Code: setiap sesi baru, harus menjelaskan ulang tentang arsitektur proyek, stack teknikal, conventions yang dipakai, dan rules yang sudah disepakati tim. Lima menit penjelasan sebelum bisa mulai kerja. Setiap hari.

CLAUDE.md adalah solusinya. File ini adalah “memori proyek” yang dibaca Claude Code secara otomatis di setiap sesi — sehingga AI selalu punya konteks yang tepat tanpa perlu dijelaskan ulang.

Di artikel ini, kita bahas cara menulis CLAUDE.md golang claude code yang benar-benar efektif untuk proyek Golang production.

04.1 Apa Itu CLAUDE.md dan Bagaimana Cara Kerjanya

CLAUDE.md adalah file Markdown yang diletakkan di root direktori proyek. Claude Code membaca file ini secara otomatis di setiap sesi — menjadikannya sebagai persistent project context.

Cara kerjanya paling mudah dipahami lewat perbandingan alur sesi dengan dan tanpa file ini, seperti diagram berikut.

1Tanpa CLAUDE.md:
2Sesi 1: [Jelaskan arsitektur 5 menit] → [Coding 30 menit]
3Sesi 2: [Jelaskan arsitektur 5 menit lagi] → [Coding 30 menit]
4Sesi N: [Jelaskan arsitektur 5 menit lagi] → [Coding 30 menit]
5
6Dengan CLAUDE.md:
7Sesi 1: [Claude baca CLAUDE.md otomatis] → [Coding langsung]
8Sesi 2: [Claude baca CLAUDE.md otomatis] → [Coding langsung]
9Sesi N: [Claude baca CLAUDE.md otomatis] → [Coding langsung]

Lebih dari sekadar efisiensi waktu — CLAUDE.md juga memastikan Claude Code selalu generate kode yang konsisten dengan arsitektur yang sudah ditetapkan tim, bahkan jika yang menggunakan Claude Code adalah developer baru yang belum hafal semua conventions.

04.2 Komponen Wajib CLAUDE.md untuk Proyek Golang

Berdasarkan pengalaman menggunakan SDD di proyek Golang production, ada enam komponen yang sebaiknya selalu ada.

Komponen 1: Project Overview

Komponen pertama menjelaskan service ini apa dan mengerjakan apa, seperti contoh berikut.

1## Project Overview
2
3**Santekno Shop** adalah platform e-commerce multi-tenant.
4Service ini: **Order Service** — mengelola lifecycle order dari creation hingga delivery.
5
6Repository: github.com/santekno/santekno-shop
7Go module: github.com/santekno/santekno-shop

Overview singkat ini memberi AI (dan developer baru) gambaran besar sebelum masuk ke detail teknis.

Komponen 2: Tech Stack (Versi Spesifik)

Komponen kedua mencantumkan library beserta versinya secara eksplisit, seperti tabel berikut.

 1## Tech Stack
 2
 3| Komponen | Library | Versi |
 4|----------|---------|-------|
 5| Language | Go | 1.22+ |
 6| HTTP | Echo | v4 |
 7| PostgreSQL | pgx | v5 |
 8| Cache | go-redis | v9 |
 9| Messaging | confluent-kafka-go | v2 |
10| Auth | golang-jwt/jwt | v5 |
11| UUID | google/uuid | v1 |
12| Testing | testify | v1.9 |
13| Mocking | gomock | v1.6 |
14| Logging | log/slog | stdlib |

Versi yang eksplisit mencegah AI menghasilkan kode yang memakai API library versi lama atau berbeda dari yang benar-benar dipakai proyek.

Komponen 3: Architecture Rules

Komponen ketiga menetapkan urutan layer dan aturan yang tidak boleh dilanggar, dituliskan dengan bahasa imperatif seperti berikut.

 1## Architecture Rules
 2
 3### Layer Order (WAJIB)
 4domain → usecase → repository → delivery/http
 5
 6### Rules yang Tidak Boleh Dilanggar
 7- TIDAK BOLEH: import usecase dari domain layer
 8- TIDAK BOLEH: direct DB call dari handler atau usecase
 9- TIDAK BOLEH: import package `delivery` dari layer lain
10- HARUS: dependency injection via constructor function
11- HARUS: interface untuk semua external dependency (DB, cache, kafka)
12- HARUS: error wrapping dengan `fmt.Errorf("context: %w", err)`

Aturan setegas ini membuat AI menolak menghasilkan kode yang melanggar clean architecture, bahkan ketika prompt user tidak menyebut arsitektur sama sekali.

Komponen 4: Naming Conventions

Komponen keempat menyeragamkan penamaan file, tipe, dan package, seperti daftar berikut.

 1## Naming Conventions
 2
 3### File Names
 4- Handler: `product_handler.go`
 5- Usecase: `create_product.go`, `update_product.go`
 6- Repository: `product_repository.go`
 7- Entity: `entity.go` (di dalam package domain)
 8
 9### Types dan Variables
10- Struct: PascalCase (`OrderHandler`, `CreateProductInput`)
11- Interface: Verb-er pattern (`OrderRepository`, `ProductService`)
12- Error variable: `ErrPascalCase` (`ErrOrderNotFound`, `ErrInsufficientStock`)
13- Constant: UPPER_SNAKE_CASE untuk domain status (`ORDER_PENDING`)
14
15### Package Names
16- Domain: singular lowercase (`order`, `product`, `user`)
17- Handler: `handler`
18- Usecase: `usecase` atau nama domain
19- Repository: `postgres`, `redis`

Dengan konvensi penamaan yang eksplisit, kode yang di-generate langsung terasa “seperti buatan tim” tanpa perlu di-rename manual setelahnya.

Komponen 5: Spec Rules

Komponen kelima menginstruksikan AI untuk selalu menuntut spec sebelum implementasi, seperti berikut.

 1## Spec Rules
 2
 3Setiap fitur HARUS punya spec di `specs/domain/[feature-name].md` SEBELUM implementasi.
 4
 5Jika diminta implementasi fitur:
 61. Tanyakan: "Spec-nya ada di mana?"
 72. Jika tidak ada: "Mari buat spec dulu, baru implementasi"
 83. Jangan pernah skip spec untuk fitur yang akan masuk production
 9
10Format spec: lihat `specs/_templates/feature-spec.md`

Inilah jembatan antara CLAUDE.md dan workflow SDD: aturan ini memaksa AI menegakkan disiplin spec-first di setiap permintaan implementasi.

Komponen 6: Reference Patterns

Komponen keenam menunjuk file yang sudah menjadi contoh pola established, seperti berikut.

1## Reference Code Patterns
2
3Untuk pattern yang sudah established, lihat:
4- Handler: `internal/delivery/http/handler/order_handler.go`
5- Usecase: `internal/usecase/order/create_order.go`
6- Repository: `internal/repository/postgres/order_repository.go`
7- Test: `internal/usecase/order/create_order_test.go`
8
9Ikuti pola yang sama, jangan reinvent pattern tanpa alasan yang jelas.

Dengan menunjuk file referensi konkret, AI bisa meniru pola yang benar-benar ada di codebase alih-alih mengarang gaya baru yang tidak konsisten.

04.3 CLAUDE.md Lengkap untuk Santekno Shop

Setelah memahami keenam komponen di atas, mari satukan semuanya. Berikut CLAUDE.md lengkap yang akan kita gunakan sepanjang seri ini untuk Santekno Shop.

 1# CLAUDE.md — Santekno Shop
 2
 3> File ini dibaca otomatis oleh Claude Code. Jangan hapus atau pindahkan.
 4> Untuk pertanyaan: @ihsan-arif (tech lead)
 5
 6---
 7
 8## Project Overview
 9
10**Santekno Shop** adalah platform e-commerce B2C Indonesia.
11Service ini: **Order Service** — mengelola lifecycle order.
12
13- Go module: `github.com/santekno/santekno-shop`
14- Dibuat: 2025-01-01
15- Tech lead: @ihsan-arif
16
17---
18
19## Tech Stack
20
21Language:     Go 1.22+
22HTTP:         Echo v4 (labstack/echo)
23PostgreSQL:   pgx/v5 (jackc/pgx)
24Redis:        go-redis/v9
25Kafka:        confluent-kafka-go v2
26Auth:         golang-jwt/jwt/v5
27UUID:         github.com/google/uuid v1
28Testing:      testify/suite v1.9 + gomock v1.6
29Logging:      log/slog (stdlib, structured logging)
30Linting:      golangci-lint
31
32---
33
34## Architecture Rules
35
36### Layer Dependency (WAJIB, tidak boleh dilanggar)
37domain ← usecase ← repository
38domain ← usecase ← delivery/http
39
40### Rules
41- **TIDAK BOLEH**: Direct DB call dari handler, usecase, atau domain
42- **TIDAK BOLEH**: Import `delivery` package dari layer lain
43- **TIDAK BOLEH**: Logika bisnis di handler layer
44- **HARUS**: Semua external dependency via interface
45- **HARUS**: Constructor injection (func NewXxx(dep1 Dep1, dep2 Dep2) *Xxx)
46- **HARUS**: Error wrapping: fmt.Errorf("funcName: %w", err)
47- **HARUS**: Context propagation di semua function signature
48- **HARUS**: Gunakan slog.InfoContext(ctx, ...) bukan log.Printf
49
50---
51
52## Domain Types
53
54### Order Status
55StatusPending   Status = "PENDING"
56StatusConfirmed Status = "CONFIRMED"
57StatusShipped   Status = "SHIPPED"
58StatusDelivered Status = "DELIVERED"
59StatusCancelled Status = "CANCELLED"
60
61### ID Convention
62- Selalu gunakan uuid.UUID dari github.com/google/uuid
63- Tidak boleh menggunakan int atau string sebagai ID entitas
64
65### Price Convention
66- Selalu simpan harga dalam satuan sen (cents) sebagai int64
67- Field name: PriceCents, TotalAmountCents, RefundAmountCents
68- TIDAK BOLEH menggunakan float64 untuk harga
69
70---
71
72## Spec Rules
73
74Setiap fitur HARUS punya spec di `specs/domain/[feature-name].md` SEBELUM implementasi.
75
76Jika diminta implementasi fitur:
771. Tanyakan: "Spec-nya ada di mana?"
782. Jika tidak ada: "Mari buat spec dulu, baru implementasi"
793. Jangan pernah skip spec untuk fitur yang akan masuk production
80
81Format spec: lihat `specs/_templates/feature-spec.md`
82
83---
84
85## Reference Patterns
86## Reference Code Patterns
87
88Untuk pattern yang sudah established, lihat:
89- Handler: `internal/delivery/http/handler/order_handler.go`
90- Usecase: `internal/usecase/order/create_order.go`
91- Repository: `internal/repository/postgres/order_repository.go`
92- Test: `internal/usecase/order/create_order_test.go`
93
94Ikuti pola yang sama, jangan reinvent pattern tanpa alasan yang jelas.

Perhatikan bahwa file ini tetap ringkas namun padat: cukup untuk memberi AI konteks arsitektur, tipe domain, dan aturan spec, tanpa membengkak menjadi ratusan baris yang justru memboroskan context window.

04.4 Cara Claude Code Menggunakan CLAUDE.md

Ketika claude dijalankan di root proyek, file ini dimuat secara otomatis. Tampilan awal sesi kira-kira seperti ilustrasi berikut.

 1$ claude
 2                              ╔═══════════════════════╗
 3                              ║    Claude Code         ║
 4                              ║    Santekno Shop       ║
 5                              ╚═══════════════════════╝
 6Reading project context from CLAUDE.md...
 7✓ Architecture rules loaded
 8✓ Tech stack context loaded
 9✓ Naming conventions loaded
10✓ Spec rules loaded
11
12What would you like to work on?
13>

Setelah konteks termuat, Claude Code menggunakannya di setiap response. Perbedaannya paling jelas terlihat pada permintaan sederhana yang sama, mulai dari kondisi tanpa CLAUDE.md berikut.

1> Buat fungsi untuk create order
2
3[Claude mungkin menggunakan float64 untuk harga, atau langsung query DB dari handler]

Tanpa konteks, AI menebak — dan tebakannya sering melanggar konvensi proyek. Bandingkan dengan hasil ketika CLAUDE.md tersedia seperti berikut.

1> Buat fungsi untuk create order
2
3[Claude otomatis menggunakan uuid.UUID untuk ID, int64 untuk harga,
4 bertanya tentang spec, dan mengikuti clean architecture layer]

Dengan CLAUDE.md, permintaan yang sama menghasilkan kode yang langsung sesuai konvensi — inilah nilai konkret dari “memori proyek” yang persisten.

04.5 CLAUDE.md untuk Tim: Collaborative Maintenance

CLAUDE.md bukan dokumen pribadi — ini adalah dokumen tim yang harus di-maintain bersama.

Siapa yang Bisa Update CLAUDE.md?

Semua anggota tim bisa propose perubahan, tapi merge ke main harus melalui PR review oleh tech lead atau senior engineer. CLAUDE.md adalah “konstitusi teknikal” proyek.

Kapan CLAUDE.md Perlu Di-update?

• Ketika ada library baru yang diputuskan untuk dipakai
• Ketika ada pattern baru yang disepakati tim
• Ketika ada rules yang perlu ditambahkan atau diubah
• Ketika ada architectural decision record (ADR) baru

Format Commit untuk Update CLAUDE.md

Karena CLAUDE.md ada di git, perubahannya harus punya pesan commit yang jelas seperti contoh berikut.

1git commit -m "docs(claude): add Redis caching convention
2
3Tambah section tentang cara menggunakan Redis untuk caching
4berdasarkan ADR-003. Pattern: cache-aside dengan TTL 5 menit.
5
6Refs: docs/adr/003-redis-caching.md"

Pesan commit yang mereferensikan ADR membuat evolusi CLAUDE.md bisa ditelusuri — setiap aturan baru punya jejak keputusan yang mendasarinya.

04.6 Memvalidasi CLAUDE.md yang Efektif

Bagaimana tahu apakah CLAUDE.md sudah efektif? Jalankan test sederhana dengan menanyakan sesuatu yang melanggar arsitektur, seperti berikut.

1Prompt test 1 (testing architecture awareness):
2"Saya ingin menambahkan logika validasi stock langsung di OrderHandler.
3Apa pendapatmu?"
4
5Response yang diharapkan:
6"Berdasarkan architecture rules di proyek ini, logika bisnis tidak boleh
7ada di handler layer. Validasi stock sebaiknya ada di usecase layer,
8tepatnya di CreateOrderUseCase. Handler hanya bertugas parse request
9dan delegate ke usecase."

Test kedua memeriksa apakah AI menegakkan aturan spec-first, seperti probe berikut.

1Prompt test 2 (testing spec awareness):
2"Implementasikan fitur 'apply coupon to order'"
3
4Response yang diharapkan:
5"Fitur ini belum punya spec. Mari buat spec dulu di
6specs/domain/apply-coupon.md. Saya bisa bantu draft spec-nya
7berdasarkan kebutuhan yang ada."

Jika Claude Code merespons seperti kedua contoh di atas — menolak melanggar arsitektur dan menuntut spec — berarti CLAUDE.md sudah bekerja dengan baik.

04.7 Perbedaan CLAUDE.md dengan .cursorrules dan Kiro Steering

Semua tools punya mekanisme serupa untuk project context, dengan format dan scope yang berbeda. Tabel berikut merangkum padanannya di masing-masing tool.

Intinya sama di semua tool: tulis dalam format yang jelas dan bisa dibaca manusia, karena file ini adalah living documentation — bukan hanya untuk AI, tapi juga berguna untuk manusia yang onboard ke project.

04.8 CLAUDE.md untuk Microservice Environment

Di environment dengan banyak service, ada beberapa strategi.

Strategi 1: Satu CLAUDE.md per service — pendekatan paling sederhana, dengan struktur file seperti berikut.

1order-service/CLAUDE.md
2product-service/CLAUDE.md
3user-service/CLAUDE.md

Kelebihannya fokus, kekurangannya ada duplikasi informasi yang umum di antara service. Untuk mengurangi duplikasi, strategi kedua memakai inheritance seperti berikut.

1# di order-service/CLAUDE.md
2# Inherits common rules from: ../shared/COMMON.md
3
4## Service-specific Rules
5...

Pendekatan inheritance ini menghindari menyalin aturan yang sama berulang kali. Strategi ketiga menggabungkan base bersama dengan override per service, seperti struktur berikut.

1shared/
2  CLAUDE-BASE.md          ← conventions yang berlaku untuk semua service
3order-service/
4  CLAUDE.md               ← import base, tambah order-specific
5  (note: "Lihat juga ../shared/CLAUDE-BASE.md untuk shared conventions")

Untuk Santekno Shop, kita akan menggunakan strategi 1 karena masih monorepo di early stage — kesederhanaannya lebih berharga daripada penghematan duplikasi.

04.9 CLAUDE.md dan GDPR/Security Consideration

CLAUDE.md dibaca dan dikirim ke Anthropic API sebagai bagian dari setiap request. Ini artinya ada hal yang boleh dan tidak boleh ada di dalamnya, seperti kontras berikut.

1# ❌ JANGAN: Taruh ini di CLAUDE.md
2DATABASE_URL=postgres://admin:password123@prod-db:5432/shop
3
4# ✅ BENAR: Referensikan environment variable
5Database config ada di environment variable: DATABASE_URL
6Contoh format: postgres://user:pass@host:port/dbname

Aturan praktisnya sederhana: cantumkan nama environment variable, struktur arsitektur, dan business rules yang tidak sensitif — jangan pernah cantumkan API key, secret, connection string dengan password, atau data pengguna aktual.

04.10 Contoh CLAUDE.md untuk Proyek yang Sudah Ada

Jika proyek sudah berjalan dan belum punya CLAUDE.md, ada pendekatan bertahap yang direkomendasikan, seperti langkah-langkah berikut.

 1Step 1: Extract dari kode existing
 2Prompt ke Claude Code:
 3"Analisis codebase ini dan buat draft CLAUDE.md yang merangkum:
 4 1. Tech stack yang digunakan (dengan versi dari go.mod)
 5 2. Architecture pattern yang dipakai
 6 3. Naming conventions yang konsisten di existing code
 7 4. Error handling pattern
 8 5. Testing approach"
 9
10Step 2: Review dan koreksi
11Review draft yang dihasilkan. Tambahkan rules yang belum tertangkap.
12Koreksi asumsi yang salah.
13
14Step 3: Tambahkan spec rules
15Tambahkan section tentang spec dan SDD workflow.
16
17Step 4: Review dengan tim
18Share ke tim, collect feedback, finalize.

Dengan memulai dari draft yang di-extract AI, kamu tidak menulis dari nol — cukup mengoreksi dan menambahkan, yang jauh lebih cepat daripada menyusun manual dari awal.

04.11 CLAUDE.md sebagai Onboarding Document

Bonus yang tidak terduga: CLAUDE.md yang ditulis dengan baik juga bisa jadi onboarding document yang excellent untuk developer baru.

Developer baru bisa membaca CLAUDE.md untuk:

• Memahami arsitektur project dalam 10 menit
• Tahu conventions apa yang harus diikuti
• Tahu di mana mencari reference code
• Tahu cara kerja spec process

Ini lebih up-to-date dari dokumen onboarding di Confluence yang mungkin sudah outdated. Karena jika kode berubah tapi CLAUDE.md tidak diupdate, AI akan generate kode yang salah — ada insentif nyata untuk menjaganya tetap akurat.

04.12 Versioning CLAUDE.md

CLAUDE.md ada di git — jadi otomatis versioned. Tapi ada best practice tambahan: tandai perubahan signifikan lewat header dan changelog singkat seperti berikut.

 1# CLAUDE.md
 2# Last major update: 2025-07-01 (Add Redis caching rules)
 3# Previous major updates:
 4# - 2025-06-01: Add Kafka event patterns
 5# - 2025-05-01: Initial version
 6
 7## Changelog (singkat)
 8| Tanggal | Perubahan |
 9|---------|-----------|
10| 2025-07-01 | Add Redis caching convention |
11| 2025-06-01 | Add Kafka event pattern |
12| 2025-05-01 | Initial |

Changelog singkat ini memudahkan tim melihat sekilas evolusi aturan proyek. Selain itu, jadwalkan review CLAUDE.md saat sprint planning — minimal sekali sebulan, tanyakan bersama apa yang perlu ditambah, diubah, atau dihapus.

04.13 Anti-Pattern CLAUDE.md

Dari pengalaman, ada beberapa pola CLAUDE.md yang tidak efektif.

Anti-pattern 1: Terlalu panjang (>500 baris) — CLAUDE.md yang terlalu panjang menghabiskan banyak token context window, membuat Claude “fokus” di bagian tertentu dan mengabaikan bagian lain, serta sulit di-maintain. Target ideal: 150-300 baris.

Anti-pattern 2: Terlalu generik — aturan yang tidak actionable membuat AI tidak tahu apa yang dimaksud, seperti contoh berikut.

1# ❌ Terlalu generik
2"Gunakan best practices"
3"Tulis kode yang clean dan maintainable"

Kalimat semacam itu terdengar bagus tapi tidak memberi AI instruksi konkret apa pun. Kontras dengan anti-pattern berikutnya yang justru berbahaya karena saling bertentangan.

1# ❌ Kontradiksi
2"Selalu gunakan context untuk logging"
3(di baris 50)
4"Gunakan log.Printf untuk debug messages"
5(di baris 150)

Aturan yang contradictory membuat Claude bingung memilih mana yang harus diikuti. Anti-pattern 4: Tidak ada contoh kode — rules tanpa contoh lebih sering disalahinterpretasikan, jadi selalu tambahkan snippet kecil untuk rules yang non-trivial.

04.14 Testing Efektivitas CLAUDE.md dengan Prompt Probing

Gunakan serangkaian “probe prompts” untuk verify bahwa CLAUDE.md bekerja sesuai harapan. Kumpulan probe berikut menguji lima aspek berbeda sekaligus.

 1# Probe 1: Architecture compliance
 2"Tulis handler untuk create product yang langsung query ke database"
 3# Expected: Claude menolak dan menjelaskan layer separation
 4
 5# Probe 2: Naming convention
 6"Buat struct untuk input data create order"
 7# Expected: Claude menggunakan PascalCase dan suffix Input
 8
 9# Probe 3: Error handling
10"Bagaimana cara handle error jika order tidak ditemukan?"
11# Expected: Claude menyebut ErrOrderNotFound sebagai sentinel error
12
13# Probe 4: Spec awareness
14"Implementasikan fitur refund order"
15# Expected: Claude menanyakan spec sebelum implementasi
16
17# Probe 5: Price convention
18"Buat field untuk harga produk"
19# Expected: Claude menggunakan int64 dengan nama PriceCents

Jika semua probe menghasilkan response yang sesuai harapan, CLAUDE.md sudah bekerja efektif — jika ada satu yang meleset, itu petunjuk aturan mana yang perlu dipertegas.

04.15 CLAUDE.md untuk Context yang Lebih Kaya

Selain rules dan conventions, CLAUDE.md juga bisa berisi konteks bisnis. Salah satunya adalah domain glossary yang menyeragamkan istilah, seperti berikut.

1## Domain Glossary
2
3- **Order:** Transaksi pembelian yang dibuat customer. Satu order bisa punya multiple items.
4- **Cart:** Kumpulan item yang belum di-checkout. Cart bisa dimodifikasi, order tidak bisa.
5- **SKU (Stock Keeping Unit):** Kode unik untuk setiap variant produk.
6- **Merchant:** Penjual yang listing produk di platform.
7- **Fulfillment:** Proses pengiriman order dari merchant ke customer.

Glossary ini memastikan AI dan tim memakai istilah yang sama, sehingga tidak ada kebingungan antara “cart” dan “order” misalnya. Selain glossary, kamu juga bisa mendokumentasikan pertanyaan arsitektur yang sering muncul seperti berikut.

1## FAQ Arsitektur
2
3**Q: Mengapa tidak pakai GORM?**
4A: Keputusan di ADR-001. pgx/v5 dipilih karena performa yang lebih baik
5   untuk workload kita dan lebih explicit dalam query management.
6
7**Q: Mengapa event-driven untuk notifikasi?**
8A: Decoupling antara Order Service dan Notification Service.
9   Detail di ADR-005.

FAQ semacam ini menjawab pertanyaan “kenapa” sebelum ditanyakan, sehingga AI tidak menyarankan mengganti keputusan arsitektur yang sudah dipertimbangkan matang.

04.16 Integrasi CLAUDE.md dengan Spec Workflow

CLAUDE.md dan spec file bekerja bersama untuk menciptakan context yang comprehensive. Pembagian perannya bisa dilihat pada skema berikut.

1CLAUDE.md:
2- "Bagaimana" → Architecture rules, conventions, patterns
3- "Dengan apa" → Tech stack, libraries, versions
4
5specs/domain/cancel-order.md:
6- "Apa" → User story, AC, EC, NFR
7- "Kenapa" → User story dan business context

Ketika Claude Code punya akses ke keduanya, hasilnya sangat powerful — alurnya kira-kira seperti berikut.

1> Implementasikan cancel order
2
3Claude Code:
41. Baca CLAUDE.md → "tahu arsitektur, conventions, dan rules"
52. Baca specs/order/cancel-order.md → "tahu apa yang harus diimplementasikan"
63. Generate: kode yang sesuai arsitektur DAN sesuai spec

Kombinasi inilah tujuan akhirnya: CLAUDE.md menjaga cara penulisan kode, spec menjaga apa yang ditulis, dan AI menyatukan keduanya menjadi implementasi yang tepat.

04.17 Kesalahan Umum Saat Membuat CLAUDE.md

Kesalahan 1: Menulis CLAUDE.md di akhir project — CLAUDE.md paling efektif jika ditulis di awal project dan di-update secara incremental. Menulis retroaktif lebih sulit dan sering menghasilkan dokumen yang tidak akurat.

Kesalahan 2: Tidak menjelaskan “kenapa” untuk rules yang tidak obvious — aturan tanpa konteks lebih mudah dilanggar. Perhatikan perbedaan antara aturan tanpa dan dengan konteks berikut.

1# ❌ Kurang konteks
2"Gunakan pgx/v5 bukan database/sql"
3
4# ✅ Dengan konteks
5"Gunakan pgx/v5 bukan database/sql — keputusan di ADR-001.
6 Alasan: performa lebih baik, native PostgreSQL types support,
7 dan batch operations yang lebih efficient untuk use case kita."

Versi dengan konteks membantu AI (dan developer) memahami alasan di balik aturan, bukan sekadar mematuhinya secara buta. Kesalahan 3: CLAUDE.md hanya untuk developer baru — CLAUDE.md adalah untuk Claude Code yang bekerja setiap hari, bukan hanya pengantar untuk orang baru.

04.18 Tips & Gotchas

💡 Tip 1: Mulai dengan template, bukan dari scratch — gunakan template di artikel ini sebagai starting point. Lebih baik punya CLAUDE.md yang 70% tepat dari tidak ada sama sekali.

💡 Tip 2: Gunakan bahasa imperatif untuk rules — “HARUS”, “TIDAK BOLEH”, “WAJIB” lebih efektif dari “sebaiknya” atau “lebih baik jika.” Claude merespons lebih baik pada instruksi yang jelas dan tegas.

💡 Tip 3: Sertakan contoh kode untuk pattern yang penting — untuk rules yang critical (error handling, layer separation), selalu sertakan minimal satu contoh kode.

💡 Tip 4: Review CLAUDE.md setiap bulan — jadwalkan review bulanan. Pertanyaan utama: apakah ada pattern baru yang harus ditambahkan? Ada rules yang sudah tidak relevan?

⚠️ Gotcha 1: CLAUDE.md mengkonsumsi context window — semakin panjang CLAUDE.md, semakin sedikit space untuk percakapan dan kode. Prioritaskan informasi yang paling sering diperlukan.

⚠️ Gotcha 2: Claude Code tidak selalu 100% mengikuti CLAUDE.md — terutama untuk rules yang panjang dan kompleks. Selalu review output — CLAUDE.md mengurangi tapi tidak eliminasi kebutuhan review.

⚠️ Gotcha 3: Update CLAUDE.md bersamaan dengan perubahan arsitektur — jika arsitektur berubah tapi CLAUDE.md tidak, AI akan generate kode berdasarkan arsitektur lama. CLAUDE.md yang outdated bisa lebih berbahaya dari tidak ada CLAUDE.md.

⚠️ Gotcha 4: Satu CLAUDE.md untuk satu proyek/service — jangan taruh multiple project’s rules dalam satu file.

04.19 CLAUDE.md vs README.md: Apa Bedanya?

Sering ada kebingungan antara CLAUDE.md dan README.md. Tabel berikut menyandingkan keduanya berdasarkan aspek yang paling membedakan.

Dari tabel ini jelas keduanya dibutuhkan dan saling melengkapi: README.md untuk manusia yang pertama kali melihat proyek, CLAUDE.md untuk AI yang akan bekerja di proyek setiap hari.

04.20 Ringkasan

CLAUDE.md adalah fondasi dari SDD workflow yang efisien. Tanpanya, setiap sesi Claude Code dimulai dari nol — dengan risiko menghasilkan kode yang tidak konsisten dengan arsitektur proyek.

Enam komponen wajib CLAUDE.md: project overview, tech stack dengan versi spesifik, architecture rules yang explicit, naming conventions, spec rules, dan reference code patterns.

CLAUDE.md yang efektif adalah dokumen yang compact (150-300 baris), berisi rules imperatif dengan contoh kode, dan di-update bersamaan dengan perubahan arsitektur.

Jangan taruh credentials di CLAUDE.md — file ini dikirim ke Anthropic API. Gunakan referensi ke environment variable, bukan value-nya.

CLAUDE.md bekerja bersama spec files — bukan pengganti. CLAUDE.md berisi “bagaimana” dan “dengan apa”, spec file berisi “apa” dan “kenapa.”

Di artikel berikutnya, kita masuk ke Part 2 seri ini: membahas secara mendalam anatomi spesifikasi yang baik — user story, acceptance criteria, dan edge case yang benar-benar bisa jadi source of truth.