piątek, 17 lipca 2026

Smart Home & IoT w przestrzeniach: Jak skonfigurować zestaw do słuchania muzyki z adapteru na pasywnych głośnikach?

Chciałem słuchać muzyki z adapteru i gramofonu na normalnych, pasywnych głośnikach. Sam adapter miał własne niewielkie głośniki, ale ich jakość oraz głośność były dalekie od tego, czego oczekiwałem.



Miałem już Raspberry Pi z systemem Volumio, nakładkę HiFiBerry Amp2 oraz parę pasywnych głośników. Początkowo wydawało się więc, że wystarczy podłączyć adapter do Raspberry Pi, a następnie skierować dźwięk do HiFiBerry.

Problem polegał na tym, że HiFiBerry Amp2 jest wyłącznie urządzeniem wyjściowym. Odbiera cyfrowy dźwięk z Raspberry Pi, wzmacnia go i wysyła do głośników, ale nie ma analogowego wejścia RCA, do którego można bezpośrednio podłączyć adapter lub gramofon.

Rozwiązaniem okazał się zewnętrzny interfejs audio USB Behringer UCA202.

Finalnie powstał zestaw, który może działać w dwóch trybach: jako streamer Volumio oraz jako cyfrowy most pomiędzy adapterem, gramofonem i pasywnymi głośnikami.

Co chciałem osiągnąć?

Docelowy system miał umożliwiać:

  • słuchanie muzyki z gramofonu na pasywnych głośnikach,
  • wykorzystanie HiFiBerry Amp2 jako wzmacniacza,
  • zachowanie Volumio jako odtwarzacza radia internetowego, Spotify i AirPlay,
  • przełączanie źródła bez każdorazowego logowania przez SSH,
  • sterowanie całością z prostego panelu WWW.

Architektura rozwiązania

Finalny tor sygnału wygląda następująco:

Adapter / gramofon
wyjście LINE OUT RCA
        │
        ▼
Behringer UCA202
wejście INPUT L/R
        │
        │ USB
        ▼
Raspberry Pi z Volumio
        │
        │ I2S
        ▼
HiFiBerry Amp / Amp2
        │
        │ przewody głośnikowe
        ▼
Pasywne głośniki

Raspberry Pi pełni tutaj rolę cyfrowego routera audio.

Analogowy sygnał z adapteru trafia do Behringera UCA202. Interfejs zamienia go na cyfrowe audio przesyłane przez USB. Raspberry Pi odbiera strumień za pomocą ALSA, a następnie wysyła go do HiFiBerry. HiFiBerry wzmacnia sygnał i napędza pasywne głośniki.

Najważniejszy jest podział odpowiedzialności pomiędzy urządzeniami:

  • Behringer UCA202 pełni rolę wejścia audio,
  • Raspberry Pi przekazuje i kontroluje strumień,
  • HiFiBerry Amp2 jest wyjściem audio i wzmacniaczem.

Zaciski głośnikowe HiFiBerry nie są wejściem audio. Nie wolno podłączać do nich wyjścia RCA adapteru ani gramofonu.

Potrzebny sprzęt

Element Rola
Adapter lub gramofon z LINE OUT Analogowe źródło dźwięku
Behringer UCA202 Konwersja analogowego sygnału RCA na cyfrowe audio USB
Raspberry Pi Uruchomienie Volumio, ALSA, usług systemowych i panelu sterującego
HiFiBerry Amp lub Amp2 Wyjście audio oraz wzmacniacz dla głośników pasywnych
Pasywne głośniki Docelowe odtwarzanie dźwięku
Kabel 2 × RCA Połączenie wyjścia LINE OUT adapteru z wejściem Behringera
Przewody głośnikowe Połączenie HiFiBerry z lewym i prawym głośnikiem

Podłączenie sprzętu

Adapter lub gramofon do Behringera

Wyjście LINE OUT urządzenia podłączamy do wejść Behringera UCA202:

  • biały RCA do kanału lewego L,
  • czerwony RCA do kanału prawego R,
  • przewody muszą trafić do złączy oznaczonych jako INPUT.

Następnie Behringera podłączamy przewodem USB do Raspberry Pi.

HiFiBerry do głośników

Pasywne głośniki podłączamy przewodami głośnikowymi bezpośrednio do zacisków HiFiBerry. Należy zachować poprawne przypisanie kanałów oraz polaryzację przewodów.

Przed pierwszym testem warto ustawić niski poziom głośności, a dopiero później stopniowo go zwiększać.

Konfiguracja Volumio i HiFiBerry

Po uruchomieniu Raspberry Pi panel Volumio powinien być dostępny pod adresem:

http://volumio.local

Jeżeli nazwa lokalna nie działa, należy użyć adresu IP Raspberry Pi:

http://192.z.y.z

Ten sam adres wykorzystujemy do połączenia SSH:

ssh volumio@192.z.y.z

Jeżeli SSH jest wyłączone, można je aktywować na stronie developerskiej:

http://ADRES_IP_VOLUMIO/dev

W panelu Volumio przechodzimy do:

Settings → Playback Options

Następnie ustawiamy:

  • I2S DAC: ON,
  • DAC Model: HiFiBerry Amp/Amp2 lub zgodny model,
  • Mixer Type: Hardware, jeżeli jest dostępny,
  • niski początkowy poziom głośności.

Po zapisaniu ustawień restartujemy system.

Sprawdzenie urządzeń ALSA

Przed uruchomieniem przekazywania dźwięku trzeba sprawdzić, czy system widzi wejście Behringera i wyjście HiFiBerry.

Urządzenia nagrywające wyświetlamy poleceniem:

arecord -l

Urządzenia odtwarzające:

aplay -l

W opisywanej konfiguracji urządzenia zostały wykryte jako:

Behringer UCA202:
card 5, device 0
plughw:5,0

HiFiBerry:
card 2, device 0
plughw:2,0

Składnia plughw:<card>,<device> określa numer karty i urządzenia ALSA.

Numery kart mogą zmienić się po restarcie systemu albo przepięciu urządzenia USB. Przed modyfikacją konfiguracji zawsze warto ponownie wykonać arecord -l i aplay -l.

Test HiFiBerry i głośników

Najpierw sprawdzamy sam tor wyjściowy:

amixer -c 2 sset 'Digital' 90% unmute
volumio volume 80
speaker-test -D plughw:2,0 -c 2 -t sine -f 440

Jeżeli z głośników słychać sygnał testowy, oznacza to, że:

  • HiFiBerry zostało poprawnie wykryte,
  • wzmacniacz działa,
  • głośniki są właściwie podłączone,
  • możemy przejść do testowania wejścia Behringera.

Test nagrania z adapteru lub gramofonu

Nagrywamy dziesięciosekundową próbkę:

arecord \
  -D plughw:5,0 \
  -f S16_LE \
  -r 44100 \
  -c 2 \
  -V stereo \
  -d 10 \
  /tmp/adapter.wav

Następnie odtwarzamy ją przez HiFiBerry:

aplay -D plughw:2,0 /tmp/adapter.wav

Parametr -V stereo pokazuje poziom odbieranego sygnału. Jeżeli wskaźnik reaguje podczas odtwarzania muzyki, Behringer poprawnie odbiera dźwięk.

W przypadku UCA202 program alsamixer może wyświetlić komunikat:

This sound device does not have any capture controls

Jest to normalne. Komunikat oznacza jedynie, że urządzenie nie udostępnia programowego suwaka poziomu wejścia.

Odsłuch na żywo

Po potwierdzeniu działania wejścia i wyjścia łączymy oba urządzenia prostym potokiem:

arecord \
  -D plughw:5,0 \
  -f S16_LE \
  -r 44100 \
  -c 2 \
  --buffer-time=500000 \
| aplay \
  -D plughw:2,0 \
  -f S16_LE \
  -r 44100 \
  -c 2 \
  --buffer-time=500000

arecord odbiera dźwięk z Behringera, a aplay przekazuje go do HiFiBerry.

W tym momencie muzyka z adapteru powinna być słyszalna na pasywnych głośnikach.

Usługa systemd dla wejścia audio

Ręczna komenda działa tylko do chwili zamknięcia terminala. Dlatego tworzymy usługę systemową:

sudo nano /etc/systemd/system/turntable.service

Zawartość pliku:

[Unit]
Description=Turntable line-in from Behringer UCA202 to HiFiBerry
After=sound.target
Wants=sound.target

[Service]
Type=simple
User=volumio
Group=audio
ExecStart=/bin/bash -c 'arecord -D plughw:5,0 -f S16_LE -r 44100 -c 2 --buffer-time=500000 | aplay -D plughw:2,0 -f S16_LE -r 44100 -c 2 --buffer-time=500000'
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Przeładowujemy konfigurację:

sudo systemctl daemon-reload

Usługę uruchamiamy poleceniem:

sudo systemctl start turntable.service

Status sprawdzamy przez:

sudo systemctl status turntable.service

Konflikt pomiędzy adapterem a Volumio

Podczas działania potoku arecord | aplay proces aplay zajmuje urządzenie HiFiBerry.

Volumio próbuje korzystać z tej samej karty dźwiękowej. Może więc pojawić się błąd:

device busy

Dlatego zestaw działa w dwóch rozłącznych trybach:

Tryb Aktywne źródło Zatrzymane procesy
Adapter ON Behringer → Raspberry Pi → HiFiBerry Volumio i MPD
Volumio ON Radio, Spotify lub AirPlay turntable.service, arecord i aplay

Usługa wejścia audio nie powinna uruchamiać się automatycznie przy starcie:

sudo systemctl disable turntable.service

Skrypt uruchamiający adapter

sudo nano /usr/local/bin/gramofon-on
#!/bin/bash

volumio stop 2>/dev/null || true
systemctl stop mpd 2>/dev/null || true
systemctl stop turntable.service 2>/dev/null || true

pkill arecord 2>/dev/null || true
pkill aplay 2>/dev/null || true

amixer -c 2 sset 'Digital' 90% unmute 2>/dev/null || true
volumio volume 80 2>/dev/null || true

systemctl start turntable.service

exit 0

Skrypt przywracający Volumio

sudo nano /usr/local/bin/gramofon-off
#!/bin/bash

systemctl stop turntable.service 2>/dev/null || true

pkill arecord 2>/dev/null || true
pkill aplay 2>/dev/null || true

sleep 1

systemctl restart mpd 2>/dev/null || true

sleep 2

volumio vrestart 2>/dev/null \
  || systemctl restart volumio.service 2>/dev/null \
  || true

sleep 5

volumio volume 80 2>/dev/null || true

exit 0

Skrypt sprawdzający status

sudo nano /usr/local/bin/gramofon-status
#!/bin/bash

echo "=== turntable.service ==="
systemctl status turntable.service --no-pager -l || true

echo ""
echo "=== arecord / aplay ==="
ps -ef | egrep 'arecord|aplay' | grep -v grep || true

echo ""
echo "=== audio users ==="
fuser -v /dev/snd/* 2>/dev/null || true

exit 0

Ustawiamy prawa:

sudo chown root:root \
  /usr/local/bin/gramofon-on \
  /usr/local/bin/gramofon-off \
  /usr/local/bin/gramofon-status

sudo chmod 755 \
  /usr/local/bin/gramofon-on \
  /usr/local/bin/gramofon-off \
  /usr/local/bin/gramofon-status

Panel WWW do przełączania trybów

Logowanie przez SSH za każdym razem byłoby niewygodne. Dlatego powstał prosty panel WWW działający na porcie 8090.

Panel udostępnia trzy akcje:

  • Gramofon ON – uruchamia wejście z Behringera,
  • Gramofon OFF / Volumio ON – przywraca streaming,
  • Status – pokazuje procesy korzystające z urządzeń audio.

Panel jest dostępny pod adresem:

http://ADRES_IP_VOLUMIO:8090

Przykładowo:

http://192.168.1.250:8090

Panel powinien być dostępny wyłącznie w sieci domowej. Portu 8090 nie należy wystawiać bezpośrednio do internetu.

Minimalne uprawnienia sudo

Panel działa jako użytkownik volumio, ale skrypty sterujące usługami wymagają uprawnień administratora.

Zamiast uruchamiać cały serwer Node.js jako root, nadajemy użytkownikowi możliwość wykonywania tylko konkretnych skryptów.

sudo visudo -f /etc/sudoers.d/zz_turntable_web

Dodajemy:

Cmnd_Alias TURNTABLE_CMDS = /usr/local/bin/gramofon-on, /usr/local/bin/gramofon-off, /usr/local/bin/gramofon-status
volumio ALL=(root) NOPASSWD: TURNTABLE_CMDS

Następnie:

sudo chown root:root /etc/sudoers.d/zz_turntable_web
sudo chmod 440 /etc/sudoers.d/zz_turntable_web
sudo visudo -c

Reguły testujemy poleceniami:

sudo -k
sudo -n /usr/local/bin/gramofon-status

sudo -k
sudo -n /usr/local/bin/gramofon-on

sudo -k
sudo -n /usr/local/bin/gramofon-off

Najczęstsze problemy

Volumio nie działa przez volumio.local

Należy użyć adresu IP:

ssh volumio@192.168.1.250
http://192.168.1.250
http://192.168.1.250:8090

Brak capture controls w Behringerze

W przypadku UCA202 jest to normalne. Wejście testujemy przez arecord, a nie suwaki w alsamixer.

Volumio nie gra po wyłączeniu adapteru

sudo systemctl stop turntable.service
sudo pkill arecord 2>/dev/null
sudo pkill aplay 2>/dev/null
sudo systemctl restart mpd 2>/dev/null
volumio vrestart 2>/dev/null \
  || sudo systemctl restart volumio.service

Dźwięk z adapteru jest bardzo cichy

Należy sprawdzić:

  • czy używane jest wyjście LINE OUT,
  • czy RCA są podłączone do wejścia INPUT Behringera,
  • czy poziom wejścia reaguje w arecord -V stereo,
  • czy HiFiBerry poprawnie odtwarza sygnał testowy,
  • czy regulator głośności adapteru wpływa na LINE OUT.

Procesy arecord lub aplay nadal działają

ps -ef | egrep 'arecord|aplay' | grep -v grep
sudo fuser -v /dev/snd/*
sudo pkill arecord 2>/dev/null
sudo pkill aplay 2>/dev/null

Czego nauczył mnie ten projekt?

Samo przekazanie dźwięku z Behringera do HiFiBerry można uruchomić jedną komendą. To jednak nie wystarczy, jeżeli zestaw ma być wygodny w codziennym użyciu.

Trzeba dodatkowo rozwiązać kilka typowo systemowych problemów:

  • wykrywanie urządzeń audio,
  • zarządzanie dostępem do współdzielonej karty dźwiękowej,
  • kontrolowanie procesów,
  • automatyzację za pomocą systemd,
  • ograniczenie uprawnień administratora,
  • udostępnienie prostego interfejsu użytkownika.

Mały domowy projekt audio okazał się więc dobrym przykładem integracji sprzętu, Linuksa, usług systemowych oraz prostej aplikacji webowej.

Podsumowanie

Finalnie powstał system pozwalający korzystać z tych samych pasywnych głośników zarówno podczas słuchania muzyki z adapteru lub gramofonu, jak i podczas streamowania przez Volumio.

Tor dla źródła analogowego wygląda następująco:

Adapter lub gramofon
→ Behringer UCA202
→ Raspberry Pi
→ HiFiBerry Amp2
→ pasywne głośniki

Volumio pozostaje natomiast źródłem radia internetowego, Spotify oraz AirPlay.

Przełączanie pomiędzy źródłami odbywa się z prostego panelu WWW, bez ręcznego logowania przez SSH.

Najważniejsza rekomendacja: w autostarcie powinien działać tylko panel WWW. Usługę przekazującą dźwięk z adapteru uruchamiamy dopiero w momencie wybrania trybu gramofonu.

poniedziałek, 22 czerwca 2026

{dev} forge - Jak pisać specyfikacje pod AI?

Jednym z największych nieporozumień ery AI-assisted development jest przekonanie, że wystarczy nauczyć się pisać lepsze prompty.

Przez ostatnie dwa lata internet zalały poradniki o prompt engineeringu:

  • jak pisać prompty,
  • jak używać odpowiednich słów,
  • jak budować role,
  • jak poprawnie instruować modele.

To wszystko jest przydatne.

Ale w większych projektach problem szybko przestaje dotyczyć promptów.

Problemem staje się jakość specyfikacji.



Bo niezależnie od tego, czy używasz Codex, Claude Code, Cursor, Gemini CLI czy OpenSpec – wszystkie te narzędzia mają jedną wspólną cechę:

Jakość wyjścia jest ograniczona jakością wejścia.

I właśnie dlatego umiejętność pisania specyfikacji pod AI staje się jedną z najważniejszych kompetencji nowoczesnego software engineeringu.

Największy błąd: traktowanie AI jak człowieka

Większość źle napisanych specyfikacji wynika z jednego założenia:

Autor zakłada, że AI rozumie kontekst tak samo jak człowiek.

To nieprawda.

Doświadczony developer potrafi:

  • dopytać o szczegóły,
  • wyłapać nieścisłości,
  • domyślić się intencji biznesowej,
  • rozpoznać brakujące wymagania.

AI działa inaczej.

Jeśli czegoś nie opiszesz, model najczęściej:

  • założy własną interpretację,
  • uzupełni luki statystycznie,
  • wygeneruje „najbardziej prawdopodobne” rozwiązanie.

To właśnie dlatego dobra specyfikacja dla AI musi być bardziej precyzyjna niż specyfikacja dla człowieka.

Zasada #1: Zacznij od intencji, nie od rozwiązania

Najczęstszy antywzorzec wygląda tak:

Dodaj tabelę customer_discount
oraz endpoint GET /discounts.

Problem?

Opisujesz rozwiązanie, a nie problem.

Znacznie lepiej napisać:

Intent:
Klienci premium powinni otrzymywać rabaty
zależne od wartości zakupów.

Business Goal:
Zwiększenie retencji klientów premium.

Success Metric:
Wzrost liczby ponownych zakupów o 10%.

W ten sposób AI rozumie nie tylko co ma zrobić, ale również dlaczego.

Zasada #2: Opisuj domenę przed implementacją

Większość projektów nie upada przez błędne API.

Upada przez błędne zrozumienie domeny.

Zanim opiszesz endpointy, opisz:

  • encje,
  • relacje,
  • słownik pojęć,
  • reguły biznesowe.

Przykład:

Entities:
- Customer
- LoyaltyAccount
- LoyaltyTransaction

Rules:
- Jeden klient może mieć tylko jedno konto lojalnościowe
- Punkty wygasają po 365 dniach
- Zwrot zamówienia usuwa przyznane punkty

AI dużo lepiej radzi sobie z implementacją, gdy najpierw rozumie model domenowy.

Zasada #3: Używaj przykładów zamiast opisów

To jedna z najważniejszych lekcji wyniesionych z BDD i Specification by Example.

Zamiast pisać:

System powinien poprawnie naliczać punkty.

Napisz:

Scenario:
Customer places order worth 100 PLN

Given:
Customer is Premium

When:
Order is completed

Then:
100 loyalty points are added

Dla AI przykład jest znacznie bardziej jednoznaczny niż ogólny opis.

Zasada #4: Dokumentuj edge case'y

Większość błędów nie pojawia się w głównym scenariuszu.

Pojawia się na obrzeżach systemu.

Dlatego dobra specyfikacja zawsze zawiera sekcję:

Edge Cases

Na przykład:

Edge Cases:

- Refund after points were spent
- Customer account merged
- Loyalty account deleted
- Promotion expired during checkout

Jeśli nie opiszesz edge case'ów, AI je wymyśli.

I nie zawsze będą to właściwe założenia.

Zasada #5: Definiuj kontrakty

AI świetnie generuje kod.

Jeszcze lepiej generuje kod na podstawie kontraktów.

Dlatego specyfikacja powinna zawierać:

  • API Contract
  • Event Contract
  • Data Contract

Przykład:

POST /loyalty/points

Request:
{
  "customerId": "123",
  "orderValue": 100
}

Response:
{
  "pointsAdded": 100,
  "currentBalance": 1200
}

To eliminuje ogromną część niejednoznaczności.

Zasada #6: Opisuj ograniczenia architektoniczne

AI nie zna architektury Twojej organizacji.

Dlatego trzeba ją opisać.

Na przykład:

Constraints:

- Java 21
- Spring Boot 3
- PostgreSQL
- Event-driven architecture
- Kafka only
- No synchronous communication

Dzięki temu AI nie zaproponuje rozwiązania sprzecznego z kierunkiem architektonicznym organizacji.

Zasada #7: Opisuj kryteria walidacji

Jednym z największych błędów jest kończenie specyfikacji na implementacji.

Dobra specyfikacja odpowiada również na pytanie:

Skąd będziemy wiedzieć, że rozwiązanie jest poprawne?

Przykład:

Validation:

- Unit tests coverage > 80%
- Integration tests pass
- API contract tests pass
- Loyalty points calculation verified

To pozwala AI nie tylko wygenerować kod, ale również zrozumieć sposób jego weryfikacji.

Przykład pełnej specyfikacji pod AI

Intent:
Introduce loyalty program.

Business Goal:
Increase customer retention.

Entities:
Customer
LoyaltyAccount
LoyaltyTransaction

Rules:
1 point per 1 PLN.
Points expire after 365 days.

Scenario:
Given Premium Customer
When Order Completed
Then Points Added

API:
POST /loyalty/points

Edge Cases:
Refunds
Expired points

Constraints:
Java 21
Spring Boot 3
Kafka

Validation:
Unit Tests
Contract Tests
Integration Tests

Zauważ, że taka specyfikacja jest:

  • krótka,
  • jednoznaczna,
  • łatwa do wersjonowania,
  • czytelna dla człowieka,
  • bardzo czytelna dla AI.

Najważniejsza zmiana mentalna

Przez wiele lat specyfikacja była czymś, co prowadziło do kodu.

W erze AI zaczyna być czymś więcej.

Specyfikacja staje się:

  • kontraktem,
  • źródłem prawdy,
  • interfejsem pomiędzy człowiekiem a AI.

I właśnie dlatego coraz częściej słyszymy o Spec-Driven Development.

Nie dlatego, że AI wymaga więcej dokumentacji.

Ale dlatego, że AI wymaga lepszej dokumentacji.

Podsumowanie

Jeśli miałbym sprowadzić cały artykuł do jednego zdania, brzmiałoby ono tak:

Nie pisz specyfikacji tak, jakby czytał ją człowiek. Pisz ją tak, jakby miała zostać wykonana przez maszynę.

Bo właśnie do tego zmierza nowoczesny software engineering.

Coraz częściej nie programujemy bezpośrednio systemów.

Projektujemy specyfikacje, które systemy budują.

piątek, 19 czerwca 2026

{dev} forge – Developer czy Spec Engineer? Jak AI zmienia rolę programisty

Przez ostatnie kilkadziesiąt lat odpowiedź na pytanie „czym zajmuje się programista?” była stosunkowo prosta.

Programista analizował wymagania, projektował rozwiązanie i pisał kod.

Oczywiście w zależności od doświadczenia dochodziły dodatkowe obowiązki związane z architekturą, analizą biznesową czy mentoringiem, ale rdzeń zawodu pozostawał ten sam:

Developer był przede wszystkim producentem kodu.




Dziś jednak znajdujemy się w momencie, który może okazać się jedną z największych zmian w historii software engineeringu.

Po raz pierwszy od dekad produkcja kodu przestaje być głównym ograniczeniem procesu wytwarzania oprogramowania.

Modele takie jak Codex, Claude Code, Gemini CLI czy Cursor potrafią wygenerować w kilka minut ilość kodu, której napisanie zajmowało kiedyś wiele godzin.

To prowadzi do bardzo ciekawego pytania:

Czy przyszłością programisty jest bycie lepszym coderem, czy raczej lepszym projektantem specyfikacji?

Od rzemieślnika kodu do projektanta systemów

Przez wiele lat produktywność programisty była mocno związana z szybkością tworzenia kodu.

Znajomość frameworków, języków programowania i bibliotek była głównym źródłem przewagi.

Dziś sytuacja zaczyna się zmieniać.

Coraz częściej obserwujemy, że największą wartość dostarcza nie osoba, która najszybciej pisze kod, ale osoba, która najlepiej definiuje problem.

AI potrafi napisać endpoint.

AI potrafi wygenerować testy.

AI potrafi stworzyć dokumentację.

Ale nadal nie potrafi samodzielnie odpowiedzieć na pytania:

  • Jaki problem biznesowy rozwiązujemy?
  • Jakie są reguły domenowe?
  • Jakie są granice systemu?
  • Jakie kompromisy architektoniczne akceptujemy?
  • Jak zmierzymy sukces rozwiązania?

I właśnie tutaj zaczyna pojawiać się nowa specjalizacja.

Kim jest Spec Engineer?

Nie jest to jeszcze oficjalny zawód.

Nie znajdziesz go w większości struktur organizacyjnych.

A jednak coraz więcej zespołów zaczyna wykonywać dokładnie tę pracę.

Spec Engineer to osoba odpowiedzialna za stworzenie specyfikacji, która pozwala ludziom i AI budować rozwiązania w sposób przewidywalny.

Jej zadaniem nie jest przede wszystkim pisanie kodu.

Jej zadaniem jest zaprojektowanie warunków, w których poprawny kod może powstać.

To subtelna, ale fundamentalna różnica.

Nowy łańcuch wartości

Przez lata dominował model:

Requirements → Developer → Code

W świecie AI coraz częściej wygląda to tak:

Requirements → Specification → AI → Code

Lub nawet:

Business Intent
        ↓
Specification
        ↓
Plan
        ↓
Tasks
        ↓
AI Agents
        ↓
Validation
        ↓
Production

Zauważmy coś ciekawego.

Kod nie zniknął.

Ale przestał być centralnym artefaktem procesu.

Coraz częściej staje się produktem ubocznym dobrze przygotowanej specyfikacji.

Dlaczego seniorzy nadal są tak cenni?

Jednym z argumentów często pojawiających się w dyskusjach o AI jest:

„Skoro AI potrafi pisać kod, to po co nam doświadczeni developerzy?”

To pytanie wynika z błędnego założenia.

Zakłada bowiem, że główną wartością seniora jest szybkość kodowania.

W rzeczywistości seniorzy od dawna zarabiają na czymś innym.

Na podejmowaniu decyzji.

Doświadczony architekt lub senior developer potrafi:

  • zidentyfikować ryzyka,
  • zauważyć brakujące wymagania,
  • przewidzieć skutki decyzji architektonicznych,
  • rozpoznać błędne założenia biznesowe,
  • zaprojektować rozwiązanie możliwe do utrzymania za kilka lat.

To są kompetencje, których nie zastępuje automatyczne generowanie kodu.

Wręcz przeciwnie.

Ich znaczenie rośnie.

Czy juniorzy mają problem?

To jeden z najbardziej kontrowersyjnych tematów związanych z AI.

Przez lata junior zdobywał doświadczenie poprzez pisanie dużej ilości kodu.

W ten sposób poznawał:

  • wzorce projektowe,
  • architekturę systemów,
  • debugowanie,
  • integracje,
  • procesy jakościowe.

Jeśli znaczną część tej pracy przejmie AI, pojawia się pytanie:

Skąd przyszli seniorzy będą zdobywać doświadczenie?

Moim zdaniem odpowiedzią jest zmiana sposobu nauki.

Przyszły senior będzie musiał szybciej rozwijać:

  • myślenie systemowe,
  • analizę domenową,
  • modelowanie procesów,
  • projektowanie specyfikacji.

Kod pozostanie ważny, ale przestanie być jedynym źródłem nauki.

Najcenniejsze kompetencje dekady AI

Jeżeli miałbym wskazać kompetencje, których warto rozwijać najwięcej w latach 2026–2030, byłyby to:

1. Domain Modeling

Rozumienie biznesu i domeny problemowej.

2. Systems Thinking

Myślenie o zależnościach między elementami systemu.

3. Architecture

Projektowanie rozwiązań odpornych na zmiany.

4. Specification Design

Umiejętność tworzenia jednoznacznych specyfikacji dla ludzi i AI.

5. Validation Engineering

Definiowanie sposobów walidacji i kontroli jakości.

Warto zauważyć, że tylko jedna z tych kompetencji dotyczy bezpośrednio kodowania.

Spec Engineer jako naturalna ewolucja developera

Nie sądzę, aby zawód developera zniknął.

Nie wierzę również w wizję świata, w którym wszyscy staną się wyłącznie analitykami piszącymi prompty.

Bardziej prawdopodobny wydaje się inny scenariusz.

Developerzy będą stopniowo przesuwać się wyżej w stosie abstrakcji.

Tak jak kiedyś przeszliśmy od assemblera do języków wysokiego poziomu.

Tak jak później przeszliśmy od ręcznego zarządzania serwerami do chmury.

Tak samo dziś przechodzimy od:

Code First

do:

Specification First

Nie oznacza to końca programowania.

Oznacza zmianę punktu ciężkości.

Podsumowanie

Największą zmianą, jaką przynosi AI, nie jest automatyczne generowanie kodu.

Największą zmianą jest przesunięcie wartości z implementacji na intencję.

Coraz mniej istotne staje się to, kto napisze kod szybciej.

Coraz ważniejsze staje się to, kto potrafi lepiej zdefiniować problem, ograniczenia i oczekiwany rezultat.

Dlatego uważam, że w ciągu najbliższych kilku lat będziemy obserwować narodziny nowej specjalizacji:

Spec Engineer – osoby odpowiedzialnej za projektowanie specyfikacji, na podstawie których ludzie i AI wspólnie tworzą oprogramowanie.

Bo jeśli software ma być kuty z pomocą AI, to ktoś musi najpierw przygotować formę, do której ten metal zostanie wlany.

poniedziałek, 18 maja 2026

{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:

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:

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:

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:

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:

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.

niedziela, 26 kwietnia 2026

{dev} forge – Kto odpowiada za kod generowany przez AI?

AI coding assistants zmieniły sposób, w jaki powstaje software. Kod, który kiedyś był efektem godzin pracy developera, dziś może powstać w kilka minut. Prompt, kilka iteracji i gotowe. Szybkość robi wrażenie. Problem w tym, że wraz z tą zmianą pojawia się pytanie, które wielu zespołów jeszcze nie zadaje wystarczająco głośno:

kto odpowiada za kod generowany przez AI?



To nie jest pytanie filozoficzne. To jest pytanie bardzo praktyczne. Dotyczy jakości, bezpieczeństwa, odpowiedzialności prawnej i – co najważniejsze – odpowiedzialności inżynierskiej.

W świecie, w którym kod powstaje coraz częściej przy udziale modeli językowych, nie możemy pozwolić sobie na brak jasnej odpowiedzi.

Mit: „AI wygenerowało, więc to nie moja odpowiedzialność”

Jednym z najbardziej niebezpiecznych mitów, jakie pojawiły się wraz z popularyzacją AI, jest przekonanie, że skoro kod został wygenerowany przez model, to odpowiedzialność za jego jakość jest „rozmyta”.

To bardzo wygodna narracja. Ale całkowicie nieprawdziwa.

AI nie jest członkiem zespołu. Nie bierze odpowiedzialności. Nie podpisuje się pod commitami w sensie inżynierskim. Nie odpowiada przed klientem, audytem ani produkcją.

AI jest narzędziem. Bardzo zaawansowanym, ale nadal narzędziem.

A odpowiedzialność za efekt użycia narzędzia zawsze pozostaje po stronie człowieka i organizacji.

To nie pierwszy raz w historii

Warto zauważyć, że to nie jest zupełnie nowy problem. Historia software engineeringu zna już podobne momenty.

Kiedy pojawiły się frameworki, biblioteki open source, code generators czy low-code platforms, również pojawiało się pytanie: kto odpowiada za kod, którego nie napisaliśmy w 100% sami?

Odpowiedź zawsze była taka sama:

odpowiada ten, kto decyduje o użyciu i wdrożeniu.

To, że nie napisałeś każdej linijki ręcznie, nie zwalnia Cię z odpowiedzialności za system, który trafia na produkcję.

AI tylko podnosi stawkę, bo zwiększa skalę i tempo generowania kodu.

Problem numer jeden: iluzja poprawności

Jednym z największych zagrożeń przy pracy z AI jest to, że generowany kod wygląda poprawnie.

Ma sensowną strukturę. Kompiluje się. Często przechodzi nawet podstawowe testy. Komentarze brzmią przekonująco. Nazwy są logiczne. Wszystko sprawia wrażenie profesjonalne.

Ale „wygląda poprawnie” to nie to samo, co „jest poprawne”.

Model nie rozumie Twojego systemu w taki sposób, jak robi to doświadczony inżynier. Nie zna wszystkich kontekstów biznesowych. Nie zna ograniczeń infrastrukturalnych. Nie zna kompromisów, które zostały wcześniej podjęte.

W rezultacie może wygenerować rozwiązanie, które:

I to wszystko bez żadnego ostrzeżenia.

Problem numer dwa: brak świadomości decyzji

Kiedy developer pisze kod ręcznie, podejmuje serię mikrodecyzji. Każda linijka ma swoje uzasadnienie. Każda konstrukcja wynika z jakiejś intencji.

W przypadku kodu generowanego przez AI część tych decyzji jest ukryta. Model generuje rozwiązanie, ale nie zawsze jasno komunikuje, dlaczego wybrał właśnie takie podejście.

To prowadzi do bardzo niebezpiecznej sytuacji:

zespół zaczyna utrzymywać kod, którego w pełni nie rozumie.

A utrzymywanie kodu bez zrozumienia to prosta droga do problemów.

Problem numer trzy: odpowiedzialność rozproszona

W klasycznym modelu developmentu odpowiedzialność jest względnie jasna. Wiemy, kto implementował feature, kto go reviewował, kto zatwierdził wdrożenie.

W modelu opartym o AI bardzo łatwo tę odpowiedzialność rozmyć:

  • „AI to wygenerowało”
  • „to było tylko sugestią”
  • „nie zmieniałem tego, bo wyglądało dobrze”

Jeśli zespół nie zdefiniuje jasno zasad pracy z AI, bardzo szybko może dojść do sytuacji, w której nikt nie czuje się właścicielem kodu.

A brak właściciela to brak jakości.

Jak powinna wyglądać odpowiedzialność w erze AI?

Moim zdaniem odpowiedź jest prostsza, niż się wydaje:

odpowiedzialność się nie zmienia. Zmieniają się narzędzia.

To nadal:

  • developer odpowiada za kod, który commitował,
  • reviewer odpowiada za code review,
  • architekt odpowiada za spójność systemu,
  • organizacja odpowiada za to, co trafia na produkcję.

AI nie znosi tych ról. Ono tylko zmienia sposób, w jaki wykonujemy pracę.

Nowa kompetencja: AI Code Review

Wraz z AI pojawia się nowa, bardzo ważna kompetencja: umiejętność reviewowania kodu generowanego przez model.

To nie jest dokładnie to samo, co klasyczny code review. Trzeba nauczyć się patrzeć na kod trochę inaczej.

Na co zwracać uwagę?

  • Czy rozwiązanie jest zgodne z architekturą systemu?
  • Czy nie wprowadza ukrytych założeń?
  • Czy obsługuje edge case’y?
  • Czy nie „overengineeruje” problemu?
  • Czy nie pomija ważnych aspektów (np. bezpieczeństwa, walidacji, logowania)?

AI potrafi być bardzo przekonujące. Dlatego review musi być jeszcze bardziej świadome.

Rola Spec-Driven Development

I tutaj wracamy do jednego z głównych tematów tej serii.

Jeśli chcemy realnie zarządzać odpowiedzialnością za kod generowany przez AI, potrzebujemy stabilnego punktu odniesienia. Czegoś, co pozwala jasno powiedzieć:

„to jest poprawne, a to nie”.

Właśnie tę rolę pełni specyfikacja.

W podejściu spec-driven:

  • AI nie „zgaduje” rozwiązania, tylko realizuje spec,
  • kod można walidować względem scenariuszy i kontraktów,
  • odpowiedzialność jest powiązana z artefaktami, a nie rozmową,
  • łatwiej przeprowadzić audyt i analizę decyzji.

To nie eliminuje potrzeby myślenia. Ale znacząco zmniejsza ryzyko chaosu.

Najważniejsza zasada

Jeśli miałbym sprowadzić cały temat do jednej zasady, brzmiałaby ona tak:

Jeśli wrzucasz kod na produkcję, bierzesz za niego odpowiedzialność – niezależnie od tego, czy napisałeś go sam, czy wygenerowało go AI.

To podejście jest brutalnie proste. Ale właśnie dlatego działa.

Podsumowanie

AI zmienia sposób, w jaki tworzymy software. Przyspiesza development, obniża barierę wejścia i pozwala realizować pomysły szybciej niż kiedykolwiek wcześniej.

Ale nie zmienia jednego:

odpowiedzialności za system.

Nie możemy traktować AI jako wymówki. Nie możemy zrzucać na nie decyzji. Nie możemy zakładać, że skoro coś zostało wygenerowane, to jest automatycznie poprawne.

W erze AI dobry inżynier to nie ten, kto pisze najwięcej kodu. To ten, kto potrafi ocenić, który kod powinien istnieć.

A do tego potrzebujemy nie tylko promptów, ale przede wszystkim dobrze zbudowanych specyfikacji.

czwartek, 9 kwietnia 2026

{dev} forge – Spec vs Prompt: dlaczego promptowanie nie skaluje się w projektach

AI do kodowania weszło do codziennej pracy szybciej, niż wiele zespołów zdążyło zbudować wokół niego sensowne praktyki. Najpierw był zachwyt. Wrzucasz prompt, dostajesz kod. Doprecyzowujesz dwa szczegóły, model poprawia. Prosisz o testy, generuje testy. Prośba o refaktoryzację? Proszę bardzo. Na poziomie pojedynczego zadania wygląda to wręcz magicznie.




Problem zaczyna się później. Nie wtedy, gdy generujemy pierwszy endpoint. Nie wtedy, gdy robimy prosty komponent UI. Tylko wtedy, gdy z takiego podejścia próbujemy zbudować większy, dłużej żyjący system.

I właśnie w tym miejscu pojawia się fundamentalna różnica między promptem a specyfikacją.

Prompt uruchamia odpowiedź. Spec uruchamia proces wytwarzania.

To zdanie dobrze ustawia cały problem. Bo choć przez chwilę może się wydawać, że promptowanie AI to nowy model developmentu, w praktyce bardzo szybko okazuje się, że prompt-driven development nie skaluje się w projektach. Skaluje się co najwyżej w eksperymentach, prototypach i krótkich iteracjach wykonywanych przez jedną osobę, która cały kontekst trzyma jeszcze w głowie.

Dlaczego prompt-driven development działa tak dobrze na początku?

Żeby uczciwie opisać problem, warto zacząć od tego, dlaczego promptowanie w ogóle jest tak kuszące. Powód jest prosty: ono naprawdę działa. I to działa zaskakująco dobrze.

Jeśli tworzysz mały feature, narzędzie pomocnicze, prosty landing page, parser, integrację z jednym API albo szybki proof of concept, prompt potrafi dostarczyć ogromną wartość. Skraca czas wejścia, obniża koszt pierwszej implementacji i redukuje tarcie przy przejściu od pomysłu do pierwszego działającego wyniku.

To właśnie dlatego tak wiele osób zakochało się w AI coding assistants. Bo w porównaniu z pustym plikiem prompt wydaje się genialnym interfejsem. Zamiast pisać wszystko od zera, zaczynasz od rozmowy. Zamiast konstruować każde rozwiązanie ręcznie, możesz kierować modelem jak bardzo szybkim, bardzo sprawnym juniorem z nieskończoną energią.

Ale jest w tym haczyk. Ten model świetnie działa lokalnie, dla pojedynczych zadań. Problem w tym, że software engineering rzadko kończy się na lokalnym sukcesie jednego zadania. Systemy żyją długo. Zmieniają się. Rozrastają się. Wchodzą w interakcje z innymi systemami. Są rozwijane przez wiele osób. Podlegają ograniczeniom domenowym, architektonicznym, bezpieczeństwa, wydajności i zgodności.

I wtedy prompt zaczyna pokazywać swoje granice.

Czym właściwie jest prompt-driven development?

W najprostszym ujęciu to sposób pracy, w którym głównym mechanizmem sterowania implementacją jest rozmowa z modelem. Zamiast opierać development na trwałych artefaktach, takich jak specyfikacja, kontrakt, scenariusze, ADR czy model domeny, opieramy go głównie na kolejnych wiadomościach w czacie.

Przykładowy flow wygląda tak:

  • opisujesz, co chcesz zbudować,
  • AI generuje pierwszą wersję,
  • dopisujesz poprawki,
  • AI dostosowuje kod,
  • pojawia się kolejny edge case,
  • wrzucasz następny prompt,
  • pojawia się problem architektoniczny,
  • rozwiązujesz go kolejną rozmową.

Na krótkim dystansie to wygląda sensownie. Na dłuższym zaczyna przypominać budowanie systemu z pamięci krótkotrwałej. Wszystko działa, dopóki wszyscy pamiętają, co już ustaliliśmy. A to nie jest solidny fundament dla większego projektu.

Największy problem: chat nie jest source of truth

To jest chyba najważniejszy punkt całego artykułu.

Historia rozmowy nie jest dobrym źródłem prawdy dla projektu.

Czat jest świetny do eksploracji. Do iteracji. Do szybkiego zawężania pomysłów. Do generowania wariantów. Ale bardzo słabo nadaje się na trwały nośnik decyzji projektowych.

Dlaczego?

Bo rozmowa jest z natury liniowa, ulotna i zależna od kolejności komunikatów. Część ważnych ustaleń pojawia się mimochodem. Część ginie kilka ekranów wyżej. Część zostaje nadpisana nowym promptem. Część zostaje błędnie zreinterpretowana przez model. Część w ogóle nie trafia do żadnego miejsca, z którego inna osoba albo inny agent AI mogliby z niej później skorzystać.

W rezultacie zespół zaczyna funkcjonować w bardzo niebezpiecznym trybie: „to było gdzieś w rozmowie”.

A jeśli coś było „gdzieś w rozmowie”, to w praktyce bardzo często znaczy, że nie istnieje jako stabilny artefakt.

Prompt nie utrzymuje spójności systemowej

Drugi problem jest równie ważny: prompt bardzo słabo utrzymuje spójność między decyzjami.

W dobrze prowadzonym projekcie nie chodzi tylko o to, żeby każdy pojedynczy fragment kodu działał. Chodzi też o to, żeby całość była spójna. Nazewnictwo. Reguły domenowe. Podejście do błędów. Styl integracji. Kontrakty API. Standardy bezpieczeństwa. Logging. Metryki. Sposób modelowania encji. Granice odpowiedzialności modułów.

Jeśli każdy kolejny element systemu powstaje z osobnego promptu, istnieje bardzo duże ryzyko, że AI za każdym razem będzie interpretować problem odrobinę inaczej. Raz użyje jednego wzorca. Innym razem drugiego. Raz nazwie encję Customer, innym razem Client. Raz założy synchroniczny flow, innym razem asynchroniczny. Raz doda walidację w kontrolerze, innym razem w serwisie.

Każda z tych różnic może wydawać się niewielka. Ale w skali projektu to właśnie z takich różnic powstaje architektoniczny chaos.

Ambiguity at machine speed

W poprzednim artykule newsowym pojawiła się bardzo ważna intuicja: niejednoznaczność porusza się dziś z prędkością maszyny.

Kiedyś nieprecyzyjne wymaganie oznaczało, że programista przez kilka godzin albo dni źle rozumiał zadanie. Dziś nieprecyzyjne wymaganie może w kilka minut wygenerować kod, testy, dokumentację i jeszcze propozycję refaktoryzacji, wszystkie oparte na błędnym założeniu.

To zmienia skalę problemu. AI nie tworzy nowego rodzaju chaosu. Ono po prostu dramatycznie przyspiesza dostarczanie chaosu tam, gdzie wejście jest nieprecyzyjne.

Dlatego promptowanie nie rozwiązuje problemu niejednoznaczności. Ono go często maskuje na początku, a potem zwielokrotnia.

Prompt nie tworzy kontraktu

Jest jeszcze jedna rzecz, o której mówi się zdecydowanie za mało. Prompt może być instrukcją, ale bardzo rzadko jest kontraktem.

Kontrakt mówi nie tylko, co zrobić, ale również:

  • jakie są granice rozwiązania,
  • jakie zachowania są obowiązkowe,
  • jakie wyjątki trzeba obsłużyć,
  • jakie warunki uznajemy za poprawność,
  • jakie elementy są poza zakresem.

Prompt bardzo często jest skrótem myślowym. Czasem bardzo dobrym skrótem. Ale nadal skrótem. A systemów produkcyjnych nie powinno się budować na skrótach myślowych, jeśli chcemy przewidywalności.

Właśnie tu zaczyna się przewaga specyfikacji.

Spec to nie dłuższy prompt

To bardzo ważne rozróżnienie. Gdy mówię, że promptowanie nie skaluje się w projektach, nie mam na myśli tego, że wystarczy po prostu pisać dłuższe prompty.

Specyfikacja nie jest „większym promptem”.

Spec to inny rodzaj artefaktu.

Dobrze przygotowana specyfikacja jest:

  • trwała,
  • strukturalna,
  • podzielona na warstwy,
  • możliwa do przeglądu i wersjonowania,
  • czytelna dla ludzi i użyteczna dla AI,
  • powiązana z walidacją.

Prompt jest impulsem. Spec jest modelem pracy.

Prompt jest rozmową. Spec jest systemem odniesienia.

Prompt inicjuje wykonanie. Spec stabilizuje delivery.

Jak wygląda różnica w praktyce?

Załóżmy, że chcesz zbudować moduł promocji w e-commerce.

W podejściu prompt-driven możesz napisać coś w stylu:

Zbuduj moduł promocji dla sklepu online.
Powinien obsługiwać rabaty procentowe, promocje 2+1 i ograniczenia czasowe.
Dodaj API i testy.

To wystarczy, żeby AI wygenerowało coś sensownego. Być może nawet całkiem niezłego. Ale natychmiast pojawiają się pytania:

  • Czy promocje mogą się łączyć?
  • Co ma wygrać przy konflikcie dwóch promocji?
  • Czy promocja działa per kanał, per sklep, per klient, per koszyk?
  • Czy walidacja ma blokować zapis, czy tylko ostrzegać?
  • Jak mierzymy skuteczność promocji?
  • Jakie są ograniczenia wydajnościowe?
  • Jakie eventy system ma publikować?

W podejściu spec-driven zaczynasz od czegoś zupełnie innego. Najpierw definiujesz kontekst biznesowy. Potem zakres. Potem model domenowy. Potem scenariusze BDD. Potem edge case’y. Potem kontrakty API i ograniczenia architektoniczne. Dopiero na końcu pojawia się implementacja.

I właśnie dlatego efekt końcowy jest bardziej przewidywalny. Nie dlatego, że AI nagle stało się „mądrzejsze”. Tylko dlatego, że dostało lepszy artefakt wejściowy.

Dlaczego prompt-driven development rozpada się w zespole?

Jedna osoba może jeszcze przez jakiś czas utrzymać projekt oparty głównie na rozmowach z AI. Zwłaszcza jeśli sama była autorem większości promptów i pamięta intencję stojącą za decyzjami.

Ale kiedy do projektu wchodzi zespół, sytuacja się komplikuje.

Nagle trzeba odpowiedzieć na pytania:

  • Skąd nowa osoba ma wiedzieć, dlaczego coś zrobiono tak, a nie inaczej?
  • Jak inny developer albo architekt ma odtworzyć decyzje ukryte w historii czatu?
  • Jak tester ma zrozumieć oczekiwane zachowanie bez trwałych scenariuszy?
  • Jak kolejny agent AI ma zachować spójność z poprzednimi decyzjami?

Jeśli odpowiedź brzmi „trzeba przejrzeć całą rozmowę”, to znaczy, że proces nie skaluje się organizacyjnie.

To właśnie dlatego zespoły potrzebują artefaktów, które żyją poza czatem.

Co w takim razie skaluje się lepiej?

Lepszym modelem jest podejście, w którym prompt nie znika, ale przestaje być głównym nośnikiem logiki projektu.

Innymi słowy: nie chodzi o rezygnację z promptów. Chodzi o obniżenie ich rangi.

W zdrowym, skalowalnym modelu prompt jest tylko jednym z interfejsów wykonawczych, a nie centralnym artefaktem systemu. Centralnym artefaktem staje się specyfikacja.

Flow wygląda wtedy mniej więcej tak:

Business Context → Scope → Domain Model → Scenarios → Contracts → Validate → Code

albo jeszcze prościej:

Spec → Plan → Tasks → Code → Validate

W takim modelu AI nadal robi bardzo dużo pracy. Nadal może generować kod, testy, diagramy, dokumentację, migracje czy propozycje refaktoryzacji. Ale robi to już w ramach ustalonych granic.

To jest dokładnie ta różnica, która odróżnia eksperyment od engineeringu.

Prompt jest świetny do eksploracji. Spec jest potrzebny do dostarczania

Nie chcę demonizować promptów. Byłoby to nieuczciwe i mało praktyczne. Prompt ma ogromną wartość. Problem zaczyna się dopiero wtedy, gdy próbujemy uczynić z niego fundament całego procesu.

Moim zdaniem prompt najlepiej sprawdza się w trzech sytuacjach:

  • eksploracja problemu,
  • szybkie prototypowanie,
  • iteracyjne dopracowywanie szczegółów w ramach już ustalonej specyfikacji.

Natomiast gdy zależy nam na trwałości decyzji, spójności systemu, współpracy w zespole, traceability i przewidywalności jakości, potrzebujemy czegoś więcej. Potrzebujemy specu.

Najważniejsza zmiana mentalna

W erze AI bardzo łatwo wpaść w pułapkę myślenia, że skoro model potrafi generować kod z języka naturalnego, to wystarczy już tylko dobrze „pogadać z AI”.

Ale software engineering nigdy nie polegał wyłącznie na produkcji kodu. Zawsze chodziło o redukowanie ryzyka błędnej interpretacji, stabilizowanie decyzji i tworzenie systemów, które da się rozwijać w czasie.

Dlatego najważniejsza zmiana mentalna brzmi:

nie projektujemy już tylko kodu. Projektujemy artefakty wejściowe dla ludzi i AI.

A najlepszym takim artefaktem nie jest ulotna rozmowa. Jest nim dobrze zbudowana specyfikacja.

Podsumowanie

Promptowanie AI jest świetne. Ale tylko wtedy, gdy wiemy, do czego służy.

Jako narzędzie do szybkiej eksploracji, prototypowania i przyspieszania lokalnych zadań prompt sprawdza się znakomicie. Jako centralny fundament większego projektu zaczyna bardzo szybko ujawniać swoje ograniczenia.

Nie utrzymuje trwałego kontekstu. Nie gwarantuje spójności. Nie buduje kontraktu. Nie skaluje się dobrze na zespół. I zbyt łatwo zamienia niejednoznaczność w szybki, pozornie imponujący, ale kosztowny chaos.

Dlatego właśnie uważam, że:

Prompt to rozmowa. Spec to system.

I jeśli chcemy naprawdę kuć software z pomocą AI, to nie możemy zatrzymać się na rozmowie. Musimy przejść do specyfikacji.

środa, 1 kwietnia 2026

{dev} forge – AI & Spec News #1: Koniec vibe coding?

W serii {dev} forge – How software is forged with AI skupiam się na jednym głównym temacie: jak zmienia się sposób budowania oprogramowania w erze AI.



Ten artykuł to pierwszy wpis z nowego mini-cyklu: AI & Spec News, gdzie zbieram najciekawsze obserwacje i trendy z rynku – świeże, konkretne i bez hype’u.

1. Koniec „vibe coding” – zaczyna się era spec

Jeszcze niedawno dominowało podejście:

Prompt → Code

Dziś coraz więcej zespołów przechodzi na:

Spec → Plan → Tasks → Code

Dlaczego? Bo prompt nie skaluje się w większych projektach. Kontekst znika, decyzje są niespójne, a architektura rozpływa się w historii czatu.

To nie jest tylko opinia – to trend widoczny w całej branży. Coraz więcej publikacji wskazuje, że spec-driven development staje się naturalnym kolejnym krokiem po „vibe coding” (The New Stack).

Dodatkowo pojawia się mocny insight z community:

„Don’t prompt AI to write code. Give it a specification and let agents implement it.”

(źródło)

2. Największy problem AI: niejednoznaczność × prędkość

AI potrafi generować tysiące linii kodu w kilka sekund.

Ale problem nie jest w szybkości.

Problemem jest to, że niejuednoznaczność porusza się teraz z prędkością maszyny.

Jak trafnie opisano:

AI generuje kod szybciej, niż jesteśmy w stanie go przeczytać – ale prawdziwym problemem jest brak precyzji wymagań.

(źródło)

To zmienia wszystko. Błędy nie znikają – są tylko produkowane szybciej.

3. Spec jako kontrakt (a nie dokument)

Nowoczesne podejście do specyfikacji zmienia jej rolę:

  • spec nie opisuje systemu
  • spec steruje systemem

Specyfikacja definiuje:

  • wejścia i wyjścia
  • reguły biznesowe
  • edge case’y

Dzięki temu:

  • AI generuje bardziej przewidywalny kod
  • testy mogą powstawać automatycznie

To podejście jest coraz częściej opisywane jako spec = source of truth, a kod jako artefakt wtórny:

Specyfikacja staje się głównym artefaktem, a kod – wtórnym, często generowanym.

(źródło)

4. AI potrzebuje ograniczeń, nie tylko możliwości

AI coding assistants są niesamowicie wydajne, ale mają jedną fundamentalną cechę:

są świetne w wykonywaniu instrukcji, ale słabe w zgadywaniu intencji.

Dlatego pojawia się coraz więcej głosów, że:

  • prompt = eksperyment
  • spec = system

Spec-Driven Development działa jak mechanizm kontroli:

  • wprowadza strukturę
  • ogranicza interpretację
  • wymusza spójność

Jak pokazują analizy:

AI models are excellent at following detailed instructions, but poor at inferring vague ones.

(źródło)

5. Enterprise shift: od eksperymentów do architektury

W 2026 widzimy bardzo wyraźny pivot:

  • z eksperymentów AI
  • do governance i architektury

Firmy przestają traktować AI jako „zabawkę do generowania kodu” i zaczynają budować wokół niego procesy.

Eksperci wskazują wprost:

AI coding tools are shifting towards architecture, governance and maintainability.

(źródło)

6. Skala adopcji AI jest ogromna

To już nie jest nisza.

Z najnowszych danych:

  • 64% firm generuje większość kodu z pomocą AI
  • w ciągu roku może to być nawet 90%

(źródło)

Jednocześnie pojawia się ważny efekt uboczny:

  • produktywność rośnie
  • ale jakość i spójność stają się wyzwaniem

7. Nowy kierunek: AI + Spec + Test

Pojawiają się też bardzo ciekawe podejścia researchowe i praktyczne:

  • Test-Driven AI Agents (spec → test → agent)
  • Spec jako enforce'owany kontrakt (np. security)

To pokazuje jeden kierunek:

przyszłość nie jest „AI pisze kod” – tylko „AI wykonuje specyfikację”.

Podsumowanie

AI nie eliminuje potrzeby myślenia o systemie.

Wręcz przeciwnie.

Wymusza lepsze myślenie.

I właśnie dlatego Spec-Driven Development przestaje być ciekawostką.

Staje się nowym standardem – szczególnie tam, gdzie liczy się jakość, przewidywalność i skalowalność.

Software nie jest już tylko pisany.

Software jest generowany – na podstawie specyfikacji.

wtorek, 31 marca 2026

{dev} forge – Struktura dobrej specyfikacji w Spec-Driven Development

W poprzednich artykułach z cyklu {dev} forge – How software is forged with AI ustaliliśmy dwie rzeczy. Po pierwsze – Spec-Driven Development nie jest nową modą, tylko ewolucją podejść takich jak V-Model, BDD i Specification by Example. Po drugie – pojawienie się AI sprawiło, że jakość specyfikacji zaczęła mieć jeszcze większe znaczenie.



Pora więc zejść poziom niżej i odpowiedzieć na bardzo praktyczne pytanie:

Jak powinna wyglądać dobra specyfikacja w Spec-Driven Development?

Nie taka „ładna”. Nie taka „zgodna z template’em”. Tylko taka, która realnie prowadzi implementację – zarówno dla człowieka, jak i dla AI.

Dlaczego struktura specyfikacji ma dziś większe znaczenie niż kiedykolwiek?

W klasycznym developmentcie niedoskonała specyfikacja była problemem, ale często dało się ją „uratować” rozmowami w zespole. Developer dopytał, tester doprecyzował, analityk wyjaśnił kontekst.

W świecie AI sytuacja wygląda inaczej.

AI nie dopytuje. AI zakłada.

Jeśli coś jest nieprecyzyjne, model uzupełni luki na podstawie statystyki, a nie Twojej intencji biznesowej. Dlatego dobra specyfikacja musi być:

  • jednoznaczna,
  • warstwowa (różne poziomy szczegółowości),
  • operacyjna (możliwa do użycia w implementacji i testach),
  • spójna (bez sprzecznych założeń).

Struktura nie jest więc formalnością. To mechanizm kontroli jakości myślenia.

Moja referencyjna struktura specyfikacji (Spec-Driven Development)

Nie ma jednego słusznego standardu. Ale po wielu projektach widzę, że dobra specyfikacja najczęściej składa się z kilku powtarzalnych warstw.

Poniżej moja referencyjna struktura, która dobrze działa zarówno dla zespołów, jak i dla AI-assisted development.

1. Kontekst biznesowy (Why)

To najczęściej pomijana sekcja. A jednocześnie najważniejsza.

Tu odpowiadamy na pytania:

  • jaki problem rozwiązujemy,
  • jakie są pain pointy,
  • jakie KPI chcemy poprawić,
  • dlaczego ta zmiana ma sens biznesowy.

Bez tej sekcji reszta specyfikacji staje się technicznym opisem czegoś, czego sens może być błędnie zrozumiany.

Anti-pattern: „Dodaj endpoint do zarządzania promocjami” bez kontekstu, po co i dla kogo.

2. Zakres i granice (Scope & Boundaries)

Tu definiujemy, co wchodzi w zakres, a co nie.

  • co dokładnie budujemy,
  • jakie są wykluczenia,
  • jakie systemy są objęte zmianą,
  • gdzie kończy się odpowiedzialność tego komponentu.

To sekcja, która chroni przed „feature creep” i nadinterpretacją – szczególnie przez AI.

3. Model domenowy (Domain Model)

To fundament zrozumienia systemu.

Opisujemy:

  • kluczowe encje (np. Zamówienie, Promocja, Klient),
  • relacje między nimi,
  • reguły biznesowe (np. „promocja nie łączy się z inną promocją”),
  • słownik pojęć.

To sekcja, która eliminuje różne interpretacje tych samych słów.

Tip: jeśli nazwy w kodzie i w specyfikacji się różnią – masz problem.

4. Scenariusze i zachowania (BDD / Specification by Example)

To serce specyfikacji.

Opisujemy konkretne zachowania systemu:

Given klient premium
And koszyk powyżej 500 zł
When użytkownik przechodzi do płatności
Then system nalicza rabat 10%

Dlaczego to działa?

  • jest zrozumiałe dla biznesu,
  • jest testowalne,
  • jest czytelne dla AI.

Kluczowa zasada: mniej ogólnych wymagań, więcej konkretnych przykładów.

5. Reguły i edge case’y

To sekcja, która oddziela junior-level spec od senior-level spec.

Opisujemy:

  • przypadki brzegowe,
  • błędy danych,
  • konflikty (np. promocje nakładające się),
  • fallbacki.

AI bardzo często „gubi się” właśnie tutaj, jeśli nie ma jasno określonych zasad.

6. Kontrakty techniczne (API / Events / Data)

Tu przechodzimy z poziomu domeny do implementacji.

  • API (request/response),
  • eventy (jeśli system jest event-driven),
  • formaty danych,
  • walidacje.

To sekcja, która minimalizuje rozjazd między zespołami i komponentami.

7. Ograniczenia architektoniczne

Nie wszystko wolno zrobić „jak się chce”.

Tu definiujemy:

  • wymagania niefunkcjonalne (wydajność, SLA),
  • zasady integracji,
  • security (np. OWASP, auth flows),
  • observability (logi, metryki).

To sekcja, która zabezpiecza system przed „technicznie działającym, ale złym” rozwiązaniem.

8. Walidacja (Testability)

Wracamy do DNA V-Modelu.

Każdy element specyfikacji powinien mieć odpowiedź na pytanie:

Jak sprawdzimy, że to działa poprawnie?

  • testy automatyczne,
  • checklisty,
  • kryteria akceptacji,
  • metryki sukcesu.

Bez tej sekcji spec jest tylko deklaracją.

9. Traceability (powiązania)

To element często ignorowany, ale kluczowy w większych projektach.

  • powiązanie z wymaganiami biznesowymi,
  • powiązanie z ticketami,
  • powiązanie z testami,
  • powiązanie z ADR-ami.

To właśnie tutaj pojawia się realna wartość RTM (Requirements Traceability Matrix).

Jak taka specyfikacja współpracuje z AI?

Dobrze zbudowana specyfikacja działa jak kontrakt wejściowy dla AI.

Zamiast jednego prompta typu:

"Zrób system promocji"

AI dostaje:

  • kontekst biznesowy,
  • model domenowy,
  • scenariusze,
  • reguły,
  • kontrakty API.

Efekt?

  • mniej zgadywania,
  • większa spójność,
  • lepsza jakość kodu i testów.

Najczęstsze błędy

  • brak kontekstu biznesowego,
  • zbyt ogólne wymagania,
  • brak przykładów,
  • pominięcie edge case’ów,
  • brak walidacji,
  • niespójność nazw.

W świecie AI te błędy są multiplikowane.

Podsumowanie

Dobra specyfikacja w Spec-Driven Development nie jest dokumentem. Jest systemem myślenia.

Łączy:

  • kontekst biznesowy,
  • zachowania (BDD),
  • reguły domenowe,
  • kontrakty techniczne,
  • walidację.

W świecie AI to właśnie specyfikacja staje się najważniejszym artefaktem w projekcie.

Bo dziś software nie jest już tylko pisany.

Software jest „kuty” – na podstawie specyfikacji.

czwartek, 26 marca 2026

{dev} forge: OpenSpec, czyli jak nadać Spec-Driven Development realny kształt

Skoro w poprzednim wpisie z cyklu {dev} forge – How software is forged with AI ustaliliśmy, że Spec-Driven Development jest nowoczesnym, AI-powered potomkiem V-Modelu, wzbogaconym o BDD i Specification by Example, to naturalnie pojawia się kolejne pytanie: jak to robić w praktyce?



I tutaj na scenę wchodzi OpenSpec – otwarte, lekkie podejście i zestaw narzędzi, których celem jest uporządkowanie współpracy człowieka z AI coding assistantem wokół specyfikacji. Oficjalny opis projektu mówi wprost, że chodzi o uzgodnienie co budujemy, zanim powstanie kod. To bardzo zdrowy kierunek, szczególnie dziś, gdy modele potrafią generować kod szybko, ale nadal nie czytają w myślach. OpenSpec jest opisywany jako lekki, open-source’owy framework spec-driven dla coding agentów i CLI, bez konieczności używania API keys czy MCP. 

Dlaczego OpenSpec jest ciekawy?

Najbardziej podoba mi się to, że OpenSpec nie próbuje sprzedać kolejnej magicznej obietnicy pod tytułem „AI zrobi software za Ciebie”. Zamiast tego projekt wychodzi od znacznie dojrzalszego założenia: AI jest skuteczne wtedy, gdy ma dobre wejście. A najlepszym wejściem nie jest przypadkowy prompt wrzucony do czatu, tylko sensownie przygotowana specyfikacja.

Twórcy OpenSpec trafnie zauważają, że asystenci kodujący bywają potężni, ale nieprzewidywalni, gdy wymagania żyją wyłącznie w historii rozmowy. OpenSpec dodaje więc lekką warstwę specyfikacji, która porządkuje uzgodnienia przed implementacją. To nie jest tylko techniczny detal. To w praktyce próba zamiany AI z „generatora zgadującego kontekst” w wykonawcę pracującego na bardziej stabilnym kontrakcie. 

OpenSpec jako brakujący pomost między teorią a codziennym developmentem

Wiele rozmów o Spec-Driven Development kończy się na poziomie idei. Mówimy, że warto mieć specyfikację. Że dobrze byłoby powiązać ją z testami. Że AI powinno dostać jasne zasady. I wszystko to jest prawdą. Problem pojawia się wtedy, gdy zespół pyta: dobrze, ale jak dokładnie to wdrożyć do repozytorium i codziennej pracy?

OpenSpec próbuje odpowiedzieć właśnie na to pytanie. Nie buduje zamkniętego ekosystemu ani nie uzależnia całego procesu od jednego vendora. Zamiast tego daje prosty workflow, który można potraktować jako szkic operacyjny dla pracy spec-driven.

Z dokumentacji projektu wynika, że domyślna szybka ścieżka opiera się na trzech krokach: propose → apply → archive. Najpierw proponujemy zmianę, potem ją wdrażamy, a na końcu archiwizujemy i domykamy ślad tej decyzji. To banalnie proste, ale właśnie w tej prostocie tkwi siła.

Jak rozumiem filozofię OpenSpec?

Dla mnie OpenSpec jest interesujące nie dlatego, że „wymyśla specyfikację od nowa”, tylko dlatego, że próbuje ją uczynić operacyjną. To ważna różnica.

Tradycyjnie specyfikacja bywała dokumentem wejściowym do projektu. Potem żyła własnym życiem, a kod i tak skręcał w inną stronę. W bardziej zwinnym świecie często z kolei rezygnowaliśmy z precyzji na rzecz szybkich ustaleń i ticketów, które rozumiały głównie osoby aktualnie siedzące w kontekście. OpenSpec wygląda jak próba znalezienia środka: spec ma być lekki, praktyczny i blisko implementacji, ale jednocześnie wystarczająco formalny, żeby człowiek i AI mogli pracować na tych samych założeniach.

To podejście dobrze wpisuje się w to, jak ja patrzę na ewolucję developmentu. Najpierw mieliśmy cięższe modele procesowe, które dobrze rozumiały wagę weryfikacji. Potem przyszły BDD i Specification by Example, które nauczyły nas mówić o systemie językiem zachowań i przykładów. Teraz dochodzi AI, które wymusza jeszcze większą precyzję, bo każda luka w założeniach bardzo szybko zamienia się w błędną implementację. OpenSpec jest więc dla mnie nie tyle rewolucją, co dobrze nazwanym etapem dojrzewania praktyk inżynierskich.

Co konkretnie wyróżnia OpenSpec?

Na stronie projektu OpenSpec jest przedstawiany jako framework universal, open source, bez API keys i bez MCP. To jest istotne z kilku powodów. Po pierwsze, obniża próg wejścia. Po drugie, pozwala myśleć o nim bardziej jak o metodzie pracy niż o kolejnym płatnym produkcie. Po trzecie, dobrze pasuje do realiów zespołów, które chcą testować podejście spec-driven bez przepisywania całego stacku narzędziowego. 

Repozytorium i changelog pokazują też, że projekt jest aktywnie rozwijany. Na dziś publicznie widoczna wersja pakietu to 1.2.0, a w ostatnich zmianach pojawiały się między innymi profile instalacyjne, możliwość tworzenia kompletnych propozycji zmian w jednym kroku oraz rozszerzenia wsparcia dla kolejnych agentów. Changelog wspomina też o konfigurowalnych schematach workflow w katalogu openspec/schemas/, które można współdzielić przez repozytorium. To akurat bardzo ciekawy trop dla zespołów, które chcą mieć własny, powtarzalny sposób opisywania zmian. 

Dlaczego ten projekt ma sens właśnie teraz?

Bo jesteśmy w bardzo specyficznym momencie rynku. Z jednej strony mamy ogromny entuzjazm wobec AI coding assistants. Z drugiej – coraz więcej zespołów zaczyna widzieć, że samo „kodowanie z prompta” nie skaluje się dobrze w większych inicjatywach.

Na początku wszystko wygląda świetnie. Agent szybko wygeneruje komponent, endpoint, test albo migrację. Potem jednak zaczynają się schody: brak spójności między modułami, różne interpretacje tych samych reguł biznesowych, niespójne nazewnictwo, rozjazdy między dokumentacją a kodem, niejasne decyzje architektoniczne. Innymi słowy: dokładnie te same problemy co dawniej, tylko dostarczane szybciej.

OpenSpec trafia więc w bardzo realną potrzebę: jak sprawić, żeby szybkość AI nie rozwalała jakości i przewidywalności delivery? Odpowiedź brzmi: przez lepsze, bardziej strukturalne uzgadnianie zmian.

OpenSpec a BDD, ADR i dokumentacja architektoniczna

To, co szczególnie warto podkreślić, to fakt, że OpenSpec nie powinien być traktowany jako konkurencja dla innych praktyk inżynierskich. Moim zdaniem największy sens ma wtedy, gdy działa jako warstwa spinająca kilka światów naraz.

Z BDD łączy go myślenie o zachowaniach i o tym, że system trzeba opisać przez oczekiwane rezultaty. Z ADR-ami łączy go potrzeba utrwalenia decyzji, które wpływają na sposób implementacji. Z dokumentacją architektoniczną łączy go to, że specyfikacja nie dotyczy tylko funkcji, ale też granic, zależności i ograniczeń.

W praktyce wyobrażam sobie bardzo sensowny model pracy: biznes i analityk definiują intencję zmiany, BDD doprecyzowuje zachowanie, ADR utrwala decyzje techniczne, a OpenSpec spina to w workflow, który staje się wejściem dla człowieka i AI. W takim układzie spec przestaje być pojedynczym dokumentem. Staje się zestawem powiązanych artefaktów, które razem prowadzą implementację.

Najciekawsza lekcja z OpenSpec: spec jako aktywny artefakt

Jeśli miałbym wyciągnąć z OpenSpec jedną najważniejszą lekcję, to byłaby nią zmiana sposobu myślenia o specyfikacji. Nie jako o obowiązkowym załączniku do projektu. Nie jako o slajdach do governance. Nie jako o „analizie, którą ktoś gdzieś napisał”.

Spec w tym podejściu jest aktywnym artefaktem delivery. Czymś, co ma realny wpływ na to, co zostanie zbudowane i jak będzie weryfikowane. To jest bardzo zdrowe przesunięcie. Szczególnie dla zespołów technicznych, które przez lata często traktowały dokumentację jako przykry obowiązek, bo dokumenty faktycznie nie brały udziału w pracy wytwórczej.

W świecie AI to się zmienia. Dobrze przygotowany spec staje się wejściem dla generatorów kodu, testów, opisów zmian, a czasem nawet dokumentacji. To sprawia, że jego jakość zaczyna mieć bezpośredni wpływ na koszt, szybkość i ryzyko projektu.

Czy OpenSpec rozwiązuje wszystko?

Nie. I to akurat dobra wiadomość, bo narzędzia, które obiecują rozwiązanie wszystkiego, zwykle robią jedną rzecz dobrze: marketing.

OpenSpec nie zwalnia zespołu z myślenia. Nie napisze za nas sensownej domeny. Nie podejmie wszystkich decyzji architektonicznych. Nie zamieni słabego backlogu w świetny produkt. Ale wygląda na bardzo sensowny mechanizm, który może poprawić jakość współpracy między ludźmi, dokumentacją i AI assistantami.

To trochę jak z dobrym szablonem ADR albo dobrze użytym Gherkinem. Sam szablon nie gwarantuje jakości, ale potrafi bardzo pomóc w uporządkowaniu myślenia i ograniczeniu chaosu. OpenSpec wydaje się właśnie takim rodzajem narzędzia – wzmacnia praktykę, jeśli zespół naprawdę chce pracować świadomie.

Gdzie widzę dla niego najlepsze zastosowania?

Największy potencjał widzę w kilku sytuacjach.

Po pierwsze, w zespołach, które już korzystają z AI coding assistants, ale zaczynają odczuwać koszt niejednoznaczności. Po drugie, w projektach z istotną logiką biznesową, gdzie liczą się reguły, wyjątki i traceability. Po trzecie, w środowiskach, gdzie chcemy połączyć specyfikację funkcjonalną, decyzje techniczne i automatyzację jakości bez wchodzenia w zbyt ciężki proces.

Szczególnie dobrze wygląda to dla organizacji, które chcą tworzyć własne standardy pracy z AI. Changelog sugeruje możliwość definiowania własnych schematów workflow, a to oznacza, że OpenSpec może być nie tylko narzędziem do pracy indywidualnej, ale też bazą pod wewnętrzny operating model dla AI-assisted development

Moja opinia na dziś

Patrzę na OpenSpec jak na jeden z najciekawszych praktycznych sygnałów, że Spec-Driven Development zaczyna wychodzić poza poziom hasła. Projekt jest spójny z realnym problemem rynku, ma jasną filozofię i nie próbuje udawać, że sama obecność AI zwalnia nas z dyscypliny inżynierskiej.

To, co najbardziej kupuję, to nacisk na uzgadnianie tego, co budujemy przed napisaniem kodu. Brzmi banalnie? Oczywiście. A jednak właśnie ten banał jest dziś nagminnie pomijany, bo wszyscy zachwycili się szybkością generowania implementacji.

Moim zdaniem OpenSpec jest wartościowe nie dlatego, że daje kolejny CLI, ale dlatego, że przypomina o czymś fundamentalnym: software nadal trzeba świadomie projektować, nawet jeśli znaczną część kodu generuje AI.

Podsumowanie

Jeśli poprzedni artykuł z cyklu {dev} forge – How software is forged with AI był próbą pokazania, skąd wzięło się Spec-Driven Development, to ten wpis pokazuje pierwszy konkretny przykład narzędziowego ucieleśnienia tej idei.

OpenSpec to lekki, otwarty framework dla spec-driven development, który porządkuje współpracę z AI coding assistantami wokół specyfikacji, zamiast opierać wszystko na ulotnym kontekście rozmowy. Bazuje na prostym workflow typu propose → apply → archive, jest open source, nie wymaga API keys ani MCP, i aktywnie się rozwija. 

I to właśnie dlatego uważam, że warto go obserwować. Nie jako cudowną receptę na cały software engineering, ale jako bardzo sensowny krok w kierunku bardziej świadomego, przewidywalnego i spec-driven wytwarzania oprogramowania z udziałem AI.

Źródło 
Źródło

wtorek, 24 marca 2026

{dev}forge: Spec-Driven Development - czym jest i z czego wyewoluowało?

W świecie wytwarzania oprogramowania co jakiś czas pojawiają się pojęcia, które brzmią jak kolejna moda. Najpierw „Agile”, potem „Shift Left”, później „Platform Engineering”, a dziś coraz częściej przewija się Spec-Driven Development. Na pierwszy rzut oka można pomyśleć, że to po prostu nowe opakowanie dla starych praktyk. I trochę tak jest. Ale tylko trochę.



Moim zdaniem Spec-Driven Development to nowoczesny, AI-powered potomek V-Modelu, mocno wzbogacony o BDD i Specification by Example. Gdybym miał ująć to jeszcze prościej, powiedziałbym tak:

  • dziadek: V-Model,
  • najbliższy kuzyn: BDD / Specification by Example,
  • współczesna forma: Spec-Driven Development wspierane przez AI.

I właśnie z tej perspektywy warto o tym podejściu rozmawiać. Nie jako o rewolucji znikąd, ale jako o logicznej ewolucji sposobu, w jaki próbujemy zamieniać potrzeby biznesowe na działające oprogramowanie.

Skąd w ogóle bierze się potrzeba Spec-Driven Development?

Od lat branża zmaga się z tym samym problemem: co dokładnie mamy zbudować? Nie jak to zakodować. Nie w jakim frameworku. Nie czy lepszy będzie monolit czy mikroserwisy. Najpierw trzeba odpowiedzieć na dużo bardziej podstawowe pytanie: jaki problem rozwiązujemy i po czym poznamy, że rozwiązanie jest poprawne?

Przez długi czas odpowiedzią były rozbudowane dokumenty analityczne, opisy wymagań, makiety, modele procesów i grube specyfikacje funkcjonalne. Problem polegał na tym, że dokumentacja bardzo często żyła własnym życiem. Była tworzona na początku projektu, a potem kod zaczynał iść w swoją stronę.

Z drugiej strony pojawił się świat zwinny, który słusznie zwrócił uwagę, że dokumentacja bez wartości wykonawczej niewiele daje. Tyle że w wielu zespołach skręcono za mocno w przeciwną stronę. Zaczęło dominować podejście typu: „dogadamy się na daily”, „doprecyzujemy w trakcie”, „zobaczymy w refinement”. I nagle okazało się, że brak precyzyjnej specyfikacji wcale nie oznacza większej zwinności. Często oznacza po prostu chaos.

Spec-Driven Development wyrasta właśnie z tej frustracji. Z potrzeby odzyskania specyfikacji, ale w formie, która nie jest martwym dokumentem. Ma być żywa, operacyjna, testowalna i coraz częściej także czytelna dla modeli AI.

Dziadek, czyli V-Model

Jeżeli szukać przodka tego podejścia, to dla mnie jest nim V-Model. To stary, momentami niedoceniany model, który miał jedną wielką zaletę: traktował specyfikację i walidację bardzo serio.

W V-Modelu każdemu poziomowi analizy i projektowania odpowiadał poziom weryfikacji. Wymagania biznesowe miały swoje testy akceptacyjne. Wymagania systemowe miały testy systemowe. Projekt techniczny miał testy integracyjne i jednostkowe. Była w tym pewna elegancja. Logika była prosta: jeśli coś definiujesz, to musisz też wiedzieć, jak sprawdzisz, że zostało dobrze zrealizowane.

To jest właśnie fundament, który wraca dziś pod nową nazwą. Spec-Driven Development odziedziczyło po V-Modelu kilka bardzo ważnych cech:

  • szacunek do specyfikacji,
  • powiązanie wymagań z walidacją,
  • myślenie o traceability,
  • założenie, że implementacja nie powinna być oderwana od intencji biznesowej.

Oczywiście współczesne projekty nie chcą wracać do ciężkiego, liniowego procesu, w którym pół roku piszemy dokumenty, a potem drugie pół roku kod. I słusznie. Ale warto zauważyć, że sam rdzeń V-Modelu – czyli relacja między specyfikacją a testowaniem – był bardzo zdrowy.

Kuzyn, czyli BDD i Specification by Example

Potem przyszły praktyki, które zaczęły tłumaczyć wymagania na bardziej praktyczny język. Tutaj pojawiają się BDD oraz Specification by Example. I właśnie one są dla Spec-Driven Development najbliższą rodziną.

BDD nauczyło zespoły, że zachowanie systemu można opisywać w sposób zrozumiały nie tylko dla programistów, ale też dla biznesu i testerów. Scenariusze w stylu Given / When / Then nie były już tylko notatką. Stawały się kontraktem. Czymś, co da się zautomatyzować, sprawdzić i utrzymać.

Specification by Example poszło jeszcze dalej. Zamiast pisać abstrakcyjne wymagania, zaczęliśmy opierać się na konkretnych przykładach. Nie „system powinien poprawnie liczyć rabaty”, tylko: „dla klienta premium z koszykiem powyżej 500 zł rabat powinien wynieść 10%”. Nagle wymagania przestały być mgłą. Stały się czymś namacalnym.

To właśnie dlatego uważam, że BDD i Specification by Example są najbliższymi kuzynami Spec-Driven Development. Bo wprowadziły trzy rzeczy, bez których SDD nie miałoby sensu:

  • operacyjny język opisu wymagań,
  • przykłady jako nośnik wiedzy domenowej,
  • bezpośrednie połączenie specyfikacji z testami.

Co zmieniło się dziś? Pojawienie się AI

No dobrze, skoro tyle rzeczy już było, to po co nowa nazwa? Bo pojawił się nowy czynnik, który zmienia stawkę gry: AI.

Jeszcze kilka lat temu specyfikacja była głównie artefaktem dla ludzi. Analityk pisał ją dla biznesu, architekta, programisty i testera. Dziś dochodzi nowy uczestnik procesu: model językowy, agent kodujący albo zestaw narzędzi wspierających development. I nagle okazuje się, że jakość specyfikacji zaczyna mieć wpływ nie tylko na komunikację w zespole, ale też na jakość generowanego kodu, testów, dokumentacji czy propozycji architektury.

To jest moment, w którym spec staje się interfejsem. Nie tylko między biznesem a IT, ale również między człowiekiem a AI.

Jeżeli specyfikacja jest niejasna, sprzeczna albo zbyt ogólna, to AI zrobi dokładnie to, co zwykle robi człowiek pod presją czasu: zgadnie. Czasem dobrze, czasem źle, ale niemal zawsze z dużą pewnością siebie. A to oznacza, że w erze AI dobrze napisana specyfikacja przestaje być „miłym dodatkiem”. Staje się narzędziem sterowania wytwarzaniem.

Czym więc jest Spec-Driven Development?

Spec-Driven Development to podejście, w którym specyfikacja nie jest dokumentem archiwalnym, ale centralnym artefaktem sterującym projektowaniem, implementacją, testami i coraz częściej także pracą AI.

W praktyce oznacza to, że zanim powstanie kod, próbujemy zbudować możliwie precyzyjny opis:

  • jaki problem rozwiązujemy,
  • jakie są reguły biznesowe,
  • jakie zachowania są oczekiwane,
  • jakie scenariusze muszą przejść,
  • jakie ograniczenia architektoniczne obowiązują,
  • oraz po czym rozpoznamy, że rozwiązanie jest gotowe.

Spec może przyjmować różne formy. To może być zestaw user stories, scenariuszy BDD, ADR-ów, opisów API, kontraktów danych, reguł domenowych, diagramów czy nawet checklist jakościowych. Ważne jest nie tyle medium, ile rola, jaką ten artefakt pełni.

W Spec-Driven Development specyfikacja:

  • prowadzi implementację,
  • ogranicza pole domysłów,
  • umożliwia automatyzację testów,
  • wspiera traceability,
  • i może być bezpośrednim wejściem dla narzędzi AI.

Dlaczego nie wystarczy samo „promptowanie” AI?

Tu dochodzimy do bardzo praktycznego problemu. Wiele zespołów zachwyca się dziś tym, że można „po prostu opisać funkcję” agentowi kodującemu i dostać działający wynik. I jasne – to działa. Zwłaszcza dla małych, izolowanych zadań. Problem pojawia się później.

Bez uporządkowanej specyfikacji zaczynają się klasyczne kłopoty:

  • sprzeczne decyzje między modułami,
  • różne interpretacje tych samych wymagań,
  • brak spójności między kodem, testami i dokumentacją,
  • trudność w ocenie, czy feature faktycznie jest gotowy,
  • chaos w kolejnych iteracjach rozwoju.

AI potrafi bardzo przyspieszyć produkcję, ale nie rozwiązuje magicznie problemu niejednoznaczności. Wręcz przeciwnie – potrafi go zwielokrotnić, bo błędne założenia można teraz wdrażać szybciej niż kiedykolwiek wcześniej.

Dlatego uważam, że Spec-Driven Development jest naturalną odpowiedzią na epokę AI-assisted development. To nie jest hamulec dla szybkości. To układ kierowniczy.

Jakie elementy najczęściej tworzą podejście spec-driven?

Choć nie ma jednego, kanonicznego standardu, to w praktyce ten styl pracy zwykle opiera się na kilku warstwach.

1. Kontekst biznesowy

Zaczynamy od odpowiedzi na pytanie: po co to robimy? Jakie pain pointy rozwiązujemy? Jakie KPI lub cele biznesowe za tym stoją? Bez tego nawet najlepsza specyfikacja funkcjonalna może prowadzić do świetnie wykonanego, ale niepotrzebnego rozwiązania.

2. Specyfikacja zachowań

Tutaj pojawiają się user stories, przykłady, scenariusze BDD, kryteria akceptacji i reguły biznesowe. To ta część, która mówi, jak system powinien się zachowywać z perspektywy użytkownika i domeny.

3. Ograniczenia projektowe i architektoniczne

To miejsce na decyzje techniczne, ADR-y, zasady integracji, kontrakty API, standardy bezpieczeństwa, wydajności i obserwowalności. Innymi słowy: nie tylko co ma działać, ale też w jakich ramach ma działać.

4. Walidacja

Spec bez walidacji jest tylko ambitną deklaracją. Dlatego potrzebne są testy, checklisty, scenariusze automatyczne i mechanizmy traceability. To właśnie tu wraca DNA V-Modelu.

5. Wykorzystanie AI jako wykonawcy lub współautora

W nowoczesnym wydaniu specyfikacja może być wejściem dla modeli generujących kod, testy, dokumentację, diagramy czy nawet migracje. Ale jakość efektu zależy od jakości specyfikacji. Garbage in, garbage out – tylko szybciej.

Największa różnica względem starego podejścia do dokumentacji

W tradycyjnych projektach dokumentacja często była produktem ubocznym procesu. W Spec-Driven Development dokumentacja-specyfikacja staje się aktywnym elementem delivery.

To subtelna, ale ogromna zmiana. Nie piszemy specyfikacji „bo governance wymaga”. Piszemy ją po to, by:

  • lepiej myśleć o problemie,
  • uzgodnić znaczenie pojęć,
  • zmniejszyć ryzyko złej interpretacji,
  • móc automatyzować walidację,
  • i skuteczniej współpracować z AI.

To dlatego dobrze zrobione SDD nie przypomina ciężkiej analizy sprzed dekad. Bardziej przypomina zestaw połączonych artefaktów, które razem prowadzą zespół od intencji biznesowej do gotowego rozwiązania.

Dlaczego teraz ten temat wraca z taką siłą?

Bo dojrzały trzy światy naraz.

Po pierwsze, dojrzał świat domenowy. Firmy lepiej rozumieją dziś, że przewaga nie leży tylko w kodzie, ale w poprawnym odwzorowaniu procesów, reguł i wyjątków.

Po drugie, dojrzał świat automatyzacji jakości. Testy automatyczne, kontrakty API, pipeline’y CI/CD, quality gates – to wszystko sprawiło, że specyfikację można realnie powiązać z wykonaniem.

Po trzecie, dojrzał świat AI. A wraz z nim pojawiła się ogromna potrzeba tworzenia artefaktów, które są jednoznaczne, modularne i nadają się do użycia przez ludzi oraz modele.

Właśnie na przecięciu tych trzech światów rodzi się dzisiejsze zainteresowanie Spec-Driven Development.

Moja robocza definicja

Na potrzeby tego cyklu przyjąłbym taką roboczą definicję:

Spec-Driven Development to podejście do tworzenia oprogramowania, w którym centralną rolę pełni specyfikacja opisująca zachowanie, reguły i ograniczenia systemu, a sama specyfikacja służy jako podstawa do projektowania, implementacji, testów i współpracy z AI.

Ta definicja jest szeroka, ale celowo. Nie chcę zamykać tematu w jednym frameworku czy modnej etykiecie. Bardziej interesuje mnie praktyczny kierunek: jak tworzyć specyfikacje, które naprawdę pomagają dowozić systemy lepiej, szybciej i bardziej przewidywalnie.

Czego można spodziewać się w dalszej części cyklu?

To dopiero pierwszy artykuł z cyklu {dev} forge - How software is forged with AI, więc na razie ustawiamy scenę. W kolejnych wpisach warto będzie wejść głębiej w tematy takie jak:

  • jak wygląda dobra specyfikacja dla AI-powered development,
  • jak łączyć SDD z BDD, ADR-ami i dokumentacją architektoniczną,
  • gdzie kończy się specyfikacja biznesowa, a zaczyna techniczna,
  • jak utrzymywać spójność między specem, kodem i testami,
  • oraz jakich błędów unikać, żeby nie stworzyć nowej wersji „martwej dokumentacji”.

Podsumowanie

Spec-Driven Development nie wzięło się znikąd. To nie jest przypadkowy buzzword wykreowany tylko dlatego, że pojawiły się modele generatywne. To raczej kolejny etap dojrzewania branży.

Z jednej strony odziedziczyliśmy po V-Modelu szacunek do relacji między wymaganiem a weryfikacją. Z drugiej strony BDD i Specification by Example nauczyły nas, że wymagania trzeba opisywać poprzez zachowania i konkretne przykłady. Dziś dokładamy do tego AI, które potrafi działać jako współtwórca rozwiązania – pod warunkiem, że dostanie sensowną, spójną i operacyjną specyfikację.

I właśnie dlatego uważam, że Spec-Driven Development to nowoczesny, AI-powered potomek V-Modelu, mocno wzbogacony o BDD i Specification by Example.

Brzmi jak rodzinne spotkanie metodyk? Trochę tak. Ale tym razem z całkiem praktycznym efektem: lepszym mostem między intencją, implementacją i jakością.