OpenSpec

Skonfiguruj swój projekt ​

Dodaj OpenSpec do projektu: uruchom init, zobacz, co init zapisał, i dostosuj to.

Wybierz, gdzie znajduje się OpenSpec ​

  • W swoim repo (domyślnie): specyfikacje i zmiany znajdują się obok kodu, którego dotyczą, i są wersjonowane razem z nim. Reszta tej strony podąża tą ścieżką.
  • W sklepie: osobne repozytorium planistyczne współdzielone przez repozytoria, z których korzysta, dla konfiguracji wielorepozytorowych lub całkowitego wyjęcia planowania poza repozytorium. Sklepy (beta) opisuje, kiedy warto to zrobić i jak je skonfigurować.

Zainicjuj swój projekt ​

Z zainstalowanym interfejsem CLI (Instalacja), uruchom init w katalogu głównym projektu. W terminalu:

bash
cd <your-project>
openspec init

Init pyta, jakich narzędzi AI używasz, zapisuje pliki przepływów pracy dla wybranych przez Ciebie i raportuje, co otrzymałeś:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Uruchom ponownie IDE, aby nowe komendy weszły w życie.

Ponowne uruchomienie init jest bezpieczne:

  • Narzędzia, które już skonfigurowałeś, wypisują Refreshed zamiast Created.
  • Ponowne uruchomienie init z wybranym nowym narzędziem dodaje to narzędzie.
  • Flaga --tools pomija selektor (dokumentacja CLI).

Migracja istniejącego project.md ​

Init nie kopiuje starszego pliku openspec/project.md do config.yaml. Zostawia plik i drukuje prośbę o migrację wspomaganą przez AI.

W czacie z AI:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Przejrzyj config.yaml, a następnie usuń project.md, gdy będziesz gotowy.

Co instaluje init ​

Uruchomienie init tworzy dwie rzeczy w Twoim projekcie:

  • Folder openspec/ w katalogu głównym repozytorium
  • Pliki przepływów pracy (umiejętności i komendy) dodane do folderu narzędzia AI (.agents/, .claude/, itd.)

Zatwierdź wszystko jak resztę kodu źródłowego. Init nie zmienia niczego innego w Twoim repozytorium (jeśli znajdzie pozostałości po starszej wersji OpenSpec, pyta przed ich usunięciem).

Folder openspec/ ​

Każdy artefakt OpenSpec znajduje się tutaj, w katalogu głównym projektu. Oto jak to wygląda:

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

Konfiguracja projektu opisuje config.yaml.

Pliki przepływów pracy (umiejętności i komendy) ​

To przepływy pracy OpenSpec, akcje, których będziesz używać podczas pracy. Oto zainstalowane umiejętności w udostępnionym folderze .agents, którego używają większość narzędzi:

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

To domyślny zestaw plus dwa opcjonalne przepływy pracy. Profile wymienia wszystkie dwanaście.

Domyślnie każdy przepływ pracy instaluje się w dwóch formach:

  • Umiejętność (openspec-apply-change): instrukcje, które agent pobiera samodzielnie, gdy poprosisz o wykonanie pracy.
  • Komenda (/opsx:apply w Claude Code): wpisany punkt wejścia dla tego samego przepływu pracy, pod krótszą nazwą.

Oba są funkcjonalnie identyczne. Umiejętność i komenda przepływu pracy niosą te same instrukcje.

Dlaczego dwa: komendy pojawiły się pierwsze, a każde narzędzie nazywa je po swojemu. Umiejętności to nowszy standard współdzielony między narzędziami, ale nie każde narzędzie może wywołać umiejętność bezpośrednio, więc komendy pozostają jako punkt wejścia dla tych narzędzi.

Niektóre narzędzia instalują wyłącznie w formie umiejętności. Gdzie narzędzie uruchamia umiejętności bezpośrednio, init pomija komendy i o tym informuje (Commands skipped for: codex (uses skills)).

Wolimy umiejętności i spodziewamy się, że ostatecznie wycofamy komendy.

Zmień, co zostanie zainstalowane ​

Interaktywny selektor zmienia formę dostarczania i zestaw przepływów pracy (Profile). W terminalu:

bash
openspec config profile

Oto przełączanie wyłącznie na umiejętności:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Odpowiedź tak stosuje to do bieżącego projektu natychmiast. Pozostałe projekty pobiorą to przy następnym openspec update. Ustawienie jest globalne, na maszynę.

Claude Code nie wyświetla przepływów pracy ​

Claude Code ładuje przepływy pracy OpenSpec z jednej lub obu tych ścieżek projektu, w zależności od ustawienia dostarczania:

  • Umiejętności: .claude/skills/openspec-*/SKILL.md
  • Komendy: .claude/commands/opsx/<id>.md

Jeśli pliki brakują, odśwież projekt. W terminalu:

bash
openspec update

Jeśli pliki komend istnieją, ale /opsx: nie wyświetla komend OpenSpec, zaktualizuj Claude Code i uruchom go ponownie. Jeśli komendy nadal nie ładują się, włącz również umiejętności. W terminalu:

bash
openspec config set delivery both
openspec update

Uruchom ponownie Claude Code, a następnie uruchom /openspec-propose w jego czacie. Jeśli brakuje tylko niektórych przepływów pracy, zmień swój profil.

Konfiguracja zakończona. Szybki start poprowadzi Cię przez pierwszą zmianę.