SpecScore vs Zwykły Markdown
Większość zespołów ma już jakieś „specyfikacje” — w postaci notatek Markdown w folderze docs, stron w Notion czy ticketów w Jirze. To nic nie kosztuje, już tam jest i działa. SpecScore to ten sam Markdown, plus struktura, którą agent AI może lintować, odpytywać i powiązać z kodem.
Co je łączy.
Co domyślne podejście robi dobrze.
Zwykły Markdown, Notion i Jira to powszechny standard. Zasłużyły na to.
Zerowy próg nauki
Brak schematów, brak wymaganych pól, brak konieczności używania CLI. Otwierasz plik i zaczynasz pisać. W przypadku szybkiej notatki lub małego projektu to idealne rozwiązanie — zbędna struktura to tylko dodatkowy opór.
Już jest w użyciu
Twój zespół już korzysta z Notion, Confluence lub katalogu docs/. Nie trzeba niczego wdrażać ani migrować. Narzędzie o najniższym oporze to to, którego już używasz.
Uniwersalna przenośność
Zwykły Markdown otworzy się wszędzie i przetrwa każde narzędzie. SpecScore bazuje dokładnie na tej właściwości — dlatego SpecScore to również Markdown, a nie baza danych.
Porównanie możliwości.
Różnica nie tkwi w samym pliku — lecz w tym, co agent może z nim zrobić.
| Możliwość | Zwykły Markdown / Notion | SpecScore |
|---|---|---|
| Format | Dowolny Markdown / dokumenty | Markdown + YAML frontmatter (strukturalny) |
| Gdzie żyją wymagania | Jira, Notion, Slack, w czyjejś głowie | W repozytorium, obok kodu |
| „Czy ta specyfikacja jest kompletna?” | Człowiek musi przeczytać i ocenić | specscore lint — automatycznie |
| Wykrywanie niejednoznaczności | Brak — nieprecyzyjne czasowniki przechodzą niezauważone | Wskazywanie niejasnych czasowników, brakujących AC i wiszących linków |
| ID wymagań / AC | Brak | Adresowalne maszynowo ID (REQ: slug) |
| Status cyklu życia | Domniemany, o ile w ogóle śledzony | Egzekwowany — Draft → Approved → Implementing → Stable |
| Śledzenie kod-do-specyfikacji | Brak | Adnotacje specscore: + trailery Verifies: |
| Nawigacja dla agentów | Czytanie każdego pliku, by cokolwiek znaleźć | Odpytywanie grafu specyfikacji przez CLI |
| Bramka jakości w CI | Brak | specscore lint kończy się kodem niezerowym, jak linter |
| Próg wejścia | Żaden | Jeden format do opanowania (stopniowo) |
| Koszt / licencja | Darmowe | Darmowe, open source |
Gdzie SpecScore idzie dalej.
Niejednoznaczność jest wykrywana, a nie interpretowana
Przy swobodnych specyfikacjach każda interakcja z agentem zaczyna się od interpretacji — „logowanie powinno działać” to rzut monetą między poprawnym a prawdopodobnym, lecz błędnym kodem. lint w SpecScore wskazuje nieprecyzyjny czasownik i brak kryteriów akceptacji, zanim agent w ogóle przystąpi do pracy.
$ specscore lint auth/login.md ✗ R1 "should work" — niemierzalne ✗ R1 no acceptance criteria
Koniec z nawarstwianiem się błędnych założeń
Jeden agent źle zinterpretuje wymaganie, drugi zbuduje na nim swoje rozwiązanie, trzeci zależy od obu — a Ty dowiadujesz się o tym trzy agenty za późno. Ustrukturyzowane kryteria akceptacji dają każdemu agentowi dokładnie te same warunki zaliczenia, zapobiegając dryfowaniu założeń.
Kod odsyła bezpośrednio do specyfikacji
Zwykła dokumentacja nie ma powiązania z kodem, który ją realizuje. SpecScore wprowadza adnotacje w kodzie źródłowym specscore: oraz trailery w commitachVerifies: — polecenie specscore code refs odpowiada deterministycznie na pytanie „jaki kod implementuje to wymaganie?”.
Jedna specyfikacja zamiast czterdziestu ticketów
Nowy członek zespołu (lub świeży kontekst agenta) czyta specyfikację funkcji z pełnym kontekstem, zamiast mozolnie odtwarzać intencje z czterdziestu zadań w Jirze i wątku na Slacku.
Agenci odpytują, zamiast czytać wszystko od nowa
W folderze z dokumentacją znalezienie „co jest w trakcie realizacji?” wymaga otwierania kolejnych plików. W SpecScore to po prostu specscore feature list — graf specyfikacji odpowiada z poziomu CLI, więc agenci nie marnują okna kontekstowego na ponowne czytanie repozytorium.
Jakość egzekwowana w CI
Swobodne specyfikacje nie mają żadnych bramek — niedokończony draft przechodzi w merge tak samo łatwo jak gotowy dokument. specscore lint zwraca niezerowy kod wyjścia przy wykryciu problemów, chroniąc specyfikację tak, jak ESLint lub go vet chronią kod.
Kiedy wybrać które rozwiązanie.
Zwykły Markdown wystarczy, gdy…
- To pojedyncza notatka, szybki spike badawczy lub projekt zbyt mały, by wymagać struktury.
- Żaden agent AI nie będzie implementował kodu na podstawie dokumentu — człowiek po prostu go przeczyta i zrozumie.
- Zapisujesz wstępny pomysł, a nie wymaganie, które ktoś ma precyzyjnie wdrożyć.
Wybierz SpecScore, gdy…
- Agent AI pisze kod na podstawie specyfikacji — niejednoznaczność zamienia się w błędny kod.
- Wielu agentów lub programistów polega na tych samych wymaganiach.
- Chcesz wiedzieć, który fragment kodu implementuje które wymaganie.
- Na pytanie „czy ta specyfikacja jest gotowa?” powinno odpowiadać narzędzie, a nie spotkanie.
- Projekt jest na tyle duży, że czytanie wszystkiego od nowa przestaje się skalować.
Rozwijaj specyfikacje, które już masz.
Nie musisz konwertować całego backlogu ani wymieniać narzędzi. Wybierz kolejną funkcję, napisz dla niej specyfikację w formacie SpecScore i uruchom specscore lint — zobacz, czy wychwyci coś, co umknęło w tickecie. Dodaj adnotacje specscore:podczas implementacji. Rozszerzaj na kolejne sprinty tylko wtedy, gdy przynosi to realną wartość.
Zwykły Markdown to punkt wyjścia. SpecScore to jego naturalna ewolucja.
Inne porównania.
Ten sam format, obok innych narzędzi rozwoju sterowanego specyfikacją:
Wszystkie razem, na jednej stronie: najlepsze narzędzia rozwoju sterowanego specyfikacją w 2026.
Opinia
To porównanie opiera się na publicznie dostępnej dokumentacji i kodzie źródłowym. Coś jest błędne lub nieaktualne? otwórz issue z poprawką. Chcesz, żebyśmy porównali SpecScore z innym narzędziem? poproś o nie.