Commit Spec Superpowers-mu, Tapi Atur Seperti ADR

Superpowers adalah plugin Claude Code (286.000 star di GitHub) yang skill-nya menulis spec dan implementation plan sebagai file markdown lalu meng-commit-nya ke repository. Secara default, semua file itu mendarat di satu folder yang sama, docs/superpowers/. Pada bulan Juni, maintainer Okama, sebuah library finance Python, menemukan bahwa delapan implementation plan yang ditulis agent di sana, di-commit persis seperti yang dimaksudkan plugin, ternyata sudah dirender jadi halaman web publik di Read the Docs. Mereka baru menyadarinya setelah rilis.

Sekarang bayangkan skalanya lebih besar: tim front-end dengan sepuluh developer, empat squad, satu repository, dan setiap developer menghasilkan file-file ini. Tiga pertanyaan mendarat di meja lead. Apa sebenarnya yang kita version? Apakah drift jadi masalah kalau sebuah spec menyebut path yang sudah dihapus dua sprint lalu? Dan siapa yang mengatur folder ini? Kebocoran Okama bukan disebabkan oleh commit. Ia disebabkan oleh commit tanpa aturan. Artikel ini memberimu lima aturan.

Superpowers tidak pernah bertanya apakah harus commit. Baris 18 dari planning skill-nya menyimpan setiap plan di bawah docs/superpowers/plans/, bertanggal, satu file per feature. Brainstorming skill menulis design document dan meng-commit-nya di langkah yang sama, sebelum kamu sempat melihat plan itu.

Ini bukan keunikan Superpowers. Setiap tool spec-driven besar membuat pilihan yang sama:

Tool	Publisher	Tempat spec disimpan
Superpowers (286.000 star)	obra	docs/superpowers/, satu folder untuk semuanya
Spec Kit (136.000 star)	GitHub	satu folder bernomor per feature, di branch feature itu
Kiro	Amazon	.kiro/specs/, satu folder per feature
AI-native SDLC playbook	Anthropic	satu artifact yang di-commit per stage: intent, spec, plan, diff, review findings, incident record

Kiro menjual folder per-feature sebagai cara agar rekan satu tim bisa berkolaborasi di feature yang berbeda-beda sekaligus. Playbook Anthropic, dirilis Agustus, melangkah lebih jauh: setiap stage meng-commit sebuah artifact yang bisa dibaca stage berikutnya. Jadi pertanyaannya tidak pernah soal apakah harus commit, dan ke mana sudah dijawab oleh setiap tool. Siapa pemilik file itu, dan kapan ia mati, belum. Itulah gap yang ditutup lima aturan ini.

Plan yang sudah di-commit bisa gagal dengan tiga cara berbeda.

Kegagalan 1: docs generator. Sebuah docs build yang merender setiap file markdown di bawah docs/, entah tercantum di table of contents atau tidak, ikut mengirim folder plans bersama manual. Itulah yang terjadi pada Okama.

Kegagalan 2: branch. Superpowers issue 1246 melaporkan bahwa brainstorm meng-commit plan langsung ke main. Satu user menghitung 10 sampai 15 commit per session, satu commit baru setiap beberapa perubahan. Permintaan thread itu cukup satu baris: jangan ada plan dan spec di branch main.

Kegagalan 3: drift. Spec drift adalah kegagalan yang diam-diam: code berkembang, spec-nya tidak. Birgitta Böckeler dari Thoughtworks menyebut tiga level spec-driven development:

Level	Arti
Spec-first	Ditulis, dipakai sekali
Spec-anchored	Disimpan dan dirawat selama umur feature itu
Spec-as-source	Manusia hanya pernah mengedit spec

Superpowers menulis dokumen spec-first dan menyimpannya selamanya. Secara default kamu mendapat penyimpanan spec-anchored dengan perawatan first-draft: tidak ada yang memperbarui file itu, dan agent membacanya kuartal berikutnya sebagai kebenaran. TrueFoundry mengatakannya dengan jelas: drift tidak terhindarkan dalam praktik spec-first dan hanya terkelola dalam praktik spec-anchored, asalkan divergensinya bisa terdeteksi.

Repository yang menyimpan 41 spec dan 9 agent file bukan punya masalah kerapian. Ia punya 41 behavior input yang tidak di-version. Reaksi Böckeler sendiri: ia lebih suka membaca code daripada semua file markdown ini. Plan yang tidak pernah dimuat lagi hanyalah sampah. Plan yang dimuat agent adalah instruksi, dan instruksi yang basi adalah instruksi yang salah.

Aturan 1: folder itu punya owner, dan owner-nya adalah squad, bukan plugin. Sejak versi 5, Superpowers menghormati instruksi di CLAUDE.md proyekmu di atas default-nya sendiri. Sebutkan ke mana plan harus pergi, dan ia akan pergi ke sana.

Namun tabel path saja tidak cukup. Di issue 939, seorang user menulis tabel output path dan model tetap mengikuti path konkret di dalam skill lalu melewati tabel itu. Catatan override dari skill sendiri hanya berupa keterangan dalam kurung. Satu baris tegas dan imperatif memperbaikinya pada percobaan pertama: spec harus disimpan di sini, bukan di sana, dengan default lama disebut sebagai hal yang harus dihindari.

Layoutnya adalah satu folder per squad (checkout, search, accounts, design-system), masing-masing dengan spec dan plan-nya sendiri. Dalam monorepo, letakkan baris itu di CLAUDE.md milik package itu sendiri. Claude Code memuat file sebuah subdirectory saat sedang membaca di sana, dan dokumentasinya menyebut bahwa owner tiap directory biasanya merawat file-nya. Engineer yang tidak pernah menginstal plugin tidak terpengaruh: baris itu hanya aktif saat sebuah skill bertanya ke mana harus menyimpan.

Lalu biarkan platform menegakkan ownership itu. Satu baris CODEOWNERS per folder squad, dan setiap review spec mendarat pada orang-orang yang akan hidup dengannya. Satu catatan: override ini adalah prompt, bukan setting. Cek spec pertama setelah setiap rilis plugin.

Aturan 2: bukan setiap plan adalah artifact tim. Orang pertama yang meminta lokasi yang bisa dikonfigurasi (issue 337) mengatakannya paling pas: file plan bisa jadi dokumen kerja pribadi, bukan artifact proyek.

Sisi pribadi sudah punya file yang dibuat khusus untuknya. CLAUDE.local.md duduk di sebelah file bersama, dimuat setelahnya, dan dokumentasinya menyuruhmu meng-git-ignore file itu sendiri. Redirect-mu ke folder pribadi tinggal di sana dan tidak ada orang lain yang melihatnya. Untuk folder itu sendiri, Git punya ignore file yang tidak pernah menyentuh tree bersama: .git/info/exclude bersifat per clone, tidak pernah di-commit, dan tidak butuh pull request. Plugin ini sendiri sudah melakukannya untuk scratch space-nya: sejak versi 6.0.3, working directory-nya menjatuhkan .gitignore berisi * di dalam dirinya sendiri, jadi ia mengabaikan dirinya sendiri tanpa menyentuh satu pun tracked file.

Sisi bersama adalah apa pun yang lolos review gate yang sudah dijalankan brainstorm: spec ditulis, review diminta, disetujui orang kedua. Setelah disetujui, ia pindah ke folder squad. Kalau tidak disetujui, ia tetap lokal. Keduanya ditulis di sebuah branch, tidak pernah di main. Dua baris di CLAUDE.md bersama sudah cukup: perlakukan spec dan plan sebagai awal dari sebuah feature, dan buat worktree sebelum menulisnya.

Satu batasan: plan yang di-git-ignore tidak ikut berpindah. Maintainer Okama sempat mencoba meng-ignore folder itu lebih dulu lalu membatalkannya, karena plan berhenti tersinkron antar mesin dan antar agent. Pribadi berarti benar-benar pribadi.

Aturan 3: sebuah spec punya status, dan spec yang sudah mati menyatakannya. Idenya sudah berumur 15 tahun. Michael Nygard, pada 2011, mengusulkan menyimpan architecture decision record (ADR) di repository, satu file bernomor untuk masing-masing. Sebuah keputusan diusulkan (proposed), lalu diterima (accepted). Ketika record berikutnya mengubahnya, record lama ditandai deprecated atau superseded dengan referensi ke penggantinya. Jika sebuah keputusan dibalik, record lama tetap disimpan tapi ditandai superseded.

Diterapkan pada spec, setiap spec bersama dibuka dengan header lima baris yang sudah dibaca agent:

Field	Kegunaan
status	proposed, accepted, superseded
superseded-by	spec pengganti
owner	squad
touches	path yang diklaim spec ini
review date	kapan terakhir dicek

Jangan pernah mengedit spec yang sudah accepted menjadi keputusan lain. Tulis spec berikutnya, arahkan balik ke spec lama, dan histori tetap jujur. Satu pengecualian, disebutkan dalam playbook Anthropic: ketika implementasi menyimpang dari plan, perbarui plan itu di commit yang sama. Plan ikut berjalan bersama diff yang membuatnya menyimpang, dan sebuah hook bisa menegakkan ini.

Spec Kit menyebut tiga cara sebuah spec bisa hidup. Flow-forward: folder baru per feature, folder lama disimpan sebagai histori. Living spec: spec adalah kontrak dan sisanya di-regenerate. Flow-back: build yang membentuk ulang spec. Aturan mereka: jangan biarkan sebuah perubahan di tasks atau code kalau spec masih mengatakan hal yang berbeda. Itu adalah pilihan sadar untuk spec-anchored.

Batasannya: status adalah metadata yang diset manusia. Agent tidak akan menandai spec-nya sendiri superseded kecuali CLAUDE.md-mu menyuruhnya, dan bahkan begitu, review tetap harus menyadarinya.

Aturan 4: spec yang berbohong soal tree gagal build. Paper yang menamai masalah ini, dipublikasikan Juni, menyebutnya silent spec-code drift: code berkembang, spesifikasinya tidak, dan divergensinya tetap tak terlihat sampai mahal untuk diperbaiki. Jawabannya adalah drift gate, sebuah blocking merge condition.

Cek-nya lebih sederhana dari kedengarannya. Untuk setiap spec dengan header berstatus accepted, ambil path yang disebutkannya, di dalam backtick atau di baris touches, lalu uji apakah masing-masing path itu masih ada. Path hilang, build gagal, dengan nama spec itu tercatat di log. File superseded dan proposed dilewati: hanya spec accepted yang mengklaim sesuatu tentang tree, jadi hanya spec accepted yang dicek. TrueFoundry membingkainya sebagai scheduled diff, bukan post-incident archaeology: spec adalah scaffold, dan perubahan spec adalah perubahan policy.

Orang-orang sudah menjalankan versi manualnya. Satu commenter meminta Claude membandingkan file spec dengan codebase dan membuat ticket untuk apa yang hilang. Script ini melakukan itu di setiap pull request, secara gratis.

Guard kedua adalah yang dilakukan Okama: kecualikan folder itu dari docs build. Satu baris di konfigurasi Sphinx membuat file-file itu tetap ada di Git tapi tidak masuk ke HTML.

Batasannya: pengecekan path hanya menangkap file yang terhapus, bukan behavior yang berubah. Sebuah spec bisa menyebut semua file yang masih ada dan tetap mendeskripsikan API yang sudah hilang. Untuk itulah review dan aturan same-commit ada.

Aturan 5: sebagian besar kerjaan tidak pantas mendapat spec. Bukti soal overhead spec-driven konsisten:

Eksperimen	Hasil
Marmelab, Spec Kit pada feature yang menampilkan tanggal saat ini	8 file, 1.300 baris teks spesifikasi
Bake-off OpenSpec, requirement sama dengan spec tool vs Claude Code sendirian	50% lebih banyak code, 50% lebih banyak cyclomatic complexity, dua kali lebih lama, tiga kali lebih mahal
Tim yang menjalankan spec-driven development selama berbulan-bulan	2 sampai 3 kali lebih banyak token, sekitar dua kali lebih lama, coordination cost besar untuk perubahan yang sebenarnya tidak butuh koordinasi; tidak ada bukti code-nya jadi lebih baik

Bake-off ini satu eksperimen, bukan benchmark, dan penulisnya sendiri mengatakan itu. Tapi arahnya konsisten. Jadi aturannya: tulis spec ketika kerjaan melintasi batas squad atau akan dibaca lagi dalam 90 hari. Selain itu, cukup sebuah prompt.

Superpowers sendiri sudah memilah setiap request ke tiga jalur: spike, bounded, architectural. Hanya jalur architectural yang menulis spec. Jaga jalur bounded tetap bounded, dan jaga spec mendekati 300 baris. Praktisi menambahkan dua baris: jangan bikin spec terlalu besar, dan baca spec yang dihasilkan.

Batasan ini berlaku dua arah. Bake-off yang sama menemukan tiga gap yang terlewat oleh run biasa. Spec membeli coverage, bukan kecepatan. Bayar untuk itu di tempat coverage benar-benar penting.

Kembali ke tiga pertanyaan lead. Apa yang kita version: spec dan plan yang sudah disetujui, di sebuah branch, di folder squad-nya. Drift: header status dan gate CI. Governance: owner dan size rule.

Lima aturan, dan tidak satu pun dari mereka ditegakkan oleh sebuah tool hari ini. Issue override-nya masih terbuka. Issue main-branch-nya masih terbuka. Pull request yang menata ulang instruksinya ditutup tanpa di-merge. Tim yang pernah kena masalah tetap mempertahankan praktiknya: 8 plan dan 6 spec, di-commit, dikecualikan dari docs build.

Keberatan Böckeler tetap berdiri. Dengan header status dan size budget, kamu hanya membaca spec yang accepted, dan jumlahnya lebih sedikit. Yang kamu dapat sebagai balasannya adalah yang disebut playbook Anthropic sebagai audit trail: siapa meminta apa, apa yang dihasilkan agent, dan siapa yang menyetujuinya.

Ini soal proses, bukan tooling: satu file CLAUDE.md, satu file CODEOWNERS, satu header, dan satu script lima belas baris. Dan kalau tim tidak mau meninjau permintaan CODEOWNERS, mereka juga tidak akan meninjau spec. Dalam kasus itu, .gitignore adalah pilihan yang jujur.