Szybki start
Twoja pierwsza zmiana, od pomysłu do archiwizacji, w nowym lub istniejącym projekcie.
Zanim zaczniesz, potrzebujesz CLI na swojej maszynie (Instalacja) i zainicjowanego OpenSpec w Twoim projekcie (Skonfiguruj swój projekt).
Rozpocznij od pustego projektu
Możesz zacząć bez wybranego stacka lub kompletnej architektury. Zainicjuj OpenSpec w folderze projektu, a następnie poproś swojego agenta, aby razem z Tobą zbadane były dostępne opcje. W czacie AI:
Pomóż mi zbadać tracker zadań od podstaw. Nie wybrałem stacka. Porównaj opcje i pomóż mi wybrać pierwsze zachowanie do zbudowania.Zdecyduj, czego wymaga pierwsza zmiana, i pozostaw późniejsze wybory architektoniczne otwarte. Poproś agenta o zaproponowanie tej jednej zmiany, a następnie wykonaj poniższe kroki. Architekturę możesz rewizytować w miarę rozwoju projektu.
Pętla w skrócie
Każda zmiana przechodzi przez te same pięć kroków: przemyślisz pomysł z agentem, on przygotowuje plan, Ty korygujesz plan zanim powstanie jakikolwiek kod, agent buduje na jego podstawie, a archiwizacja aktualizuje Twoje specyfikacje o to, co zostało dostarczone.
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
Każdy poniższy prompt trafia do Twojego czatu AI, w to samo miejsce, gdzie prosisz o kod. Przykłady używają prostego języka, aby działać w różnych narzędziach. Możesz również wywołać umiejętność bezpośrednio; składnia różni się w zależności od narzędzia (obsługiwane narzędzia).
Krok 1: Explore
Przemyśl pomysł z agentem, zanim poprosisz o plan. W czacie AI:
Pomóż mi zbadać, jak powinno działać ograniczanie zapytań w tej aplikacji.Explore to tryb myślenia. Agent analizuje Twoją bazę kodu, zadaje istotne pytania, szkicuje opcje i podważa założenia. Nigdy nie pisze kodu. Nie pisze niczego innego, chyba że poprosisz go o odnotowanie tego, co zdecydowaliście, lub powiesz tak, gdy zaproponuje. Efektem jest ostrzejszy pomysł.
Zostań tutaj tak długo, jak potrzebuje tego problem. Kiedy kształt wydaje się odpowiedni, przejdź dalej:
Zaproponuj zmianę, o której właśnie rozmawialiśmy.Ta linia uruchamia propose dla Ciebie, przenosząc wszystko, co ustaliliście. Pomiń pierwszy prompt w kroku 2.
Krok 2: Propose
Propose zamienia pomysł w plan podlegający przeglądowi. Wychodząc z explore, już działa. Zaczynamy na zimno, gdy zmiana jest jasna w Twojej głowie, zapytaj bezpośrednio. W czacie AI:
Zaproponuj zmianę dodającą ograniczanie zapytań.Agent zada wszystkie potrzebne pytania, a następnie zapisze folder zmiany:
openspec/changes/add-rate-limiting/
├── proposal.md dlaczego i co się zmienia
├── specs/ co oznacza "gotowe", jako testowalne wymagania
├── design.md decyzje techniczne (tylko gdy zmiana tego wymaga)
└── tasks.md lista kontrolna implementacjiJeszcze brak kodu. Propose zatrzymuje się na planie.
Krok 3: Przegląd i korekta planu
Popraw plan, dopóki to jeszcze tylko słowa i nic nie zostało zbudowane. Czytaj w tej kolejności:
proposal.md: czy to właściwy problem, we właściwej skali?specs/: najbardziej wartościowa lektura. Czy zaakceptowałbyś te wymagania jako gotowe?tasks.md: czy zadania obejmują specyfikacje i nic więcej?
Aby coś poprawić, działa każda z opcji:
- Edytuj plik samodzielnie. Artefakty to zwykły markdown, a pliki są planem.
- Powiedz agentowi, co jest nie tak ("specyfikacja nie obejmuje przypadku nieuwierzytelnionego"). On rewizuje artefakty.
Krok 4: Apply
Apply zamienia plan w kod. Rozpocznij nową sesję czatu, ponieważ implementacja idzie lepiej na czystym oknie kontekstu. W czacie AI:
Zastosuj zmianę add-rate-limiting.Agent odczytuje folder zmiany, a następnie pracuje przez tasks.md, odhaczając każde zadanie w miarę realizacji.
- Przerwane lub brak kontekstu? Otwórz nową sesję i poproś o ponowne zastosowanie. Wznawia od pierwszego nieodhaczonego zadania.
- Plan okazał się błędny? Popraw artefakty (na oba sposoby z kroku 3), a następnie kontynuuj stosowanie.
- Postęp znajduje się w polach wyboru
tasks.md. Nie ma ukrytego stanu.
Krok 5: Archive
Archiwizacja robi dwie rzeczy: aktualizuje Twoje główne specyfikacje o wymagania zmiany i przenosi folder zmiany do folderu archiwum (w /openspec/changes/archive/*).
Gdy każde pole w tasks.md jest odhaczone, w czacie AI:
Zarchiwizuj zmianę add-rate-limiting.Przejdź przez to, co robi archiwizacja:
## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
openspec/
├── specs/ (no rate-limiting spec yet)
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md every box checked
└── specs/
└── rate-limiting/
└── spec.md the delta: ADDED requirements
## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md gains "Requirement: Rate limiting"
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md the delta, source of the merge
## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
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 describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md the spec as built
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git to osobna kwestia. Zatwierdź folder zmiany razem z kodem i nic więcej w Twoim przepływie pracy się nie zmienia.
Przechowuj lub usuwaj zarchiwizowane zmiany
openspec/changes/archive/ przechowuje propozycję, projekt, zadania i deltę dla każdej zakończonej zmiany. W powyższym przepływie archiwizacji delta została już zastosowana w openspec/specs/.
- Przechowaj cały folder zmiany, gdy chcesz samodzielnego rekordu w bieżącym checkoutcie.
- Usuń folder
specs/zarchiwizowanej zmiany, gdy Git jest Twoją historią specyfikacji. Najpierw zatwierdź archiwum, a następnie usuńopenspec/changes/archive/<change>/specs/. Propozycja, projekt i zadania pozostają w checkoutcie.openspec validate --archivednadal działa, ponieważ sprawdza ukończenie zadań, a nie zastosowane delty. - Usuń cały folder zmiany tylko wtedy, gdy nie potrzebujesz już jego propozycji, projektu ani historii zadań w checkoutcie. Bieżące specyfikacje się nie zmieniają, ale
openspec validate --archivedi przeszukiwanie checkoutu nie obejmują już tej zmiany.
WARNING
Zachowaj zatwierdzenie archiwum w historii repozytorium, jeśli chcesz, aby Git zachował usunięte pliki. Scalenie zatwierdzeń archiwum i porządkowania usuwa ten pośredni migot.
OpenSpec nie usuwa automatycznie zarchiwizowanych zmian ani nie udostępnia ustawienia przechowywania.
Późniejsze kroki
- Delta specs: jak pisać zmiany zachowania w specyfikacji delty.
- Profile: opcjonalne przepływy pracy poza podstawowym zestawem (weryfikacja przed archiwizacją, planowanie przyrostowe).
Przewodniki zaawansowane
Jeszcze nie napisane; przewodniki, które planujemy dodać:
- Najpierw prototyp: kod w wersji prototypowej przed jakąkolwiek specyfikacją, a następnie uzupełnienie propozycji na podstawie tego, czego nauczył Cię prototyp.
- Iteracyjne budowanie: sekwencja małych zmian zamiast jednej dużej propozycji.
- Rewizja zaimplementowanej zmiany: plan musi ponownie się zmienić po apply, ale zmiana nie została jeszcze scalona ani zarchiwizowana.