Contoh & Resep

Perubahan nyata, dari awal hingga akhir. Setiap resep menampilkan perintah yang akan Anda ketik dan apa yang akan Anda terima kembali, sehingga Anda dapat mencocokkan situasi Anda dengan pola dan menyalinnya. Ini menggunakan perintah core bawaan (propose, explore, apply, update, sync, archive); di mana set yang lebih luas membantu, hal tersebut dicatat.

Sebuah pengingat sebelum Anda memulai: perintah slash seperti /opsx:propose dimasukkan ke dalam chat asisten AI, dan perintah openspec dimasukkan ke dalam terminal. Jika itu hal baru bagi Anda, baca Cara Kerja Perintah terlebih dahulu. Dalam transkrip di bawah ini, You: dan AI: adalah chat, dan baris yang dimulai dengan $ adalah terminal.

Belum yakin apa yang sedang Anda bangun? Sebagian besar resep ini lebih tajam jika Anda mulai dengan /opsx:explore untuk memikirkannya terlebih dahulu. Resep 3 menunjukkannya dalam aksi, dan panduan Jelajahi Terlebih Dahulu membuat kasus lengkapnya.

Resep 1: Fitur kecil, jalur cepat

Kapan menggunakannya: Anda tahu apa yang Anda inginkan, dan itu adalah pekerjaan yang terisolasi. Ini adalah resep yang paling umum.

Seluruh proses hanya terdiri dari tiga perintah. Propose, build, archive.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Sekarang bacalah rencananya. Buka proposal dan delta spec. Ini adalah momen di mana OpenSpec dibangun untuk: menangkap asumsi yang salah saat itu masih satu paragraf, bukan 400 baris kode. Edit setiap artefak secara langsung jika ada yang tidak sesuai, lalu lanjutkan.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Itu saja. Perilaku logout sekarang menjadi bagian dari spesifikasi Anda, dan perubahan tersebut disimpan bersama konteks lengkapnya.

Resep 2: Perbaikan bug

Kapan menggunakannya: ada sesuatu yang rusak dan Anda ingin perbaikan tersebut dicatat sebagai perubahan perilaku yang disengaja, bukan commit misterius.

Perbaikan bug bekerja persis seperti fitur. Perbedaannya terletak pada cara Anda menyusun proposal: deskripsikan perilaku yang benar, bukan hanya "perbaiki bug."

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Karena perbaikan mendarat sebagai persyaratan MODIFIED dengan skenario baru, orang berikutnya (atau sesi AI berikutnya) melihat bukan hanya bahwa Anda memperbaikinya, tetapi apa arti "benar". Kemudian jalankan /opsx:apply dan /opsx:archive seperti biasa.

Tips: untuk perbaikan, skenario yang baik adalah uji regresi dalam bentuk narasi. "GIVEN a logged-out user, WHEN they submit valid credentials, THEN they land on the dashboard and are not redirected again." Tulis itu, dan implementasinya memiliki target yang jelas.

Resep 3: Menjelajah sebelum berkomitmen

Kapan menggunakannya: Anda memiliki masalah tetapi belum memiliki rencana. Anda tidak yakin apa yang harus dibangun, atau pendekatan mana yang benar.

Mulailah dengan /opsx:explore. Ini adalah mitra berpikir tanpa struktur dan tanpa artefak yang dibuat. Ini membaca basis kode Anda dan membantu Anda memutuskan.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

Penjelajahan memperjelas pemikiran Anda sebelum Anda menghabiskan satu perubahan untuk itu. Ketika wawasan mengkristal, propose, dan AI membawa konteks tersebut maju.

Resep 4: Mengelola dua perubahan sekaligus

Kapan menggunakannya: Anda tengah mengerjakan fitur dan perbaikan mendesak melompati antrean.

Perubahan adalah folder independen, sehingga pekerjaan paralel tidak konflik. Mulai perbaikannya, kirimkan, lalu kembali ke fitur tepat di tempat Anda berhenti.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Menamai perubahan dalam /opsx:apply add-dark-mode adalah cara Anda mengarahkan AI ke perubahan spesifik ketika lebih dari satu aktif. Karena tugas melacak penyelesaian dalam tasks.md, AI mengetahui tepat di mana Anda berhenti.

Ketika beberapa perubahan selesai sekaligus, /opsx:bulk-archive yang diperluas menyimpannya bersama-sama dan menyelesaikan konflik spesifikasi dengan memeriksa apa yang sebenarnya diimplementasikan. Lihat Alur Kerja.

Resep 5: Refaktor tanpa perubahan perilaku

Kapan menggunakannya: Anda sedang menyusun ulang kode, dan perilaku yang terlihat secara eksternal harus tetap identik.

Ini adalah kasus yang menarik, karena refaktor murni tidak memiliki apa pun untuk ditambahkan ke spesifikasi Anda. Kontrak perilaku tidak berubah; hanya implementasinya saja. Jadi, pekerjaan hidup dalam desain dan tugas, dan delta spesifikasi kosong atau tidak ada.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Nyatakan delta kosong secara eksplisit dengan mengatur skip_specs: true dalam .openspec.yaml perubahan:

schema: spec-driven
skip_specs: true

Tanpa penanda, openspec validate menolak perubahan dengan nol delta (sehingga fase spesifikasi yang terlupakan masih tertangkap); dengan penanda tersebut, validasi lulus dan openspec status menunjukkan tahap spesifikasi secara eksplisit dilewati daripada tertunda. Jika ternyata refaktor mengubah perilaku, hapus skip_specs dari .openspec.yaml dan tulis spesifikasi delta — validasi menganggap penanda plus file spesifikasi sebagai konflik, sehingga penanda usang tidak dapat bertahan diam-diam.

Mengarsipkan perubahan yang ditandai tidak memerlukan bendera tambahan (tidak ada delta untuk digabungkan). Secara terpisah, bendera --skip-specs memberi tahu perintah terminal untuk melewati langkah spesifikasi secara eksplisit:

$ openspec archive refactor-payment-module --skip-specs

Bendera yang sama berguna untuk alat, CI, dan perubahan hanya dokumen. Prinsipnya: spesifikasi menggambarkan perilaku, jadi jika perilaku tidak berubah, spesifikasi juga seharusnya tidak. Lihat Konsep.

Resep 6: Kontrol langkah demi langkah (perintah yang diperluas)

Kapan menggunakannya: perubahan kompleks atau berisiko di mana Anda ingin meninjau setiap artefak sebelum melanjutkan.

/opsx:propose inti menyusun semuanya sekaligus. Ketika Anda lebih suka melakukannya satu langkah pada satu waktu, nyalakan perintah yang diperluas:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Sekarang Anda dapat membuat kerangka dan membangun secara inkremental:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Tinjuau setiap artefak saat mendarat, edit dengan bebas, dan lanjutkan ketika Anda puas. Ketika Anda ingin sisanya disusun sekaligus, /opsx:ff mempercepat melalui artefak perencanaan yang tersisa. Sebelum mengarsipkan, /opsx:verify memeriksa apakah implementasinya benar-benar cocok dengan spesifikasi. Lihat Alur Kerja.

Resep 7: Belajar seluruh loop secara langsung

Kapan menggunakannya: Anda telah menginstal OpenSpec dan ingin merasakan alur kerja pada kode Anda sendiri, bukan contoh mainan.

Nyalakan perintah yang diperluas (lihat Resep 6), lalu:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard menemukan perbaikan nyata (kecil), membuat perubahan untuk itu, mengimplementasikannya, dan mengarsipkannya, sambil menceritakan setiap langkah. Ini memakan waktu 15 hingga 30 menit dan meninggalkan Anda dengan perubahan nyata yang dapat Anda simpan atau buang. Ini adalah cara termudah untuk belajar. Lihat Perintah.

Memeriksa pekerjaan Anda dari terminal

Kapan saja, dari terminal Anda, Anda dapat memeriksa keadaan sesuatu:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Ini adalah alat baca dan inspeksi. Proposal dan pembangunan masih terjadi melalui perintah slash dalam chat. Detail lengkapnya terdapat di Referensi CLI.

Ke mana harus pergi selanjutnya

• Jelajahi Terlebih Dahulu: cara yang direkomendasikan untuk memulai ketika Anda ragu
• Alur Kerja: pola-pola di atas, dengan panduan keputusan kapan harus menggunakan masing-masing
• Perintah: setiap perintah slash secara rinci
• Memulai: walkthrough perubahan pertama yang kanonik
• Konsep: mengapa potongan-potongan tersebut saling cocok sebagaimana adanya