OpenSpec

FAQ ​

Jawaban cepat untuk pertanyaan yang paling sering diajukan. Jika pertanyaan Anda sebenarnya adalah tentang "ada yang rusak", halaman Troubleshooting lebih tepat. Jika Anda ingin mendefinisikan sebuah istilah, lihat Glossary.

Dasar-dasar ​

Apa itu OpenSpec, dalam satu kalimat? ​

Lapisan ringan yang membuat Anda dan asisten pemrograman AI Anda sepakat secara tertulis tentang apa yang akan dibangun, sebelum kode apa pun ditulis.

Mengapa saya perlu itu? ​

Karena asisten AI sangat percaya diri bahkan ketika mereka salah. Ketika persyaratan hanya ada di utas obrolan, AI mengisi celah dengan tebakan, dan Anda menyadarinya setelah kode dibuat. OpenSpec memindahkan kesepakatan ke tahap awal, di mana kesalahan lebih murah untuk diperbaiki. Lihat Core Concepts at a Glance untuk penjelasan lengkapnya.

Apakah saya harus menggunakannya untuk semuanya? ​

Tidak. Gunakan di tempat di mana kesepakatan penting, yaitu sebagian besar pekerjaan yang tidak sepele. Untuk perbaikan typo satu karakter saja, prosedurnya mungkin tidak sepadan, dan itu tidak masalah.

Dapatkah saya menggunakannya pada basis kode besar yang sudah ada, atau hanya proyek baru? ​

Basis kode yang sudah ada adalah fokus utamanya. OpenSpec bersifat brownfield-first: Anda tidak mendokumentasikan seluruh aplikasi di awal. Anda menulis spesifikasi hanya untuk bagian yang disentuh oleh setiap perubahan, dan spesifikasi Anda akan terisi seiring waktu seiring pekerjaan yang sebenarnya dilakukan. Ada panduan khusus: Using OpenSpec in an Existing Project.

Apakah ini terikat pada satu alat AI? ​

Tidak. OpenSpec bekerja dengan 30+ asisten, termasuk Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex, dan lainnya. Daftar lengkap dan detail per-alat terdapat di Supported Tools.

Menjalankan perintah ​

Di mana saya mengetik /opsx:propose? ​

Di chat asisten AI Anda, bukan di terminal. Ini adalah titik kebingungan yang paling umum, sehingga memiliki halamannya sendiri: How Commands Work. Versi singkatnya: openspec ... dijalankan di terminal, sedangkan /opsx:... dijalankan di chat.

Bagaimana cara "memulai mode interaktif"? ​

Tidak ada mode terpisah yang perlu dimulai. Anda membuka asisten AI seperti biasa dan mengetik perintah slash (/) ke dalam chat-nya. Perintah slash adalah cara Anda "masuk" ke OpenSpec. (Satu-satunya fitur terminal yang benar-benar interaktif adalah openspec view, sebuah dasbor untuk menelusuri spesifikasi dan perubahan.) Penjelasan lengkapnya ada di How Commands Work.

Saya mengetik perintah slash tetapi tidak terjadi apa-apa. Mengapa? ​

Kemungkinan besar Anda mengetiknya di terminal alih-alih di chat AI Anda, Anda menggunakan ejaan yang tidak dikenali oleh alat tersebut, atau perintahnya belum diinstal. Jika file hilang — atau Anda belum pernah mengatur alat tersebut — jalankan openspec init; openspec update hanya menyegarkan file yang sudah ada. Kemudian mulai ulang asisten Anda dan gunakan format yang dicetak di bawah "Getting started" — lihat How To Invoke. Troubleshooting memiliki daftar periksa lengkap.

Mengapa sintaksnya /opsx:propose di satu alat dan /opsx-propose di alat lain? ​

Setiap alat AI menampilkan kustomisasi perintah dengan cara yang sedikit berbeda, dan OpenSpec menuliskannya sesuai dengan cara alat Anda memuat file yang ditulisnya. File perintah bernama opsx-propose.md diketik sebagai /opsx-propose; yang disimpan di commands/opsx/ diketik sebagai /opsx:propose. Alat yang menggunakan skill alih-alih perintah menggunakan nama skill — Codex membutuhkan $openspec-propose, Kimi Code /skill:openspec-propose. Baris "Getting started" dari openspec init sudah mencetak format yang benar untuk alat yang Anda pilih; tabel lengkapnya ada di How To Invoke.

Apa perbedaan antara skill dan perintah? ​

Keduanya adalah file yang ditulis oleh OpenSpec agar asisten Anda dapat menjalankan alur kerja. Skill (.../skills/openspec-*/SKILL.md) adalah standar lintas-alat yang lebih baru; perintah (.../commands/opsx-*) adalah file slash per-alat yang lebih lama. Anda tidak perlu memilih. Anda cukup mengetik perintah slash, dan OpenSpec akan menginstal whichever yang digunakan oleh alat Anda.

Alur kerja ​

Di mana saya harus memulai jika saya tidak yakin apa yang harus dibangun? ​

Mulailah dengan /opsx:explore. Ini adalah mitra berpikir tanpa risiko yang membaca basis kode Anda, menyusun opsi, dan mengubah masalah yang kabur menjadi rencana konkret, semua sebelum ada perubahan atau kode yang dibuat. Ini ada di profil default, jadi selalu tersedia. Ketika rencananya jelas, ia menyerahkan kepada /opsx:propose. Ini adalah kebiasaan terbaik yang bisa dibentuk, karena ini menghentikan AI yang terlalu bersemangat membangun sesuatu yang salah dengan penuh keyakinan. Lihat Explore First.

Apa alur kerja yang paling sederhana? ​

text
/opsx:explore (opsional)   lalu   /opsx:propose <apa yang Anda inginkan>   lalu   /opsx:apply   lalu   /opsx:archive

Explore untuk memikirkannya, propose untuk menyusun rencana, apply untuk membangunnya, archive untuk menyimpannya. Lewati explore ketika Anda sudah tahu persis apa yang Anda inginkan.

Apa perbedaan antara /opsx:propose dan /opsx:new? ​

/opsx:propose adalah perintah satu langkah default: ini membuat perubahan dan menyusun semua artefak perencanaan sekaligus. /opsx:new adalah bagian dari set perintah yang diperluas dan hanya membuat kerangka perubahan kosong, meninggalkan Anda untuk membuat artefak satu per satu dengan /opsx:continue (atau sekaligus dengan /opsx:ff). Gunakan propose kecuali Anda menginginkan kontrol langkah demi langkah. Lihat Commands.

Apa itu profil core dan expanded? ​

Profil menentukan perintah slash mana yang diinstal. Core (default) memberi Anda propose, explore, apply, update, sync, archive. Set expanded menambahkan new, continue, ff, verify, bulk-archive, dan onboard untuk kontrol yang lebih halus. Beralih dengan openspec config profile, lalu terapkan dengan openspec update.

Apakah saya perlu menjalankan /opsx:sync? ​

Biasanya tidak. Sync menggabungkan delta spesifikasi perubahan ke dalam spesifikasi utama Anda, dan /opsx:archive akan menawarkan untuk melakukannya untuk Anda. Jalankan sync secara manual hanya ketika Anda ingin spesifikasi digabungkan sebelum pengarsipan, misalnya pada perubahan yang berlangsung lama. Lihat Commands.

Bagaimana cara mengedit proposal, spesifikasi, atau tugas setelah saya mulai? ​

Cukup edit filenya. Setiap artefak adalah Markdown biasa di openspec/changes/<name>/, dan tidak ada fase terkunci atau mode edit khusus. Ubah secara manual, atau minta AI Anda merevisinya ("perbarui desain untuk menggunakan antrian"), lalu lanjutkan. AI selalu bekerja berdasarkan isi file saat ini. Panduan lengkap: Editing & Iterating on a Change.

Dapatkah saya kembali dan mengubah rencana setelah menerapkan sebagian darinya? ​

Ya, kapan saja. Alur kerjanya cair, sehingga tinjauan dan pengeditan bukanlah fase di mana Anda dikunci keluar. Edit artefaknya, lalu lanjutkan. Jika Anda ingin pemeriksaan terstruktur bahwa kode masih sesuai dengan rencana, jalankan /opsx:verify. Lihat Editing & Iterating on a Change.

Saya mengedit kode secara manual. Bagaimana cara menyelaraskannya dengan spesifikasi? ​

Samakan kembali sebelum Anda mengarsipkannya, karena pengarsipan menjadikan spesifikasi Anda sebagai catatan kebenaran. Jika kode sekarang benar, perbarui delta spesifikasi agar sesuai dengan apa yang Anda kirimkan; jika spesifikasinya benar, terus bangun hingga kode setuju. /opsx:verify menampilkan ketidaksesuaian. Lihat Editing & Iterating on a Change.

Kapan saya harus memperbarui perubahan yang ada versus memulai yang baru? ​

Perbarui ketika itu adalah pekerjaan yang sama, yang disempurnakan. Mulai baru ketika niatnya berubah secara mendasar atau cakupannya meledak menjadi pekerjaan yang berbeda. Ada bagan keputusan dan contoh di Workflows.

Bagaimana jika sesi saya kehabisan konteks, atau persyaratan berubah di tengah implementasi? ​

Di sinilah spesifikasi membuktikan nilainya. Karena rencana hidup dalam file (bukan hanya di riwayat chat), Anda dapat menghapus konteks Anda, memulai sesi AI baru, dan melanjutkan dengan /opsx:apply; ia membaca artefak dan melanjutkan dari tugas pertama yang belum dicentang. Jika persyaratan berubah, edit artefak agar sesuai dengan realitas baru dan lanjutkan. Menjaga jendela konteks yang bersih juga menghasilkan hasil yang lebih baik; hapus sebelum implementasi.

Haruskah saya melakukan komit folder openspec/ ke git? ​

Ya. Spesifikasi, perubahan aktif, dan arsip Anda adalah bagian dari riwayat proyek Anda. Lakukan komit seperti sumber lainnya. Khususnya, arsip menjadi catatan tahan lama tentang mengapa sistem Anda bekerja sebagaimana adanya.

Spesifikasi dan perubahan ​

Apa yang masuk ke dalam spesifikasi versus desain? ​

Spesifikasi menggambarkan perilaku yang dapat diamati: apa yang dilakukan sistem, input, output, dan kondisi error-nya. Desain menggambarkan bagaimana Anda akan membuatnya: pendekatan teknis, keputusan arsitektur, perubahan file. Jika implementasi dapat berubah tanpa mengubah perilaku yang terlihat secara eksternal, itu milik desain, bukan spesifikasi. Concepts membahas lebih dalam.

Apa itu delta spec? ​

Spesifikasi yang hanya menggambarkan apa yang berubah, menggunakan bagian ADDED, MODIFIED, dan REMOVED, daripada menyatakan ulang seluruh spesifikasi. Inilah cara OpenSpec menangani penyuntingan pada sistem yang sudah ada dengan bersih. Lihat Concepts.

Ke mana perubahan yang diarsipkan pergi? ​

Ke openspec/changes/archive/YYYY-MM-DD-<name>/, dengan semua artefak perubahan dipertahankan. Perubahan keluar dari daftar aktif Anda. Perubahan yang secara eksplisit mendeklarasikan retire_capabilities: true juga dapat menghapus spesifikasi kapabilitas utama ketika menghapus persyaratan terakhir dari kapabilitas tersebut.

Konfigurasi dan kustomisasi ​

Bagaimana cara memberi tahu AI tentang tumpukan teknologi saya? ​

Masukkan ke dalam openspec/config.yaml di bawah context:. Teks itu disuntikkan ke setiap permintaan perencanaan, sehingga AI selalu mengetahui tumpukan dan konvensi Anda. Lihat Customization.

Dapatkah saya menghasilkan spesifikasi dalam bahasa selain Inggris? ​

Ya. Tambahkan instruksi bahasa ke context: konfigurasi Anda. Multi-Language memiliki cuplikan salin-tempel untuk beberapa bahasa.

Dapatkah saya mengubah alur kerjanya sendiri? ​

Ya, dengan skema kustom. Skema menentukan artefak mana yang ada dan bagaimana ketergantungannya satu sama lain. Fork default dengan openspec schema fork spec-driven my-workflow, lalu edit. Lihat Customization.

Model, privasi, dan peningkatan ​

Model AI mana yang harus saya gunakan? ​

OpenSpec bekerja paling baik dengan model penalaran tinggi. README merekomendasikan model seperti Codex 5.5 dan Opus 4.7 untuk perencanaan dan implementasi. Juga jaga jendela konteks Anda tetap bersih: hapus sebelum implementasi untuk hasil terbaik.

Apakah OpenSpec mengumpulkan data? ​

Ini mengumpulkan statistik penggunaan anonim: hanya nama perintah dan versi. Tidak ada argumen, jalur, konten, atau data pribadi, dan ini mati secara otomatis di CI. Opt-out dengan export OPENSPEC_TELEMETRY=0 atau export DO_NOT_TRACK=1.

Bagaimana cara meningkatkan versinya? ​

Dua langkah. Tingkatkan paketnya (npm install -g @fission-ai/openspec@latest), lalu jalankan openspec update di dalam setiap proyek untuk menyegarkan skill dan perintah yang dihasilkan.

Bagaimana cara mencopot pemasangan OpenSpec? ​

Tidak ada perintah pencopotan, karena ini hanyalah paket global plus file di proyek Anda. Hapus paketnya (npm uninstall -g @fission-ai/openspec), dan opsional hapus direktori openspec/ serta file alat yang dihasilkan. Langkah demi langkah, termasuk apa yang aman untuk disimpan, ada di Installation: Uninstalling.

Mendapatkan bantuan ​

Di mana saya bertanya pertanyaan atau melaporkan bug? ​

Dokumen ini salah atau membingungkan. Apa yang harus saya lakukan? ​

Beritahu kami, atau perbaiki. PR dokumentasi diterima dan dihargai. Buka isu atau kirim pull request.