Pemecahan Masalah

Solusi konkret untuk masalah yang konkret. Setiap entri menyebutkan gejala, menjelaskan penyebab yang mungkin dalam satu kalimat, dan memberikan solusinya. Jika Anda tidak menemukan masalah Anda di sini, FAQ mungkin membantu, dan Discord pasti akan membantu.

Instalasi dan penyiapan

openspec: command not found

CLI belum terinstal, atau shell Anda tidak dapat menemukannya. Instal secara global dan periksa:

npm install -g @fission-ai/openspec@latest
openspec --version

Jika sudah terinstal tetapi masih tidak ditemukan, direktori bin global npm Anda kemungkinan besar tidak ada di PATH. Jalankan npm prefix -g untuk melihat di mana paket global berada: pada macOS dan Linux, biner berada di bin/ direktori tersebut, dan pada Windows mereka berada langsung di dalamnya. Pastikan jalur tersebut ada di PATH Anda. (npm bin -g dihapus di npm 9.)

Jika Anda menggunakan instalasi bantuan AI, ini adalah titik transisi yang diharapkan: prompt tersebut memberi tahu asisten Anda untuk menunjukkan perubahan PATH kepada Anda daripada mengedit file startup shell itu sendiri.

"Requires Node.js 20.19.0 or higher"

OpenSpec berjalan di Node 20.19.0+. Periksa versi Anda dan tingkatkan jika diperlukan:

node --version

Jika Anda menggunakan bun untuk menginstal OpenSpec, perhatikan bahwa OpenSpec tetap berjalan di Node, jadi Anda perlu Node 20.19.0+ tersedia di PATH Anda terlepas dari itu. Lihat Instalasi.

openspec init tidak mengonfigurasi alat AI saya

Init menanyakan alat mana yang akan disiapkan. Jika Anda melewatkan alat Anda atau ingin menambahkan alat lain, jalankan lagi, atau gunakan bentuk non-interaktif:

openspec init --tools claude,cursor

Daftar lengkap ID alat ada di Alat yang Didukung. Gunakan --tools all untuk semuanya, --tools none untuk melewati penyiapan alat.

Perintah tidak muncul

Jika /opsx:propose (atau setara alat Anda) tidak muncul atau tidak melakukan apa-apa, ikuti daftar ini. Daftar ini diurutkan dari yang tercepat untuk diperiksa.

1. Anda mungkin berada di tempat yang salah. Slash command masuk ke chat asisten AI Anda, bukan terminal Anda. Jika Anda mengetik /opsx:propose ke dalam shell Anda, itulah masalahnya. Lihat Cara Kerja Perintah.

2. Regenerasi file. Dari root proyek Anda:

   openspec update

   Ini menulis ulang file skill dan command untuk setiap alat yang telah Anda konfigurasi.

   File instruksi berasal dari CLI yang terinstal, sehingga CLI yang usang melaporkan semuanya terbaru tanpa pernah menulis alur kerja yang lebih baru. openspec update sekarang memeriksa hal tersebut dan menawarkan untuk meningkatkan — ambil tawaran tersebut jika Anda melihatnya.

3. Mulai ulang asisten Anda. Sebagian besar alat memindai skill dan command saat startup. Jendela baru sering kali melakukannya.

4. Konfirmasi file ada. Untuk Claude Code, periksa bahwa .claude/skills/ berisi folder openspec-*. Alat lain menggunakan direktori mereka sendiri, semua terdaftar di Alat yang Didukung.

5. Periksa apakah Anda menginisialisasi proyek ini. Skill ditulis per proyek. Jika Anda mengkloning repositori atau berpindah folder, jalankan openspec init (atau openspec update) di sana.

6. Konfirmasi bahwa alat Anda mendukung file command. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent, dan target .agents bersama tidak menghasilkan file command opsx-*; mereka menggunakan pemanggilan berbasis skill, sehingga /opsx tidak akan pernah autocomplete untuk mereka. Ketik $openspec-propose di Codex, /skill:openspec-propose di Kimi Code, dan /openspec-propose di sisanya. Target .agents bersama bersifat netral vendor, sehingga /openspec-propose adalah bentuk umum daripada yang dijamin — jika asisten Anda tidak meresponsnya, lihat dokumentasinya sendiri tentang cara memanggil skill. Amazon Q mendapatkan file command, tetapi memuatnya ke pustaka prompt-nya daripada menu slash-nya — ketik @opsx-propose di sana, bukan /opsx. Bentuk setiap alat terdaftar di Cara Memanggil.

Bekerja dengan perubahan

"Change not found"

Perintah tidak dapat menentukan perubahan mana yang Anda maksud. Sebutkan secara eksplisit, atau periksa apa yang ada:

openspec list                    # lihat perubahan aktif
/opsx:apply add-dark-mode        # sebutkan perubahan di chat

Juga konfirmasi bahwa Anda berada di direktori proyek yang benar.

"No artifacts ready"

Setiap artifact sudah dibuat atau diblokir menunggu dependensi. Lihat apa yang memblokir:

openspec status --change <name>

Kemudian buat dependensi yang hilang terlebih dahulu. Ingat urutannya: proposal memungkinkan specs dan design; specs dan design bersama-sama memungkinkan tasks.

openspec validate melaporkan peringatan atau error

Validasi memeriksa specs dan perubahan Anda untuk masalah struktural. Baca pesan tersebut: ia menyebutkan file dan masalahnya.

openspec validate <name>           # validasi satu item
openspec validate --all            # validasi semuanya
openspec validate --all --strict   # pemeriksaan lebih ketat, bagus untuk CI
openspec validate --archived       # gagal jika perubahan yang diarsipkan memiliki tugas yang belum diperiksa

Penyebab umum adalah bagian wajib yang hilang (seperti spec tanpa skenario) atau header delta yang tidak sesuai format. Perbaiki file dan jalankan lagi. Referensi CLI mendokumentasikan format output.

Satu pesan layak mendapat catatan tersendiri:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Requirement MODIFIED menggantikan seluruh blok requirement, sehingga harus membawa setiap skenario yang bertahan dari perubahan tersebut, bukan hanya yang Anda edit. Salin skenario yang dinamakan dari openspec/specs/<capability-path>/spec.md kembali ke delta, mempertahankan direktori domain apa pun di path-nya. Hal ini sering muncul pada perubahan lama setelah perubahan orang lain menambahkan skenario ke requirement yang sama — archive menolak perubahan tersebut dalam kasus apa pun, dan validasi sekarang mengatakan demikian sebelum Anda mengimplementasikannya.

AI membuat artifact yang tidak lengkap atau salah

AI tidak memiliki cukup konteks. Beberapa tuas membantu:

• Tambahkan konteks proyek di openspec/config.yaml agar stack dan konvensi Anda disuntikkan ke setiap permintaan. Lihat Kustomisasi.
• Tambahkan rules: per-artifact untuk panduan yang hanya berlaku untuk, misalnya, specs.
• Berikan deskripsi yang lebih detail saat Anda mengusulkan.
• Gunakan /opsx:continue yang diperluas untuk membuat satu artifact sekaligus dan tinjau masing-masing, alih-alih /opsx:ff melakukannya semua sekaligus.

Archive tidak selesai, atau memperingatkan tentang tugas yang tidak lengkap

Archive tidak akan memblokir pada tugas yang tidak lengkap, tetapi memperingatkan Anda, karena pengarsipan biasanya berarti pekerjaan selesai. Jika tugas tetap ada dengan sengaja (Anda mengajukan perubahan parsial), lanjutkan. Jika tidak, selesaikan tugas-tugas tersebut terlebih dahulu. Archive juga akan menawarkan untuk menyinkronkan delta specs Anda ke specs utama jika Anda belum menyinkronkan; katakan ya kecuali Anda memiliki alasan untuk tidak melakukannya.

"User force closed the prompt with 0 null"

Sesuatu menjalankan openspec archive di mana tidak ada yang bisa menjawab pertanyaan — agen AI yang memanggilnya dari alat, pekerjaan CI, atau shell apa pun dengan stdin tertutup. Archive meminta hingga tiga konfirmasi, dan yang tidak dapat dijawab sebelumnya gagal dengan pesan mentah tersebut.

Lewati --yes untuk menjawabnya di awal:

openspec archive <change-name> --yes

Simpan flag apa pun yang sudah Anda lewati — --skip-specs dan --no-validate mengubah apa yang dilakukan archive, sehingga menjalankan ulang dengan --yes saja bukanlah perintah yang sama. Versi saat ini memberi nama flag untuk Anda dan mencetak baris Fix: yang dapat Anda tempel. Jika Anda bermaksud memilih dari daftar, berikan nama perubahan secara eksplisit: picker juga membutuhkan jawaban.

Jika Anda sebaliknya menjalankan archive dengan outputnya dialihkan ke file atau ditangkap oleh alat dan memang mengalirkan jawaban (printf 'y\n' | openspec archive …), versi lama menulis kode escape terminal ke dalam tangkapan tersebut saat menggambar prompt — di beberapa lingkungan cukup untuk membengkakkan file secara buruk. Versi saat ini membaca prompt konfirmasi sebagai teks biasa kapan pun stdout bukan terminal, dan openspec archive tanpa argumen (yang akan menampilkan pemilih perubahan interaktif) meminta Anda untuk memberikan nama perubahan di awal alih-alih merender menu ke dalam tangkapan. Dalam kedua kasus tersebut, jalanan yang dialihkan dan agen tetap bersih; melewatkan --yes (dengan nama perubahan) melewati prompt sepenuhnya.

Konfigurasi

config.yaml saya tidak diterapkan

Tiga tersangka biasa:

1. Nama file salah. Harus berupa openspec/config.yaml, bukan .yml.
2. YAML tidak valid. Jalankan melalui validator YAML apa pun; CLI juga melaporkan error sintaks dengan nomor baris.
3. Anda mengharapkan restart. Anda tidak membutuhkannya. Perubahan konfigurasi berlaku segera.

"Unknown artifact ID in rules: X"

Kunci di bawah rules: tidak cocok dengan artifact apa pun di skema Anda. Untuk skema default spec-driven, ID yang valid adalah proposal, specs, design, tasks. Untuk melihat ID untuk skema apa pun:

openspec schemas --json

"Context too large"

Bidang context: dibatasi pada 50KB, disengaja, karena disuntikkan ke setiap permintaan. Ringkas, atau tautkan ke dokumen yang lebih panjang alih-alih menempelkannya. Konteks yang ramping juga menghasilkan hasil yang lebih baik dan lebih cepat.

"Schema not found"

Nama skema yang Anda referensi tidak ada. Daftar apa yang tersedia dan periksa ejaannya:

openspec schemas                    # daftar skema yang tersedia
openspec schema which <name>        # lihat dari mana skema diselesaikan
openspec schema init <name>         # buat kustom

Lihat Kustomisasi.

Migrasi dari alur kerja lama

"Legacy files detected in non-interactive mode"

Anda berada di CI atau shell non-interaktif, dan OpenSpec menemukan file lama untuk dibersihkan tetapi tidak dapat meminta Anda. Setujui secara otomatis:

openspec init --force

Untuk Codex, OpenSpec mungkin mendeteksi file prompt terkelola lama di $CODEX_HOME/prompts atau ~/.codex/prompts. Pembersihan ini terbatas pada nama file prompt Codex legacy yang ada dalam daftar putih OpenSpec, dan openspec init non-interaktif hanya menghapus file yang pengganti .agents/skills/openspec-* skills-nya ada. openspec update non-interaktif meninggalkan semua pembersihan legacy tanpa tersentuh kecuali Anda melewatkan --force.

Perintah tidak muncul setelah migrasi

Mulai ulang IDE Anda. Skill dideteksi saat startup. Jika mereka masih tidak muncul, jalankan openspec update dan periksa lokasi file di Alat yang Didukung.

project.md lama saya tidak dimigrasikan

Itu disengaja. OpenSpec tidak pernah menghapus project.md secara otomatis karena mungkin memegang konteks yang Anda tulis. Pindahkan bagian yang berguna ke bagian context: di config.yaml, lalu hapus sendiri. Panduan Migrasi membahas ini, termasuk prompt yang dapat Anda berikan kepada AI Anda untuk melakukan penyulingan.

Masih buntu?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Dari terminal Anda: openspec feedback "what went wrong" membuka issue untuk Anda.

Saat Anda melaporkan masalah, sertakan versi OpenSpec Anda (openspec --version), versi Node Anda (node --version), alat AI Anda, dan perintah serta output yang tepat. Itu membantu mempercepat bantuan.