SpecGuard - Plugin CLI/Codex untuk memeriksa spesifikasi sebelum AI menulis kode

Halo. Saya sedang membuat alat open source bernama SpecGuard.

Saat menggunakan alat AI coding seperti Codex atau Claude Code, kecepatan implementasi memang jelas menjadi lebih cepat. Namun setelah beberapa kali memakainya berulang, masalah yang paling sering saya hadapi dalam praktik ternyata bukan “AI tidak bisa menulis kode”, melainkan lebih dekat ke “spesifikasi yang diserahkan ke AI itu sendiri tidak lengkap”.

Jika ada cacat pada spesifikasi, AI akan menebak celah-celah itu dengan caranya sendiri lalu mengimplementasikannya. Awalnya terlihat meyakinkan, tetapi seiring pengembangan berjalan, masalah berikut makin membesar.

• Kualitas dan struktur kode makin lama makin rusak.
• Spesifikasi dan kode makin lama makin tidak selaras.
• Pada akhirnya jadi sulit membedakan apakah kodenya yang salah, spesifikasinya yang sudah usang, atau memang kebutuhan awalnya yang ambigu.

Karena itu saya merasa code review setelah implementasi saja tidak cukup. Sebelum spesifikasi yang cacat diteruskan begitu saja ke agen implementasi, dibutuhkan tahap untuk lebih dulu menyingkap celah pada spesifikasi itu sendiri.

SpecGuard adalah plugin CLI/Codex yang dibuat untuk mengurangi masalah ini. Ini bukan alat yang memeriksa hasil setelah kode dihasilkan, melainkan alat yang memeriksa spesifikasi terlebih dahulu sebelum implementasi diserahkan ke AI.

Alur dasar yang saya maksud adalah seperti ini.

1. Manusia menulis spesifikasi produk.
2. Periksa spesifikasi dengan SpecGuard.
3. Jika NOT_READY, perkuat spesifikasinya.
4. Jika sudah READY, serahkan ke agen implementasi seperti Codex/Claude Code.

SpecGuard terutama mencari jenis celah seperti berikut.

• Batas autentikasi/otorisasi tidak jelas
• Cakupan kepemilikan tenant/user tidak dicantumkan
• Tidak ada penanganan untuk idempotency, replay, race condition
• Aturan kedaluwarsa/pencabutan/transisi status ambigu
• Tidak ada kebijakan retry untuk efek samping eksternal, webhook, background job
• Kebutuhan yang hanya mengandalkan validasi klien

Secara garis besar ada tiga jenis hasil.

• READY: bisa diteruskan ke agen implementasi
• READY_WITH_WARNINGS: bisa diteruskan, tetapi ada hal yang perlu diperhatikan
• NOT_READY: ada masalah Critical/Major sehingga spesifikasi perlu diperkuat

Jalur default adalah pemeriksaan heuristik --no-llm. Alasannya, di CI atau PR Review, hasil yang cepat dan dapat direproduksi itu penting. Review detail berbasis OpenAI Platform atau Codex juga bisa ditambahkan, tetapi saat ini saya menempatkannya sebagai jalur pendukung opsional saat ingin melakukan pemeriksaan yang lebih mendalam.

Yang ditambahkan di v0.4.0

Di v0.4.0 kali ini saya menambahkan MVP plugin aplikasi Codex.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Di aplikasi Codex, jika memilih sumber SpecGuard Plugins dan memasang plugin SpecGuard, Anda dapat meminta SpecGuard dijalankan dari dalam Codex. Misalnya setelah membuat contoh spesifikasi

specguard example copy specs/your-feature-name --force  

Anda bisa membuka folder tersebut di Codex lalu meminta seperti ini.

1. @SpecGuard tolong jalankan SpecGuard untuk specs/your-feature-name.  
2. @SpecGuard jalankan SpecGuard untuk paket spesifikasi specs/your-feature-name, lalu ringkas status READY/NOT_READY dan finding utamanya.  
3. @SpecGuard tolong jalankan SpecGuard untuk specs/your-feature-name. Gunakan pemeriksaan heuristik dasar, lalu ringkas status hasilnya dan langkah berikutnya yang harus dilakukan.  

Plugin ini tidak mengimplementasikan ulang engine SpecGuard. Plugin hanya memanggil CLI specguard yang sudah ada, lalu membaca hasil yang dihasilkan untuk merangkum status saat ini dan tindakan berikutnya.

Jika SpecGuard menghasilkan status READY, alur yang dituju adalah membuat dokumen handoff yang bisa diteruskan ke agen implementasi, lalu setelah itu Codex memulai implementasi.

PR Review juga didukung

Workflow SpecGuard PR Review berbasis GitHub Actions juga tersedia.

Alurnya adalah menjalankan SpecGuard Review saat paket spesifikasi berubah di PR, lalu meninggalkan hasilnya di PR. Fitur ini dijalankan dengan memanggil OpenAI.

Tujuannya bukan “review kode yang dibuat AI”, melainkan “review input spesifikasi sebelum diserahkan ke AI”.

Ini bisa digunakan ketika tim ingin menerapkan aturan seperti berikut.

• Jangan teruskan spesifikasi NOT_READY ke implementasi
• Tampilkan finding Critical/Major lebih dulu di PR
• Kelola dulu kualitas input kebutuhan, bukan hasil implementasinya

Instalasi bisa dilakukan dari CLI dengan specguard actions install-pr-review, atau dengan meminta Codex @specguard tolong siapkan workflow SpecGuard PR Review.

Namun, karena ini masih fitur eksperimental, pengaturan otomatis belum didukung, jadi Anda perlu menyiapkan GitHub Secret seperti berikut.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

Status saat ini dan keterbatasan

Karena masih versi awal, ini belum menjadi alat yang bisa menilai semua spesifikasi secara sempurna.

Meski begitu, bagi yang mengalami masalah “implementasi melenceng karena spesifikasinya lemah” saat memakai AI coding, sepertinya ini bisa dicoba sebagai pengaman untuk menyaringnya sekali sebelum implementasi.

Saya ingin mendapatkan umpan balik. Secara khusus, saya penasaran dengan hal-hal berikut.

• Jenis spesifikasi seperti apa yang paling cocok
• Finding mana yang berlebihan atau masih kurang
• Apakah alur plugin Codex benar-benar layak dipakai
• Apakah pemaksaan lewat PR Review cocok dengan workflow tim

Saat ini masih berada pada tahap sebelum versi beta, baru sebatas pengembangan yang benar-benar awal, tetapi saya ingin membangunnya menjadi proyek yang nantinya cukup layak digunakan di lingkungan kerja nyata.

Issue/PR dari siapa pun yang tertarik juga sangat saya sambut. Saat ini issue dan PR di repositori sebagian besar dikelola dalam bahasa Inggris, tetapi jika Anda menulisnya dalam bahasa Korea pun tidak masalah.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Detail lebih lanjut tentang proyek ini dapat dilihat di https://nirsa.tistory.com/487.