OpenSpec

Memulai ​

Panduan ini menjelaskan cara OpenSpec bekerja setelah Anda menginstalnya dan melakukan inisialisasi. Untuk instruksi instalasi, lihat README utama atau Panduan Instalasi. Baru mengenal seluruh set dokumentasi ini? Beranda dokumentasi memetakan semuanya.

Di mana saya mengetik perintah-perintah ini? Di dua tempat, dan mencampuradukkannya adalah kesalahan awal yang paling umum.

  • Perintah openspec ... (seperti openspec init) dijalankan di terminal Anda.
  • Perintah /opsx:... (seperti /opsx:propose) dijalankan di chat asisten AI, kotak yang sama tempat Anda meminta asisten untuk menulis kode.

Tidak ada "mode interaktif" terpisah untuk dimulai. Anda cukup mengetik perintah slash di chat dan asisten Anda akan melanjutkan dari sana. Penjelasan lengkap: Cara Kerja Perintah.

Lima Menit Pertama Anda ​

Seluruh siklus kerja, dengan setiap langkah ditandai berdasarkan lokasinya:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (opsional: pikirkan dulu)
AI CHAT      /opsx:propose add-dark-mode      (AI menyusun rencana; Anda meninjaunya)
AI CHAT      /opsx:apply                      (AI membangunnya)
AI CHAT      /opsx:archive                    (spesifikasi diperbarui, perubahan disimpan)

Dua langkah terminal untuk pengaturan, lalu Anda bekerja di dalam chat. Sisa panduan ini menguraikan apa yang dilakukan setiap langkah dan apa yang akan Anda lihat.

Tidak ingin melakukan bagian terminal sendiri? Tempelkan prompt setup ke asisten Anda dan ia akan menangani kedua baris tersebut, lalu melaporkan apa yang telah dibuatnya.

Belum yakin apa yang harus dibangun? Mulailah dengan /opsx:explore. Ini adalah mitra berpikir tanpa risiko yang membaca basis kode Anda, mempertimbangkan opsi, dan mempertajam ide yang kabur menjadi rencana konkret, semua sebelum artefak atau kode apa pun ada. Ketika gambaran sudah jelas, ia menyerahkan kepada /opsx:propose. Ini adalah kebiasaan terbaik untuk bekerja dengan AI yang jika tidak akan dengan percaya diri membangun hal yang salah. Lihat Panduan Explore.

Cara Kerja ​

OpenSpec membantu Anda dan asisten coding AI Anda sepakat tentang apa yang akan dibangun sebelum kode apa pun ditulis.

Jalur cepat default (profil inti):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (opsional)

Mulailah dengan /opsx:explore ketika Anda sedang mencari tahu apa yang harus dilakukan, atau langsung lanjut ke /opsx:propose ketika Anda sudah mengetahuinya. Explore ada di profil default, jadi selalu tersedia kapan pun Anda membutuhkannya.

Jalur diperluas (pemilihan alur kerja kustom):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Profil global default adalah core, yang mencakup propose, explore, apply, update, sync, dan archive. Anda dapat mengaktifkan perintah alur kerja yang diperluas dengan openspec config profile dan kemudian openspec update.

Apa yang Dibuat oleh OpenSpec ​

Setelah menjalankan openspec init, proyek Anda memiliki struktur berikut:

openspec/
├── specs/              # Sumber kebenaran (perilaku sistem Anda)
│   └── <domain>/
│       └── spec.md
├── changes/            # Pembaruan yang diusulkan (satu folder per perubahan)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Spesifikasi delta (apa yang berubah)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Konfigurasi proyek (opsional)

Dua direktori kunci:

  • specs/ - Sumber kebenaran. Spesifikasi ini menggambarkan bagaimana sistem Anda saat ini berperilaku. Disusun berdasarkan domain (misalnya, specs/auth/, specs/payments/).

  • changes/ - Modifikasi yang diusulkan. Setiap perubahan mendapatkan foldernya sendiri dengan semua artefak terkait. Ketika sebuah perubahan selesai, spesifikasinya digabungkan ke dalam direktori specs/ utama.

Memahami Artefak ​

Setiap folder perubahan berisi artefak yang membimbing pekerjaan:

ArtefakTujuan
proposal.md"Mengapa" dan "Apa" - menangkap maksud, ruang lingkup, dan pendekatan
specs/Spesifikasi delta yang menunjukkan persyaratan ADDED/MODIFIED/REMOVED
design.md"Bagaimana" - pendekatan teknis dan keputusan arsitektur
tasks.mdDaftar periksa implementasi dengan kotak centang

Artefak saling mendukung:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            perbarui saat Anda belajar

Anda selalu dapat kembali dan menyempurnakan artefak sebelumnya saat Anda mempelajari lebih lanjut selama implementasi.

Cara Kerja Spesifikasi Delta ​

Spesifikasi delta adalah konsep kunci dalam OpenSpec. Mereka menunjukkan apa yang berubah relatif terhadap spesifikasi Anda saat ini.

Format ​

Spesifikasi delta menggunakan bagian untuk menunjukkan jenis perubahan:

markdown
# Delta untuk Auth

## Persyaratan TAMBAHAN

### Persyaratan: Autentikasi Dua Faktor
Sistem HARUS memerlukan faktor kedua selama login.

#### Skenario: OTP diperlukan
- DARI pengguna dengan 2FA diaktifkan
- SAAT pengguna mengirimkan kredensial yang valid
- MAKA tantangan OTP ditampilkan

## Persyaratan DIMODIFIKASI

### Persyaratan: Waktu Tunggu Sesi
Sistem AKAN kedaluwarsa sesi setelah 30 menit tidak aktif.
(Sebelumnya: 60 menit)

#### Skenario: Waktu tunggu idle
- DARI sesi yang diautentikasi
- SAAT 30 menit berlalu tanpa aktivitas
- MAKA sesi tidak valid

## Persyaratan DIHAPUS

### Persyaratan: Ingat Saya
(Dipensiunkan demi 2FA)

Apa yang Terjadi Saat Arsip ​

Ketika Anda mengarsipkan sebuah perubahan:

  1. Persyaratan TAMBAHAN ditambahkan ke spesifikasi utama
  2. Persyaratan DIMODIFIKASI menggantikan versi yang ada
  3. Persyaratan DIHAPUS dihapus dari spesifikasi utama

Folder perubahan dipindahkan ke openspec/changes/archive/ untuk riwayat audit.

Contoh: Perubahan Pertama Anda ​

Mari kita telusuri penambahan mode gelap ke aplikasi.

1. Mulai Perubahan (Default) ​

text
Anda: /opsx:propose add-dark-mode

AI:  Membuat openspec/changes/add-dark-mode/
     ✓ proposal.md — mengapa kita melakukan ini, apa yang berubah
     ✓ specs/       — persyaratan dan skenario
     ✓ design.md    — pendekatan teknis
     ✓ tasks.md     — daftar periksa implementasi
     Siap untuk implementasi!

Jika Anda telah mengaktifkan profil alur kerja yang diperluas, Anda juga dapat melakukannya sebagai dua langkah: /opsx:new lalu /opsx:ff (atau /opsx:continue secara bertahap).

2. Apa yang Dibuat ​

proposal.md - Menangkap maksud:

markdown
# Proposal: Tambah Mode Gelap

## Maksud
Pengguna telah meminta opsi mode gelap untuk mengurangi ketegangan mata
selama penggunaan malam hari.

## Ruang Lingkup
- Tambah tombol ganti tema di pengaturan
- Mendukung deteksi preferensi sistem
- Simpan preferensi di localStorage

## Pendekatan
Gunakan properti khusus CSS untuk tema dengan konteks React
untuk manajemen keadaan.

specs/ui/spec.md - Delta yang menunjukkan persyaratan baru:

markdown
# Delta untuk UI

## Persyaratan TAMBAHAN

### Persyaratan: Pemilihan Tema
Sistem AKEN memungkinkan pengguna memilih antara tema terang dan gelap.

#### Skenario: Ganti manual
- DARI pengguna di halaman apa pun
- SAAT pengguna mengklik tombol ganti tema
- MAKA tema beralih segera
- DAN preferensi bertahan melintasi sesi

#### Skenario: Preferensi sistem
- DARI pengguna tanpa preferensi tersimpan
- SAAT aplikasi dimuat
- MAKA skema warna pilihan sistem digunakan

tasks.md - Daftar periksa implementasi:

markdown
# Tugas

## 1. Infrastruktur Tema
- [ ] 1.1 Buat ThemeContext dengan keadaan terang/gelap
- [ ] 1.2 Tambahkan properti khusus CSS untuk warna
- [ ] 1.3 Implementasikan persistensi localStorage

## 2. Komponen UI
- [ ] 2.1 Buat komponen ThemeToggle
- [ ] 2.2 Tambahkan tombol ganti ke halaman pengaturan
- [ ] 2.3 Perbarui Header untuk menyertakan tombol ganti cepat

## 3. Gaya
- [ ] 3.1 Tentukan palet warna tema gelap
- [ ] 3.2 Perbarui komponen untuk menggunakan variabel CSS

3. Implementasikan ​

Anda: /opsx:apply

AI:  Bekerja melalui tugas...
     ✓ 1.1 Membuat ThemeContext dengan keadaan terang/gelap
     ✓ 1.2 Menambahkan properti khusus CSS ke globals.css
     ✓ 1.3 Mengimplementasikan persistensi localStorage
     ✓ 2.1 Membuat komponen ThemeToggle
     ...
     Semua tugas selesai!

Selama implementasi, jika Anda menemukan bahwa desain perlu disesuaikan, cukup perbarui artefaknya dan lanjutkan.

4. Arsipkan ​

Anda: /opsx:archive

AI:  Mengarsipkan add-dark-mode...
     ✓ Menggabungkan spesifikasi ke openspec/specs/ui/spec.md
     ✓ Dipindahkan ke openspec/changes/archive/2025-01-24-add-dark-mode/
     Selesai! Siap untuk fitur berikutnya.

Spesifikasi delta Anda sekarang menjadi bagian dari spesifikasi utama, mendokumentasikan bagaimana sistem Anda bekerja.

Verifikasi dan Tinjauan ​

Gunakan CLI untuk memeriksa perubahan Anda:

bash
# Daftar perubahan aktif
openspec list

# Lihat detail perubahan
openspec show add-dark-mode

# Validasi format spesifikasi
openspec validate add-dark-mode

# Dasbor interaktif
openspec view

Langkah Selanjutnya ​