OpenSpec

Alur Kerja ​

Panduan ini membahas pola alur kerja umum untuk OpenSpec dan kapan harus menggunakan masing-masing. Untuk pengaturan dasar, lihat Getting Started. Untuk referensi perintah, lihat Commands.

Filsafat: Aksi, Bukan Fase ​

Alur kerja tradisional memaksa Anda melewati fase-fase: perencanaan, lalu implementasi, lalu selesai. Namun, pekerjaan nyata tidak selalu cocok dengan kotak-kotak yang kaku.

OPSX mengambil pendekatan yang berbeda:

text
Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

Prinsip utama:

  • Aksi, bukan fase - Perintah adalah hal yang bisa Anda lakukan, bukan tahap yang mengurung Anda
  • Dependensi adalah pemungkin - Mereka menunjukkan apa yang mungkin, bukan apa yang wajib dilakukan selanjutnya

Kustomisasi: Alur kerja OPSX didorong oleh skema yang mendefinisikan urutan artefak. Lihat Customization untuk detail tentang membuat skema kustom.

Ringkasan Alur Kerja ​

Alur kerja default tetap cair: eksplorasi dan verifikasi bersifat opsional, dan Anda dapat memperbarui artefak perencanaan kapan pun implementasi mengungkap hal baru.

mermaid
flowchart TD
    Idea["Ide atau masalah"] --> Explore["/opsx:explore<br/>(opsional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Artefak perencanaan<br/>siap?"}
    Review -->|"Sempurnakan"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implementasikan"| Apply["/opsx:apply"]
    Apply -->|"Rencana berubah"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(opsional, pemilihan kustom)"]
    Apply --> Sync["/opsx:sync<br/>(opsional sebelum arsip)"]
    Verify --> Verified{"Siap diarsipkan?"}
    Verified -->|"Perbaiki implementasi"| Apply
    Verified -->|"Revisi rencana"| Update
    Verified -->|"Siap"| Sync
    Verified -->|"Siap"| Archive
    Sync --> Archive

Asisten AI mengendalikan alur kerja, sementara CLI menyediakan kerangka kerja yang deterministik, status, dan instruksi artefak:

mermaid
sequenceDiagram
    actor Manusia
    participant Asisten as Asisten AI
    participant CLI sebagai CLI OpenSpec
    participant File sebagai File perencanaan dan implementasi

    Manusia->>Asisten: /opsx:propose "perubahan"
    Asisten->>CLI: openspec new change
    CLI->>File: Kerangka metadata perubahan
    Asisten->>CLI: Meminta status dan instruksi artefak
    CLI-->>Asisten: Urutan pembuatan, jalur, dan templat
    Asisten->>File: Menulis artefak perencanaan sesuai skema
    Asisten-->>Manusia: Menyajikan artefak untuk ditinjau

    Manusia->>Asisten: /opsx:apply
    Asisten->>CLI: Meminta instruksi apply
    CLI-->>Asisten: File konteks dan status tugas
    Asisten->>File: Mengimplementasikan tugas dan memperbarui kotak centang
    Asisten-->>Manusia: Melaporkan status implementasi

    Manusia->>Asisten: /opsx:archive
    Asisten->>CLI: Meminta input arsip dan status artefak
    CLI-->>Asisten: Jalur perencanaan dan penyelesaian artefak
    Asisten->>File: Membaca status tugas dan membandingkan spesifikasi delta
    opt Spesifikasi delta ada
        Asisten-->>Manusia: Menawarkan sinkronisasi sebelum pengarsipan
        alt Sinkronisasi diterima
            Manusia->>Asisten: Konfirmasi sinkronisasi
            Asisten->>File: Menggabungkan spesifikasi delta ke dalam spesifikasi utama
        else Sinkronisasi dilewati
            Manusia->>Asisten: Arsip tanpa sinkronisasi
        end
    end
    Asisten->>File: Memindahkan perubahan ke arsip
    Asisten-->>Manusia: Melaporkan lokasi arsip dan hasil sinkronisasi

    Note over Manusia,CLI: Alternatif CLI: openspec archive change-name --yes melewati prompt konfirmasi. Ini masih memvalidasi, lalu menerapkan spesifikasi delta apa pun dan mengarsipkannya

Dua Mode ​

Jalur Cepat Default (profil core) ​

Instalasi baru secara default menggunakan core, yang menyediakan:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

Alur tipikal:

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

Mulailah dengan mengeksplorasi (kebiasaan yang layak dibentuk) ​

/opsx:explore adalah bagian dari profil default, bukan tambahan lanjutan. Ini adalah langkah yang harus diambil setiap kali Anda memiliki masalah tetapi belum memiliki rencana, yang, dengan asisten AI, terjadi sebagian besar waktu.

text
Anda: /opsx:explore

AI:  Apa yang ingin Anda jelajahi?

Anda: Hasil pencarian kita terasa basi. Saya tidak yakin apakah itu caching,
     pengindeksan, atau kuerinya sendiri.

AI:  Biarkan saya melihat... [membaca layanan pencarian dan lapisan cache]
     Itu indeksnya: hanya dibangun ulang setiap malam, jadi edit tidak muncul
     sampai hari berikutnya. Dua opsi: rebuild saat tulis (sederhana,
     beban lebih tinggi) atau invalidasi cache TTL pendek (lebih banyak komponen bergerak,
     beban lebih rendah). Mengingat volume tulis Anda rendah, rebuild-on-write adalah
     perbaikan yang lebih bersih. Ingin memetakannya?

Anda: Ya.

Anda: /opsx:propose rebuild-search-index-on-write

Explore tidak membuat artefak dan tidak menulis kode. Ini adalah percakapan bebas risiko yang mengubah kekhawatiran samar menjadi perubahan yang tepat, sehingga proposal yang mengikuti menjadi tajam. Sudah tahu persis apa yang Anda inginkan? Lewati ini dan langsung ke /opsx:propose. Panduan lengkap: Jelajahi Pertama.

Alur Kerja Diperluas/Lengkap (pemilihan kustom) ​

Jika Anda menginginkan perintah scaffold-and-build yang eksplisit (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), aktifkan dengan:

bash
openspec config profile
openspec update

Pola Alur Kerja (Mode Diperluas) ​

Fitur Cepat ​

Ketika Anda tahu apa yang ingin dibangun dan hanya perlu mengeksekusi:

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

Contoh percakapan:

text
Anda: /opsx:new add-logout-button

AI:  Dibuat openspec/changes/add-logout-button/
     Siap membuat: proposal

Anda: /opsx:ff

AI:  Membuat semua artefak perencanaan...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Siap untuk implementasi!

Anda: /opsx:apply

AI:  Bekerja melalui tugas-tugas...
     ✓ Menambahkan tombol keluar ke header
     ✓ Mengimplementasikan pembersihan sesi
     ✓ Menambahkan dialog konfirmasi
     Semua tugas selesai!

Anda: /opsx:archive

AI:  ✓ Spesifikasi digabungkan
     ✓ Perubahan diarsipkan

Terbaik untuk: Fitur kecil hingga menengah, perbaikan bug, perubahan sederhana.

Eksploratif ​

Ketika persyaratan tidak jelas atau Anda perlu menyelidiki terlebih dahulu:

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Contoh percakapan:

text
Anda: /opsx:explore

AI:  Apa yang ingin Anda jelajahi?

Anda: Saya ingin meningkatkan kinerja muat halaman tetapi saya tidak yakin
     di mana hambatan utamanya.

AI:  Biarkan saya membantu menyelidiki...
     [Menganalisis ukuran bundel, mengidentifikasi kueri lambat, meninjau
     pola render komponen]

     Saya menemukan tiga hambatan utama:
     1. Gambar besar yang tidak dioptimalkan
     2. Pengambilan data sinkron di ProductList
     3. Render ulang dari perubahan konteks

     Mana yang ingin Anda tangani terlebih dahulu?

Anda: Mari kita selesaikan masalah pengambilan data.

Anda: /opsx:new optimize-product-list-fetching

AI:  Perubahan dibuat. Siap membuat: proposal

Anda: /opsx:continue

AI:  Membuat proposal berdasarkan eksplorasi kita...
     [Menulis proposal yang menggabungkan wawasan investigasi]

     Siap membuat: specs, design
     Mana yang ingin Anda lanjutkan selanjutnya?

Anda: /opsx:continue

AI:  Membuat specs...

Terbaik untuk: Optimasi kinerja, debugging, keputusan arsitektural, persyaratan yang tidak jelas.

Perubahan Paralel ​

Bekerja pada beberapa perubahan sekaligus:

text
Perubahan A: /opsx:new ──► /opsx:ff ──► /opsx:apply (sedang berlangsung)
                                         │
                                    pergantian konteks
                                         │
Perubahan B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Contoh percakapan:

text
Anda: Saya sedang mengerjakan add-dark-mode tapi terseret ke perbaikan bug

Anda: /opsx:new fix-login-redirect

AI:  Dibuat openspec/changes/fix-login-redirect/

Anda: /opsx:ff

AI:  ✓ Artefak perencanaan dibuat

Anda: /opsx:apply

AI:  Bekerja pada fix-login-redirect...
     [Mengimplementasikan perbaikan]
     Semua tugas selesai!

Anda: /opsx:archive

AI:  ✓ Diarsipkan fix-login-redirect

Anda: Mari kembali ke mode gelap

Anda: /opsx:apply add-dark-mode

AI:  Melanjutkan add-dark-mode...
     Melanjutkan pada tugas 2.3: Perbarui Header...

Terbaik untuk: Alur kerja paralel, gangguan mendesak, kolaborasi tim.

Ketika Anda memiliki beberapa perubahan yang selesai, gunakan /opsx:bulk-archive:

text
Anda: /opsx:bulk-archive

AI:  Ditemukan 3 perubahan yang selesai:
     - add-dark-mode (semua tugas selesai)
     - fix-login-redirect (semua tugas selesai)
     - update-footer (semua tugas selesai)

     Memeriksa konflik spesifikasi...
     ⚠ add-dark-mode dan update-footer keduanya menyentuh specs/ui/

     Memeriksa basis kode untuk menyelesaikan...
     Kedua perubahan telah diimplementasikan. Akan diterapkan secara kronologis.

     Arsipkan semua 3 perubahan?

Anda: Ya

AI:  ✓ Diarsipkan add-dark-mode
     ✓ Diarsipkan fix-login-redirect
     ✓ Diarsipkan update-footer
     Spesifikasi digabungkan secara berurutan: add-dark-mode → update-footer

Arsip massal mendeteksi ketika beberapa perubahan menyentuh spesifikasi yang sama dan menyelesaikan konflik dengan memeriksa apa yang sebenarnya diimplementasikan.

Menyelesaikan Perubahan ​

Alur penyelesaian yang direkomendasikan:

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              memvalidasi          meminta untuk menyinkronkan
              implementasi         jika diperlukan

Verifikasi: Periksa Pekerjaan Anda ​

/opsx:verify memvalidasi implementasi terhadap artefak Anda di tiga dimensi:

text
Anda: /opsx:verify

AI:  Memverifikasi add-auth...

     KELENGKAPAN
     ✓ Semua 12 tugas di tasks.md dicentang
     ✓ Semua persyaratan di specs memiliki kode yang sesuai
     ⚠ Skenario "Timeout sesi setelah tidak aktif" tidak diuji

     KEBENARAN
     ✓ Implementasi sesuai dengan niat spesifikasi
     ✓ Kasus tepi dari skenario ditangani
     ✓ Status kesalahan sesuai dengan definisi spesifikasi

     KOHERENSI
     ✓ Keputusan desain tercermin dalam struktur kode
     ✓ Konvensi penamaan konsisten dengan design.md
     ⚠ Desain menyebutkan "berbasis peristiwa" tetapi implementasi menggunakan polling

     RINGKASAN
     ─────────────────────────────
     Masalah kritis: 0
     Peringatan: 2
     Siap diarsipkan: Ya (dengan peringatan)

     Rekomendasi:
     1. Tambahkan tes untuk skenario timeout sesi
     2. Pertimbangkan untuk melakukan refactoring ke berbasis peristiwa seperti yang dirancang, atau perbarui design.md

Apa yang diperiksa oleh verifikasi:

DimensiApa yang divalidasi
KelengkapanSemua tugas selesai, semua persyaratan diimplementasikan, skenario tercakup
KebenaranImplementasi sesuai dengan niat spesifikasi, kasus tepi ditangani
KoherensiKeputusan desain tercermin dalam kode, pola konsisten

Verifikasi tidak akan menghalangi arsip, tetapi akan menyoroti masalah yang mungkin ingin Anda atasi terlebih dahulu.

Arsip: Finalisasi Perubahan ​

/opsx:archive menyelesaikan perubahan dan memindahkannya ke arsip:

text
Anda: /opsx:archive

AI:  Mengarsipkan add-auth...

     Status artefak:
     ✓ proposal.md ada
     ✓ specs/ ada
     ✓ design.md ada
     ✓ tasks.md ada (12/12 tugas selesai)

     Spesifikasi delta: Belum disinkronkan ke utama
     → Apakah Anda ingin menyinkronkan sekarang?

Anda: Ya

AI:  ✓ Spesifikasi disinkronkan ke openspec/specs/auth/spec.md
     ✓ Dipindahkan ke openspec/changes/archive/2025-01-24-add-auth/

     Perubahan berhasil diarsipkan.

Arsip akan meminta jika spesifikasi belum disinkronkan. Ini tidak akan menghalangi tugas yang belum selesai, tetapi akan memberi Anda peringatan.

Kapan Menggunakan Apa ​

/opsx:ff vs /opsx:continue ​

SituasiGunakan
Persyaratan jelas, siap membangun/opsx:ff
Mengeksplorasi, ingin meninjau setiap langkah/opsx:continue
Ingin mengiterasi pada proposal sebelum specs/opsx:continue
Tekanan waktu, perlu bergerak cepat/opsx:ff
Perubahan kompleks, ingin kendali/opsx:continue

Aturan praktis: Jika Anda dapat menggambarkan cakupan penuh di awal, gunakan /opsx:ff. Jika Anda sedang memahaminya sambil berjalan, gunakan /opsx:continue.

Kapan Memperbarui vs Mulai Ulang ​

Pertanyaan umum: kapan memperbarui perubahan yang ada diperbolehkan, dan kapan Anda harus memulai yang baru?

Perbarui perubahan yang ada ketika:

  • Niat yang sama, eksekusi yang disempurnakan
  • Cakupan menyempit (MVP dulu, sisanya nanti)
  • Koreksi berbasis pembelajaran (basis kode tidak seperti yang diharapkan) Penyesuaian desain berdasarkan penemuan implementasi

Mulai perubahan baru ketika:

  • Niat berubah secara fundamental
  • Cakupan meledak menjadi pekerjaan yang sama sekali berbeda
  • Perubahan asli dapat ditandai "selesai" secara mandiri
  • Tambahan akan membingungkan daripada memperjelas
text
                     ┌─────────────────────────────────────┐
                     │     Apakah ini pekerjaan yang sama?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Niat yang sama?      >50% tumpang tindih?      Dapatkah asal
          Masalah yang sama?     Cakupan yang sama?        dapat "selesai" tanpa
                 │                  │          perubahan ini?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YA                TIDAK YA           TIDAK  TIDAK              YA
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    PERBARUI            BARU  PERBARUI       BARU  PERBARUI          BARU

Contoh: "Tambahkan mode gelap"

  • "Perlu juga mendukung tema kustom" → Perubahan baru (cakupan meledak)
  • "Deteksi preferensi sistem lebih sulit dari yang diharapkan" → Perbarui (niat yang sama)
  • "Mari kirimkan toggle dulu, tambahkan preferensi nanti" → Perbarui lalu arsip, lalu perubahan baru

Praktik Terbaik ​

Pertahankan Perubahan yang Fokus ​

Satu unit kerja logis per perubahan. Jika Anda melakukan "tambahkan fitur X dan juga refactor Y", pertimbangkan untuk membaginya menjadi dua perubahan terpisah.

Mengapa ini penting:

  • Lebih mudah untuk ditinjau dan dipahami
  • Riwayat arsip lebih bersih
  • Dapat dirilis secara independen
  • Rollback lebih sederhana jika diperlukan

Gunakan /opsx:explore untuk Kebutuhan yang Tidak Jelas ​

Sebelum berkomitmen pada suatu perubahan, jelajahi ruang masalah terlebih dahulu:

text
You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

Eksplorasi memperjelas pemikiran sebelum Anda membuat artefak.

Verifikasi Sebelum Mengarsipkan ​

Gunakan /opsx:verify untuk memeriksa apakah implementasi sesuai dengan artefak:

text
You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

Mendeteksi ketidakcocokan sebelum Anda menutup perubahan.

Beri Nama Perubahan dengan Jelas ​

Nama yang baik membuat openspec list berguna:

text
Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Referensi Cepat Perintah ​

Untuk detail dan opsi perintah lengkap, lihat Commands.

PerintahTujuanKapan Digunakan
/opsx:proposeBuat perubahan + artefak perencanaanJalur default cepat (profil core)
/opsx:explorePikirkan ide bersama AIMulai di sini jika ragu: kebutuhan tidak jelas, investigasi, membandingkan opsi
/opsx:newMulai scaffold perubahanMode diperluas, kontrol artefak eksplisit
/opsx:continueBuat artefak berikutnyaMode diperluas, pembuatan artefak langkah demi langkah
/opsx:ffBuat semua artefak perencanaanMode diperluas, cakupan jelas
/opsx:applyImplementasikan tugasSiap menulis kode
/opsx:verifyValidasi implementasiMode diperluas, sebelum mengarsipkan
/opsx:syncGabungkan delta specsMode diperluas, opsional
/opsx:archiveSelesaikan perubahanSemua pekerjaan selesai
/opsx:bulk-archiveArsipkan beberapa perubahanMode diperluas, pekerjaan paralel

Langkah Berikutnya ​

  • Writing Good Specs - Bagaimana kebutuhan dan skenario yang kuat seharusnya terlihat, dan cara menentukan ukuran perubahan yang tepat
  • Reviewing a Change - Tinjauan dua menit pada rencana yang sudah dibuat sebelum menulis kode
  • OpenSpec on a Team - Bagaimana perubahan cocok dengan cabang dan pull request
  • Commands - Referensi perintah lengkap dengan opsi
  • Concepts - Penjelasan mendalam tentang specs, artefak, dan skema
  • Customization - Buat alur kerja kustom