AIDive

Paket video

Mengatur spec dan plan AI di Git: lima aturan, drift gate, sumber dan checklist

11 menit baca

TL;DR

  • Commit spec dan plan yang ditulis AI. Semua tool sudah melakukannya secara default; pertanyaan yang tersisa adalah tata kelolanya.
  • Beri setiap squad satu folder dengan satu baris CODEOWNERS, sehingga perubahan spec meminta review dari pemilik kodenya.
  • Pasang header gaya ADR di setiap spec bersama: status, superseded-by, owner, path yang disentuh, tanggal review. Jangan pernah menulis ulang spec yang sudah accepted menjadi keputusan baru.
  • Jalankan drift gate di CI: untuk setiap spec accepted, gagalkan build bila ada path yang disebutnya tapi sudah tidak ada.
  • Arahkan ulang path output dengan satu baris imperatif tebal di CLAUDE.md, simpan plan pribadi di CLAUDE.local.md dan .git/info/exclude, dan tulis di branch, jangan di main.
  • Buat spec hanya untuk pekerjaan yang melintasi batas squad atau akan dibaca lagi dalam 90 hari. Proses spec-driven memakan waktu sekitar dua kali lipat dan token tiga kali lipat.

Apa kata sumber

Default-nya: semua orang commit

Skill writing-plans dari Superpowers menyimpan plan ke docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, dengan satu baris di bawahnya yang menyatakan bahwa preferensi pengguna soal lokasi plan menimpa default ini s1. Skill brainstorming menulis desain yang sudah divalidasi ke docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md dan diakhiri dengan "Commit the design document to git" s2. Spec Kit menyusun specs/[branch-name]/ berisi spec.md, plan.md dan tasks.md, bernomor 001, 002, ditambah constitution di memory/constitution.md s6. Kiro menyimpan .kiro/specs/ dengan satu folder per fitur dan mengajak tim untuk "collaborate with team members on different features simultaneously" s8. Playbook Anthropic tegas: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md", dan "When implementation departs from the plan, update plan.md in the same commit" s5.

Tak satu pun dokumen ini menyebut siapa pemilik spec yang sudah di-commit atau kapan spec itu tidak lagi benar. Tiga kegagalan yang terdokumentasi muncul di celah itu.

Kegagalan 1: kebocoran ke publik

Issue 1690, dibuka 2026-06-05, melaporkan bahwa lokasi default docs/superpowers/ bisa membocorkan plan internal ke dokumentasi publik lewat Sphinx dan Read the Docs s15. Proyek yang terkena adalah okama, library Python dengan 273 star. Commit perbaikannya menambahkan kembali 5 plan dan 3 spec, menghapus satu baris .gitignore, dan berbunyi "track superpowers plans/specs in git, excluded from the Sphinx build" s21. Baris 84 docs/conf.py sekarang berisi exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Saat ini foldernya berisi 8 plan dan 6 spec s15. Tim itu mempertahankan praktiknya dan memperbaiki build-nya.

Kegagalan 2: plan di main

Issue 1246, dibuka 2026-04-22 dan masih terbuka, menanyakan kenapa plan di-commit sebelum ada development branch. Satu pengguna melaporkan "I'm getting 10 to 15 commits"; yang lain: "Yes please, no plans and specs on main branch!" s16. Plugin tidak memaksakan aturan branch; checklist di bawah yang melakukannya.

Kegagalan 3: override yang dilewati model

Issue 337 ditutup pada 2026-03-10 dengan catatan maintainer bahwa sejak v5.0 plugin memprioritaskan CLAUDE.md proyek Anda di atas defaultnya sendiri, contoh barisnya: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. Issue 939, pada v5.0.6, menunjukkan batasnya: tabel "Output Paths" di CLAUDE.md diabaikan dan spec tetap mendarat di docs/superpowers/specs/. Solusi yang berhasil adalah satu baris imperatif tebal di bawah tabel: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Pull request 1020, yang mengubah urutan instruksi, ditutup tanpa di-merge s19. Override ini adalah prompt, bukan setting: cek ulang setiap kali ada rilis plugin baru. Untuk file scratch milik plugin sendiri, issue 1780 ditutup oleh v6.0.3 dengan folder .superpowers/sdd/ yang mengabaikan dirinya sendiri, dengan menaruh .gitignore berisi * s20.

Pribadi versus bersama

Claude Code mendokumentasikan pemisahannya: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. File CLAUDE.md per direktori dimuat sesuai kebutuhan, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", dan setting claudeMdExcludes menyembunyikan file tim lain di monorepo s4. Git menyediakan tiga lapisan ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude dan .gitignore s24; lapisan tengah menyembunyikan folder plan pribadi tanpa menyentuh file bersama. CODEOWNERS menangani sisi kepemilikan: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Siklus hidup, seperti ADR

Post Michael Nygard tahun 2011 adalah templatenya: sebuah keputusan "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", dan "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks membagi penggunaan spec menjadi spec-first (ditulis sekali untuk satu tugas), spec-anchored (dirawat agar fitur berkembang) dan spec-as-source (hanya spec yang diedit), dan penulisnya menambahkan: "I'd rather review code than all these markdown files" s10. Superpowers menulis file spec-first dan menyimpannya selamanya: drift sejak awal.

Drift dan gate-nya

Paper arXiv menamai masalahnya "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" dan mengusulkan "a drift gate that makes spec-code divergence a blocking merge condition" s11. Panduan Spec Kit sendiri memperingatkan: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry menyampaikan argumen tata kelola ini dengan lugas: "forty-one specs and nine agent files aren't a tidiness problem", melainkan "forty-one unversioned behavior inputs and nine competing standing policies", dan drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". Post yang sama menyarankan sekitar 300 baris per spec dan anggaran 150 sampai 200 instruksi tetap s13. Seorang praktisi menggambarkan versi manualnya: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Berapa biayanya

Eksperimen Hasil Sumber
Spec Kit untuk fitur yang menampilkan tanggal hari ini 8 file dan 1,300 baris teks s14
Bake-off OpenSpec, kebutuhan sama, tool spec vs Claude Code biasa OpenSpec menemukan 3 gap tambahan; kode 50% lebih banyak dengan cyclomatic complexity 50% lebih tinggi; dua kali lebih lama dan tiga kali lebih mahal s12
Tim yang menjalankan spec-driven development selama berbulan-bulan "two to three times as many tokens and take about twice as long"; tidak ada bukti kodenya membaik s25

Bake-off itu hanya satu eksperimen dan penulisnya mengakuinya, tetapi arahnya sama di ketiganya. Jadi: buat spec untuk jalur arsitektural, jaga jalur yang terbatas tetap terbatas, dan ikuti dua baris yang diulang para praktisi, "don t spec too big / read the generated specs" s26.

Kerjakan hari Senin

  • Buat docs/specs/<squad>/ per squad dan tambahkan satu baris CODEOWNERS per folder yang menunjuk ke reviewer squad itu.
  • Tambahkan satu baris imperatif tebal ke CLAUDE.md proyek: plan dan spec MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Jalankan satu brainstorm dan cek di mana filenya mendarat.
  • Pindahkan plan pribadi ke folder yang terdaftar di .git/info/exclude dan simpan preferensi per developer di CLAUDE.local.md, yang juga di-ignore.
  • Pasang header di setiap spec bersama: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • Tulis drift gate: untuk setiap spec dengan status: accepted, ekstrak path yang disebutnya dan gagalkan pull request bila ada yang hilang. Sekitar lima belas baris shell atau Python.
  • Tambahkan aturan branch: tidak ada commit spec atau plan yang masuk ke main di luar pull request.
  • Jika repo menerbitkan dokumentasi dengan Sphinx atau sejenisnya, tambahkan folder specs ke exclude_patterns hari ini.
  • Tetapkan anggaran ukuran: spec berada di sekitar 300 baris, dan hanya pekerjaan yang melintasi batas squad atau akan dibaca lagi dalam 90 hari yang mendapat spec.

Lanjutkan membaca

  • Baca tiga kategori penggunaan spec (spec-first, spec-anchored, spec-as-source) sebelum memilih skema header; siklus hidup hanya penting untuk file spec-anchored s10.
  • Paper arXiv melangkah lebih jauh dari pengecekan path menuju arsitektur dengan drift enforcement penuh; berguna begitu gate lima belas baris terasa terlalu kasar s11.
  • Panduan Spec Kit menyebut tiga alur evolusi (Flow-Forward, Living Spec, Flow-Back) yang cocok dengan aturan same-commit s7.
  • Playbook menyarankan hook untuk memaksa sinkronisasi plan dan diff; thread Reddit tentangnya punya 43 poin dan 27 komentar laporan lapangan s5, s27.
  • Argumen TrueFoundry bahwa perubahan spec adalah perubahan kebijakan, sehingga harus berada di balik eval gate dengan metadata run, adalah langkah berikutnya setelah pengecekan path di CI s13.
  • Pantau dua issue yang masih terbuka, 1246 (plan di main) dan 939 (override yang diabaikan); begitu salah satunya ditutup, satu aturan di pack ini menjadi default plugin s16, s18.
  • Tulisan lengkap Marmelab menjelaskan kenapa 1,300 baris itu muncul dan di mana Spec Kit memang berguna s14.

Sumber

FAQ

Apakah saya perlu kelima aturan sejak hari pertama?

Tidak. Redirect di CLAUDE.md dan pengecualian Sphinx hanya butuh sepuluh menit. Tambahkan CODEOWNERS dan header saat sebuah spec pertama kali melintasi squad, dan drift gate setelah spec accepted berumur satu sprint.

Apa yang tidak tertangkap drift gate?

Perubahan perilaku. Gate ini hanya memeriksa bahwa path yang disebut masih ada, jadi kondisi yang terbalik akan lolos. Padukan dengan aturan same-commit dan review.

Kenapa tidak langsung gitignore foldernya saja?

Karena agent yang membaca spec itu nanti membutuhkannya, dan audit trail hanya bekerja bila bagian tengahnya berversi. Tim okama sempat mencoba gitignore lalu kembali ke commit dengan pengecualian di build.