{dev} forge – Jak budować specyfikację w OpenSpec pod AI coding agents

Do tej pory w serii {dev} forge – How software is forged with AI rozmawialiśmy głównie o ideach:

• czym jest Spec-Driven Development,
• dlaczego promptowanie nie skaluje się w projektach,
• jak wygląda dobra specyfikacja,
• oraz dlaczego AI potrzebuje kontraktu zamiast luźnej rozmowy.

Pora więc przejść do praktyki.

W tym artykule pokażę, jak wygląda realny workflow pracy z AI w podejściu spec-driven przy użyciu OpenSpec oraz Codex CLI.

I właśnie tutaj zaczyna się najciekawsza część całego trendu.

Bo kiedy pierwszy raz zobaczysz, że AI nie pracuje już na pojedynczym promptcie, tylko na uporządkowanej specyfikacji, bardzo szybko zrozumiesz jedną rzecz:

przyszłość AI-assisted development nie wygląda jak chat. Wygląda jak pipeline specyfikacji.

Czym właściwie jest OpenSpec?

OpenSpec to lekki framework do Spec-Driven Development, którego celem jest uporządkowanie współpracy z AI coding assistantami wokół trwałych artefaktów zamiast ulotnych rozmów.

Projekt wspiera wiele narzędzi AI, między innymi:

• Codex,
• Claude Code,
• Cursor,
• GitHub Copilot,
• Gemini CLI.

OpenSpec opisuje się jako:

• open source,
• universal,
• bez API keys,
• bez MCP.

Najważniejsze jednak jest coś innego:

OpenSpec zamienia specyfikację w aktywny artefakt procesu developmentu.

Źródła:

• https://openspec.dev/
• https://github.com/Fission-AI/OpenSpec

Jak wygląda workflow OpenSpec?

Domyślny workflow wygląda mniej więcej tak:

Propose → Explore → Apply → Validate → Archive

Czyli:

• najpierw definiujesz zmianę,
• potem eksplorujesz rozwiązanie,
• następnie AI implementuje zmianę,
• na końcu walidujesz rezultat i archiwizujesz decyzję.

To jest ogromna różnica względem klasycznego „wrzuć prompt i zobacz co wyjdzie”.

OpenSpec wymusza bowiem myślenie o zmianie jako o procesie opartym o trwałe artefakty.

Instalacja OpenSpec

OpenSpec działa jako pakiet npm.

Instalacja jest bardzo prosta:

npm install -g @fission-ai/openspec@latest

Po instalacji możesz sprawdzić wersję:

openspec --version

Źródła:

• openspec.dev
• GitHub OpenSpec

Inicjalizacja projektu

Następnie przechodzisz do repozytorium projektu:

cd my-project

I uruchamiasz:

openspec init

OpenSpec skonfiguruje workflow oraz zainstaluje odpowiednie skills i komendy dla wybranego narzędzia AI.

Domyślnie aktywowany jest profil core, który zawiera workflow:

• propose
• explore
• apply
• sync
• archive

Źródło:

• supported-tools.md

OpenSpec + Codex

I tutaj robi się naprawdę ciekawie.

OpenSpec ma natywne wsparcie dla Codex.

Podczas inicjalizacji może instalować:

• skills,
• workflow commands,
• spec-driven prompts.

Dla Codex instalowane są między innymi:

.codex/skills/openspec-*/SKILL.md

oraz workflow commands:

$CODEX_HOME/prompts/opsx-*

Źródło:

• OpenSpec supported tools

Jak działają skills?

Skills to jeden z najważniejszych elementów nowoczesnego AI-assisted development.

Można je traktować jak:

• procedury operacyjne dla AI,
• specjalizowane instrukcje,
• trwałą wiedzę domenową.

Zamiast za każdym razem tłumaczyć AI:

• jak wygląda architektura projektu,
• jakie są standardy kodowania,
• jakie obowiązują reguły bezpieczeństwa,
• jakie są konwencje nazewnicze,

skills dostarczają ten kontekst automatycznie.

To właśnie tutaj zaczynamy odchodzić od „AI jako chat” w stronę „AI jako uczestnik procesu engineeringowego”.

Instalacja skills w Codex

Codex wspiera skills w bardzo podobny sposób do Claude Code.

Skills można instalować:

• globalnie,
• per projekt,
• bezpośrednio z repozytoriów.

Przykładowo Codex wykrywa skills w katalogach:

~/.codex/skills/

lub:

.codex/skills/

Codex automatycznie ładuje skills przy starcie sesji.

Źródła:

• OpenAI Codex Skills
• Codex Skills Guide

Praktyczny przykład – budowa feature’a

Załóżmy, że chcemy dodać nowy feature:

„Program lojalnościowy dla klientów premium w sklepie online”

W klasycznym prompt-driven development moglibyśmy napisać:

Dodaj loyalty program dla klientów premium.

I AI prawdopodobnie wygenerowałoby jakiś kod.

W OpenSpec zaczynamy zupełnie inaczej.

Krok 1 – Propose

Najpierw definiujemy zmianę.

Powstaje proposal zawierający:

• cel biznesowy,
• zakres,
• model domenowy,
• scenariusze,
• kontrakty API,
• edge case’y.

Przykład:

# Premium Loyalty Program

## Goal
Introduce loyalty tiers for premium customers.

## Rules
- Customer earns points per order
- Premium threshold: 1000 points
- Discount applies only to eligible categories

## API
POST /loyalty/points
GET /loyalty/status

## Edge Cases
- Refund removes points
- Expired points cannot be reused

To jest gigantyczna różnica względem pojedynczego prompta.

AI dostaje:

• intencję,
• reguły,
• kontrakt,
• granice rozwiązania.

Krok 2 – Explore

Następnie AI eksploruje rozwiązanie.

To etap, w którym:

• analizowana jest architektura,
• sprawdzane są zależności,
• identyfikowane są ryzyka.

To bardzo ważne, bo AI przestaje działać „na ślepo”.

Krok 3 – Apply

Dopiero teraz Codex przechodzi do implementacji.

I to jest moment, w którym naprawdę widać przewagę spec-driven development.

AI nie generuje już „jakiegoś rozwiązania”.

AI implementuje konkretną specyfikację.

To ogromna różnica jakościowa.

Krok 4 – Validate

Na końcu następuje walidacja:

• czy feature spełnia scenariusze,
• czy kontrakty API są poprawne,
• czy edge case’y są obsłużone.

To właśnie tutaj wraca DNA V-Modelu i BDD.

Spec nie kończy się na implementacji.

Spec definiuje również sposób walidacji.

Największa zmiana mentalna

Najciekawsze w całym OpenSpec nie jest samo narzędzie.

Najważniejsza jest zmiana sposobu myślenia.

W klasycznym AI-assisted development często wygląda to tak:

Human → Prompt → AI → Code

W podejściu spec-driven wygląda to bardziej tak:

Human → Spec → Workflow → AI → Validate → Codebase

To zupełnie inny poziom dojrzałości procesu.

Dlaczego to jest ważne?

Bo AI coding assistants są coraz lepsze.

A im lepsze są modele, tym większe znaczenie ma jakość wejścia.

Prompt może wystarczyć do:

• małego taska,
• eksperymentu,
• prototypu.

Ale jeśli chcesz budować:

• większy system,
• zespół AI-assisted developers,
• powtarzalny proces engineeringowy,
• kontrolę jakości i traceability,

to potrzebujesz czegoś więcej.

Potrzebujesz specyfikacji jako centralnego artefaktu procesu.

Podsumowanie

OpenSpec pokazuje bardzo wyraźnie, w jakim kierunku zmierza AI-assisted development.

Nie chodzi już tylko o „pisanie promptów”.

Chodzi o budowanie:

• workflowów,
• skills,
• specyfikacji,
• kontraktów,
• procesów walidacji.

I właśnie dlatego uważam, że:

przyszłość AI programming nie będzie oparta o chat.

Będzie oparta o spec-driven workflows.

A OpenSpec jest dziś jednym z najciekawszych praktycznych przykładów tego kierunku.