Quickstart

Perubahan pertama Anda, dari ide hingga diarsipkan, dalam proyek baru atau yang sudah ada.

Sebelum memulai, Anda memerlukan CLI di mesin Anda (Instalasi) dan OpenSpec yang diinisialisasi di proyek Anda (Siapkan proyek Anda).

Mulai dari proyek kosong

Anda dapat memulai tanpa stack yang dipilih atau arsitektur lengkap. Inisialisasi OpenSpec di folder proyek Anda, lalu minta agent Anda untuk menjelajahi opsi bersama Anda. Di AI chat Anda:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

Tentukan apa yang dibutuhkan oleh perubahan pertama dan biarkan pilihan arsitektur selanjutnya tetap terbuka. Minta agent Anda untuk mengusulkan perubahan tersebut, lalu ikuti langkah-langkah di bawah. Anda dapat meninjau ulang arsitektur saat proyek berkembang.

Gambaran loop

Setiap perubahan melewati lima langkah yang sama: Anda memikirkan ide bersama agent Anda, agent menyusun rencana, Anda mengoreksi rencana sebelum kode apa pun ada, agent membangun dari rencana tersebut, dan pengarsipan memperbarui spec Anda dengan apa yang telah dirilis.

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

Setiap prompt di bawah ini dimasukkan ke AI chat Anda, tempat yang sama di mana Anda meminta kode. Contoh-contoh menggunakan bahasa sederhana agar berfungsi di berbagai alat. Anda juga dapat memanggil skill secara langsung; sintaksnya bervariasi per alat (alat yang didukung).

Langkah 1: Explore

Pikirkan ide tersebut bersama agent Anda sebelum meminta rencana. Di AI chat Anda:

Help me explore how rate limiting should work in this app.

Explore adalah mode berpikir. Agent menyelidiki codebase Anda, mengajukan pertanyaan yang penting, membuat sketsa opsi, dan menantang asumsi. Agent tidak pernah menulis kode. Agent tidak menulis apa pun kecuali Anda memintanya untuk menangkap apa yang Anda putuskan, atau mengatakan ya saat ditawarkan. Hasilnya adalah ide yang lebih tajam.

Tetap di sini selama masalah membutuhkannya. Ketika bentuknya terasa tepat, serahkan:

Propose the change we just discussed.

Baris itu memulai propose untuk Anda, membawa semua yang telah Anda sepakati. Lewati prompt pertama di langkah 2.

Langkah 2: Propose

Propose mengubah ide menjadi rencana yang dapat ditinjau. Datang dari explore, prosesnya sudah berjalan. Mulai dari nol, ketika perubahan sudah jelas di kepala Anda, tanyakan langsung. Di AI chat Anda:

Propose a change to add rate limiting.

Agent mengajukan pertanyaan yang diperlukan, lalu menulis folder perubahan:

openspec/changes/add-rate-limiting/
├── proposal.md    mengapa, dan apa yang berubah
├── specs/         apa arti "selesai", sebagai persyaratan yang dapat diuji
├── design.md      keputusan teknis (hanya ketika perubahan memerlukannya)
└── tasks.md       checklist implementasi

Belum ada kode. Propose berhenti di rencana.

Langkah 3: Tinjau dan koreksi rencana

Perbaiki rencana selagi masih berupa kata-kata dan belum ada yang dibangun. Baca dalam urutan ini:

• proposal.md: apakah ini masalah yang tepat, dengan ukuran yang tepat?
• specs/: bacaan dengan nilai tertinggi. Apakah Anda menerima persyaratan ini sebagai selesai?
• tasks.md: apakah tasks mencakup specs, dan tidak lebih?

Untuk memperbaiki sesuatu, keduanya berfungsi:

• Edit file sendiri. Artifact adalah markdown biasa, dan file adalah rencananya.
• Beri tahu agent Anda apa yang salah ("spec tidak mencakup kasus yang tidak diautentikasi"). Agent merevisi artifact.

Langkah 4: Apply

Apply mengubah rencana menjadi kode. Mulai sesi chat baru, karena implementasi berjalan lebih baik dengan context window yang bersih. Di AI chat Anda:

Apply the add-rate-limiting change.

Agent membaca folder perubahan, lalu mengerjakan tasks.md, mencentang setiap task saat selesai.

• Terputus, atau kehabisan context? Buka sesi baru dan minta agent apply lagi. Agent melanjutkan dari task pertama yang belum dicentang.
• Rencana ternyata salah? Perbaiki artifact (dengan cara apa pun dari langkah 3), lalu lanjutkan apply.
• Progres berada di kotak centang tasks.md. Tidak ada state tersembunyi.

Langkah 5: Archive

Pengarsipan melakukan dua hal: memperbarui spec utama Anda dengan persyaratan perubahan, dan memindahkan folder perubahan ke folder archive (di /openspec/changes/archive/*).

Ketika setiap kotak di tasks.md sudah dicentang, di AI chat Anda:

Archive the add-rate-limiting change.

Ikuti langkah-langkah yang dilakukan pengarsipan:

## Perubahan yang selesai
> Implementasi selesai. Delta spec (apa yang ditambahkan oleh perubahan ini) masih berada di dalam folder perubahan; specs/ belum mengetahui rate limiting.
  openspec/
  ├── specs/                                   (belum ada spec rate-limiting)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         setiap kotak dicentang
          └── specs/
              └── rate-limiting/
                  └── spec.md                  delta: persyaratan yang DITAMBAHKAN

## Persyaratan masuk ke specs/
> Setiap persyaratan di delta masuk ke spec utama: yang ditambahkan akan ditambahkan, yang dimodifikasi menggantikan versi lamanya. Kapabilitas baru mendapatkan file spec baru.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          mendapatkan "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  delta, sumber penggabungan

## Folder berpindah ke archive/
> Seluruh folder perubahan, termasuk delta, berpindah ke archive dengan prefix tanggal. Tidak ada yang dihapus.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs menjelaskan sistem sebagaimana dibangun
> changes/ bersih untuk perubahan berikutnya. specs/ adalah source of truth untuk apa yang dilakukan sistem; archive/ adalah riwayat bagaimana sistem sampai di sana.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          spec sebagaimana dibangun
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git adalah hal terpisah. Commit folder perubahan bersama kode, dan tidak ada lagi yang berubah dari workflow Anda.

Simpan atau pangkas perubahan yang diarsipkan

openspec/changes/archive/ menyimpan proposal, design, tasks, dan delta untuk setiap perubahan yang selesai. Dalam alur archive di atas, delta telah memperbarui openspec/specs/.

• Simpan seluruh folder perubahan ketika Anda ingin catatan mandiri di checkout saat ini.
• Hapus folder specs/ dari perubahan yang diarsipkan ketika Git adalah riwayat spec Anda. Commit archive terlebih dahulu, lalu hapus openspec/changes/archive/<change>/specs/. Proposal, design, dan tasks tetap ada di checkout. openspec validate --archived tetap berfungsi karena memeriksa penyelesaian task, bukan delta yang diterapkan.
• Hapus seluruh folder perubahan hanya ketika Anda tidak lagi memerlukan proposal, design, atau riwayat task-nya di checkout. Spec saat ini tidak berubah, tetapi openspec validate --archived dan pencarian di checkout tidak lagi mencakup perubahan tersebut.

WARNING

Simpan commit archive di riwayat repository Anda jika Anda ingin Git menyimpan file yang dihapus. Squashing commit archive dan cleanup bersama-sama menghapus snapshot perantara tersebut.

OpenSpec tidak memangkas perubahan yang diarsipkan secara otomatis atau menyediakan pengaturan retensi.

Langkah selanjutnya

• Delta specs: cara menulis perubahan perilaku dalam delta spec.
• Profiles: workflow opsional di luar set inti (verifikasi sebelum archive, perencanaan inkremental).

Panduan lanjutan

Belum ditulis; panduan yang rencananya akan kami tambahkan:

• Prototype first: lakukan spike kode sebelum spec apa pun, lalu isi proposal dari apa yang diajarkan oleh prototype.
• Building iteratively: urutan perubahan kecil alih-alih satu proposal besar.
• Revising an implemented change: rencana perlu digeser lagi setelah apply, tetapi perubahan belum di-merge atau diarsipkan.