🪴 Brain

OpenSpec

3 min read

OpenSpec

Framework do spec-driven development, który zamienia chaotyczne sesje z AI w strukturyzowany proces z persystentnymi artefaktami. Używam go codziennie — to fundament mojego workflow z Claude Code.

Description

OpenSpec (OPSX) tworzy strukturyzowane artefakty: specyfikację zmiany, plan implementacji, delta specs. Agent wie co buduje, dlaczego i jak — zanim napisze pierwszą linijkę kodu.

Download or use

🗒️ Reasoning for

Problem: Context Window Rot

Każdy kto pracuje z Claude Code dłużej niż tydzień zna ten scenariusz — zaczynasz sesję, budujesz feature, kontekst rośnie, agent zaczyna “zapominać” wcześniejsze ustalenia. To context window rot — degradacja jakości odpowiedzi w miarę jak konwersacja się wydłuża.

Rozwiązanie

Zamiast chaotycznych sesji krok po kroku — strukturyzowane artefakty:

  • Persistent artifacts — specyfikacje żyją w repo pod version control
  • Nie tracisz kontekstu między sesjami, bo specyfikacja jest w plikach, nie w historii czatu
  • Delta specs — zmiany opisane inkrementalnie, łatwo śledzić co się zmieniło
  • Weryfikacja — po implementacji sprawdzasz, czy kod zgadza się ze specyfikacją

Im więcej czasu spędzisz na etapie przygotowania dobrej specyfikacji, tym mniej iteracji przy samej implementacji kodu. To się zwraca wielokrotnie.

🧩 Workflow

complete — poniższe na podstawie blog overview, szczegółowy workflow w OPSX Workflow

0. /opsx:explore     → brainstorming z agentem
1. /opsx:new         → tworzy change z artefaktami
2. /opsx:ff          → fast-forward przez wszystkie artefakty
3. /opsx:apply       → implementacja zadań z planu
4. /opsx:verify      → weryfikacja vs specyfikacja
5. /opsx:archive     → archiwizacja ukończonej zmiany

Faza explore to kluczowy krok, który większość osób pomija — agent odbija pomysły, dopytuje o szczegóły, proponuje podejścia. Tu zapada decyzja czy potrzebujesz pełnej specyfikacji, czy wystarczy proposal z listą zadań.

Co wyróżnia OpenSpec

  • Artefakty w repo — wszystko pod version control, wracasz do specyfikacji po tygodniu
  • Delta specs — inkrementalne opisy zmian
  • Integracja z walidacją — weryfikacja implementacji vs specyfikacja

Alternatives considered

  • Reaktywne promptowanie — działa przy małych zmianach, nie skaluje się
  • Cursor/Windsurf bez struktury — brak persistent artifacts, context loss
  • Liniowe phase-gate workflows — walczą z rzeczywistością iteracyjnej pracy

📖 Resources

📁 Brownfield: jak specs/ powstaje (nie backfilluj)

openspec init tworzy openspec/ (AGENTS.md, project.md, puste specs/ + changes/) i skille/komendy — ale nie generuje specyfikacji. To celowe. Repo wprost: “Your openspec/specs/ directory doesn’t start full and complete. It starts nearly empty and accumulates.” oraz “Resist the urge to back-fill everything.”

Model działania:

  • openspec/specs/ = źródło prawdy, ale tylko dla capabilities, które świadomie specyfikowałeś. Nie jest mapą całego repo.
  • Nietknięty obszar → agent czyta realny kod przez /opsx:explore, nie specs/.
  • Delta w changes/<id>/specs/ używa nagłówków ## ADDED / MODIFIED / REMOVED Requirements (RFC 2119 + #### Scenario: GIVEN/WHEN/THEN); archive wlewa deltę do specs/ i przenosi change do changes/archive/YYYY-MM-DD-nazwa/.
  • Chcesz baseline dla gorącego obszaru? Zrób jeden targetowany change „document current behavior” (## ADDED Requirements opisujące stan obecny) → archive. Nie hurtowo. Dla mapy całego istniejącego kodu użyj DOX — Self-Documenting AGENTS.md.

Template: tool

Graph View

Backlinks