Mendesain Init Rules Skill: Layered Pack dan Idempotensi

Saya lagi nulis spec di specs/2026-09-27-init-rules-design.md, 199 baris, buat fitur onboarding repo pakai aturan AI. Skill ini bakal jadi pendamping plane init, setor lapisan aturan ke repo baru dalam satu jalan. Awalnya saya punya asumsi yang keliru. Saya kira satu file CLAUDE.md raksasa di root udah cukup buat menampung semua instruksi, dan menjalankan ulang generator di repo yang udah hidup itu aman-aman aja.

Ternyata asumsi itu bikin repot banget.

Jebakan Satu File Raksasa

Saat sesi dimulai, CLAUDE.md di root memang dimuat sebagai instruksi proyek yang persisten [1]. Tapi kalau isinya jadi campur aduk antara fakta statis dan prosedur multi-langkah yang panjang, file ini jadi berat dan sulit dikelola. Padahal, prosedur yang berulang dan udah terlalu kompleks buat CLAUDE.md seharusnya dipisah ke dalam skills atau aturan yang terikat pada path tertentu [2].

Di sinilah saya sadar kalau pendekatan satu file itu nggak scalable. Saya butuh cara agar repo cuma menarik aturan yang benar-benar dibutuhin, bukan menelan semua dokumentasi sekaligus. Output generator yang menumpuk semua aturan di satu tempat bakal jadi file yang susah di-maintain dan rawan konflik.

Memisahkan Fakta dari Prosedur

Jalan keluarnya: pisahin yang tegas. CLAUDE.md di root saya ubah fungsinya jadi semacam indeks atau penunjuk arah. Aturan yang spesifik tinggal di path-nya masing-masing. Kenapa ini masuk akal? Karena file CLAUDE.md di subdirektori cuma dimuat on-demand saat AI membaca file di lokasi tersebut [1].

Dari sini lahir konsep init rules skill layered pack. Strukturnya saya bagi jadi tiga lapisan. Pertama, aturan proses universal (vertical-slice, testing, debugging). Kedua, paket per-stack untuk Go, Next.js, atau MySQL. Ketiga, scaffold kosong untuk kebutuhan deploy atau batasan proyek. Semua ini dibangun harness-first: SKILL.md plus scripts/selfcheck.sh ditulis duluan, baru isi pack-nya, selfcheck itu assert-based, cek frontmatter rule file, placeholder closure, manifest pack, dan kebocoran data seed.

Skill itu sendiri cuma dimuat saat digunakan [2]. Ini mengikuti standar terbuka Agent Skills, di mana cuma enam field frontmatter yang portabel di luar ekosistem tertentu [4]. Jadi, repo target nggak terbebani oleh instruksi yang nggak relevan dengan stack yang dipakai. Saya sengaja membatasi konten aturan hanya dalam bahasa Inggris agar konsisten dan mudah diproses oleh model AI mana pun.

Idempotensi ala Konvensi Go

Masalah kedua yang saya temuin adalah keamanan menjalankan ulang generator. Saya sempat kena masalah pas nyoba nge-run generator di repo yang udah ada fitur baru. Tanpa mekanisme yang jelas, generator bakal menimpa perubahan lokal yang nggak tercatat di template.

Saya akhirnya mengadopsi pola kepemilikan artifak yang ketat. Repo generator, my-plan, memiliki semua artifak aturan. Sementara repo konsumen (ekabo) hanya bertindak sebagai read-only seed untuk bagian yang di-generate. Ini sangat mirip dengan konvensi kode yang di-generate di bahasa Go, di mana baris ^// Code generated .* DO NOT EDIT.$ adalah hukum yang nggak bisa diganggu gugat [6].

Dengan pola ini, menjalankan ulang proses inisialisasi jadi idempoten. Perubahan template ditangani dengan smart-merge yang menghormati evolusi proyek, mirip cara Copier mempertahankan jawaban pengguna lewat file .copier-answers.yml [7]. Kalau ada konflik saat update, itu tandanya ada perubahan manual yang perlu di-review, bukan sekadar ditimpa otomatis.

Desain ini bukan soal bikin aturan paling lengkap, tapi aturan yang paling gampang dikelola. Membiarkan repo konsumen tetap bersih dan hanya menarik apa yang diperlukan ternyata jauh lebih sustainable daripada memaksakan satu file master yang coba mengakomodasi semua kemungkinan.

Sumber:

• [1] How Claude remembers your project (Claude Code docs)
• [2] Extend Claude with skills (Anthropic docs)
• [4] Agent Skills Overview (agentskills.io)
• [6] golang/go issue 13560: standard way to recognize machine-generated files
• [7] Updating a project (Copier docs)