Memulai

Panduan ini menjelaskan cara kerja OpenSpec setelah Anda menginstal dan menginisialisasinya. Untuk instruksi instalasi, lihat README utama.

Cara Kerja

OpenSpec membantu Anda dan asisten pemrograman AI Anda untuk menyepakati apa yang akan dibangun sebelum kode apa pun ditulis.

Jalur cepat default (profil inti):

/opsx:propose ──► /opsx:apply ──► /opsx:archive

Jalur diperluas (pilihan alur kerja kustom):

/opsx:new ──► /opsx:ff atau /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

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

Apa yang Dibuat 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 mendeskripsikan bagaimana sistem Anda saat ini berperilaku. Diorganisir berdasarkan domain (misalnya, specs/auth/, specs/payments/).

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

Memahami Artefak

Setiap folder perubahan berisi artefak yang memandu pekerjaan:

Artefak	Tujuan
proposal.md	"Mengapa" dan "apa" - menangkap niat, cakupan, dan pendekatan
specs/	Spesifikasi delta yang menunjukkan persyaratan DITAMBAHKAN/DIMODIFIKASI/DIHAPUS
design.md	"Bagaimana" - pendekatan teknis dan keputusan arsitektur
tasks.md	Daftar periksa implementasi dengan kotak centang

Artefak dibangun satu sama lain:

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

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

Cara Kerja Spesifikasi Delta

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

Formatnya

Spesifikasi delta menggunakan bagian untuk menunjukkan jenis perubahan:

# Delta untuk Auth

## Persyaratan DITAMBAHKAN

### Persyaratan: Autentikasi Dua Faktor
Sistem WAJIB meminta faktor kedua selama login.

#### Skenario: OTP diperlukan
- DENGAN pengguna yang memiliki 2FA aktif
- KETIKA pengguna mengirimkan kredensial yang valid
- MAKA tantangan OTP disajikan

## Persyaratan DIMODIFIKASI

### Persyaratan: Batas Waktu Sesi
Sistem HARUS mengakhiri sesi setelah 30 menit tidak aktif.
(Sebelumnya: 60 menit)

#### Skenario: Batas waktu idle
- DENGAN sesi yang terotentikasi
- KETIKA 30 menit berlalu tanpa aktivitas
- MAKA sesi dibatalkan

## Persyaratan DIHAPUS

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

Apa yang Terjadi Saat Pengarsipan

Ketika Anda mengarsipkan sebuah perubahan:

1. Persyaratan DITAMBAHKAN 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 jelaskan proses menambahkan mode gelap ke sebuah aplikasi.

1. Memulai Perubahan (Default)

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 melakukan ini dalam dua langkah: /opsx:new lalu /opsx:ff (atau /opsx:continue secara bertahap).

2. Apa yang Dibuat

proposal.md - Menangkap niat:

# Proposal: Tambahkan Mode Gelap

## Niat
Pengguna telah meminta opsi mode gelap untuk mengurangi ketegangan mata
saat digunakan pada malam hari.

## Cakupan
- Tambahkan pengalih tema di pengaturan
- Dukung deteksi preferensi sistem
- Pertahankan preferensi di localStorage

## Pendekatan
Gunakan properti kustom CSS untuk tema dengan konteks React
untuk manajemen状态.

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

# Delta untuk UI

## Persyaratan DITAMBAHKAN

### Persyaratan: Pilihan Tema
Sistem HARUS memungkinkan pengguna memilih antara tema terang dan gelap.

#### Skenario: Pengalih manual
- DENGAN pengguna di halaman mana pun
- KETIKA pengguna mengklik pengalih tema
- MAKA tema beralih segera
- DAN preferensi dipertahankan di seluruh sesi

#### Skenario: Preferensi sistem
- DENGAN pengguna yang tidak memiliki preferensi tersimpan
- KETIKA aplikasi dimuat
- MAKA skema warna yang disukai sistem digunakan

tasks.md - Daftar periksa implementasi:

# Tugas

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

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

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

3. Implementasi

Anda: /opsx:apply

AI:  Mengerjakan tugas...
     ✓ 1.1 Membuat ThemeContext dengan状态 terang/gelap
     ✓ 1.2 Menambahkan properti kustom 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 penyesuaian, cukup perbarui artefak dan lanjutkan.

4. Pengarsipan

Anda: /opsx:archive

AI:  Mengarsipkan add-dark-mode...
     ✓ Menggabungkan spesifikasi ke openspec/specs/ui/spec.md
     ✓ Memindahkan 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 cara kerja sistem Anda.

Verifikasi dan Tinjauan

Gunakan CLI untuk memeriksa perubahan Anda:

# 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

• Alur Kerja - Pola umum dan kapan menggunakan setiap perintah
• Perintah - Referensi lengkap untuk semua perintah slash
• Konsep - Pemahaman lebih mendalam tentang spesifikasi, perubahan, dan skema
• Kustomisasi - Membuat OpenSpec bekerja sesuai cara Anda