Crafted vs AI-generated: cara membaca repo Spec-Driven

Pertanyaan umum setelah membuka repositori Spec-Driven: “Bagian mana yang crafted oleh manusia, dan mana yang digenerate AI? Apakah lebih mudah jika git memakai committer berbeda untuk masing-masing?” Insting itu sehat — Anda ingin peta belajar, bukan kotak misteri. Jawabannya biasanya lebih sederhana daripada dua identitas palsu di git.

Pemisahan yang berguna bukan “commit manusia” vs “commit AI”

Sesi coding modern mengaburkan authorship. Manusia bisa menempel setengah fungsi; agent bisa menulis ulang seluruh modul; orang yang sama lalu mengedit tiga baris tangan. Melabeli setiap file 100% crafted atau 100% generated biasanya kepalsuan yang terlalu rapi. Memisahkan committer (misalnya satu identitas Git untuk “crafted” dan satu untuk “AI”) bisa membantu demo, tetapi tidak membuktikan kebenaran — siapa pun bisa ganti identitas — dan melatih kebiasaan salah: membaca orang, bukan membaca kontrak.

Yang benar-benar Anda butuhkan sebagai pembelajar adalah peta intent: apa yang diputuskan dengan sengaja, apa yang bisa digenerate ulang tanpa kehilangan cerita produk, dan ke mana perhatian harus diarahkan saat belajar commit demi commit.

Model mental yang lebih baik: kontrak vs implementasi

• Crafted (biasanya): visi produk, persona, brand, persyaratan SHALL, aturan domain, OpenAPI/kontrak, ADR, skenario acceptance, prompt regenerasi, skrip demo.
• Generated atau regenerable (sering): pohon aplikasi di apps/, boilerplate UI, kode perekat yang hanya ada untuk memenuhi kontrak, client yang digenerate ulang setelah OpenAPI berubah.
• Hybrid (selalu direview): tempat agent mengarang perilaku yang tidak ada di spesifikasi — anggap itu bug atau persyaratan yang hilang, bukan “keajaiban crafted AI”.

Di banyak repo Spec-Driven folder apps/ sengaja dibuat regenerable (kadang bahkan di-gitignore di tree publik). Itu bukan kemalasan. Itu mengajarkan: jika kontraknya bagus, agent lain bisa membangun ulang implementasi. Jika Anda hanya mempelajari UI yang digenerate, Anda mempelajari cat kemarin, bukan denah bangunan.

Cara mengenali “crafted” tanpa bertanya ke penulis

1. Mulai di specs/ (atau docs/contracts/). Cari bahasa SHALL / MUST, non-goals, dan kriteria acceptance. Manusia berkeringat pada kata-kata itu.
2. Baca ADR. Architecture Decision Records menjelaskan mengapa — agent jarang menulis trade-off yang jujur kecuali manusia memintanya.
3. Temukan prompt regenerasi (sering di specs/regeneration/). File itu adalah “resep bangun ulang”. Jika implementasi hilang, inilah yang dijalankan agent lain.
4. Baru kemudian buka apps/. Tanya: perilaku mana yang diwajibkan oleh ID persyaratan bernama? Selain itu dicurigai atau sekadar dekoratif.
5. Gunakan tes dan Gherkin sebagai jembatan. Feature file yang bagus adalah intent berbentuk manusia; tes yang lulus adalah bukti implementasi saat ini masih cocok.

Tentang committer git yang terpisah

Memakai dua identitas committer (Human vs Agent) bisa jadi teater mengajar di workshop: “commit hijau gelombang agent; commit biru edit kontrak manusia.” Jika tim ingin konvensi itu, dokumentasikan di CONTRIBUTING.md dan konsisten. Itu gula opsional — bukan pengganti folder dan ID persyaratan.

• Kelebihan: sejarah visual di git log / demo blame; memaksa operator berhenti sejenak sebelum commit output agent.
• Kekurangan: mudah dipalsukan; berantakan dengan amend/rebase; membingungkan norma open-source (satu orang, satu identitas); tidak tahan ketika apps/ digenerate ulang sebagai satu gelombang.
• Default yang lebih baik: satu identitas author, pesan commit yang jelas (“specs: add SD-007 instant results”, “regen: wave 1 apps from REGENERATE.md”), dan review berbasis path (specs dulu).

Cara belajar commit demi commit (tanpa tenggelam)

1. 01Clone repo dan abaikan apps/ selama sejam pertama.
2. 02Baca visi produk → persyaratan utama → satu ADR → satu fitur acceptance.
3. 03Skim prompt regenerasi untuk melihat gelombang build yang dimaksud.
4. 04Baru kemudian jalanin sejarah git yang difilter ke specs/ (log terbatas path).
5. 05Saat membuka implementasi, pilih satu ID persyaratan dan kejar ke kode serta tes.

# Study contract history first (path-limited)
git log --oneline -- specs/

# See what changed in contracts between two points
git log -p -- specs/requirements/ specs/domain/

# When ready for implementation, chase one ID (example)
rg "SD-007" -n specs apps 2>/dev/null || true

Dari vibe coding ke belajar Spec-Driven

Vibe coding bagus untuk merasakan kemajuan. Spec-Driven Development bagus untuk menjaga kemajuan. Jika Anda berpindah dari vibes ke SDD, jangan mulai dengan membongkar setiap layar yang digenerate. Mulai dengan menulis ulang satu perilaku sebagai SHALL + skenario acceptance dengan kata-kata Anda sendiri. Lalu minta agent mengimplementasi hanya itu. Bandingkan. Loop tunggal itu mengajar lebih banyak daripada seratus commit anonim.

Bacaan terkait

• Spec-Driven Development — https://suherman.net/id/articles/spec-driven-development
• Spesifikasi SurveyDesk dengan Agent On Rails — https://suherman.net/id/articles/agent-on-rails-surveydesk-specs
• Contoh produk Spec-Driven: https://github.com/iman-suherman/survey-desk

Intinya: jangan bertanya “siapa yang mengetik file ini?” Tanya “ini kontrak atau build?” Pelajari kontraknya. Regenerasi build-nya. Review apa pun yang mengaku keduanya.