# Każda niejednoznaczność w specyfikacji to token, który pali Twój agent.

Canonical: https://specscore.md/pl/

SpecScore to otwarty format plików dla specyfikacji, sprawdzany linterem, zapisany w Markdown i YAML (YAML Ain't Markup Language) — jak JSON (JavaScript Object Notation) dla danych — z interfejsem wiersza poleceń (CLI), który Twoje agenty wywołują, by je przeszukiwać i edytować, jak `jq` dla JSON-a.

Ostatnia aktualizacja: 30 października 2026

Potem pytanie doprecyzowujące w trakcie prac. Potem poprawka po wdrożeniu. Potem kontekst, który tłumaczysz w kółko od nowa.

 Open source na GitHubie Skille AI dla Twojego agenta Zainstaluj CLI

## Format dla specyfikacji, które już teraz piszesz.

**SpecScore to format Markdown + YAML** dla funkcji, wymagań i kryteriów akceptacji. Definiuje strukturę zrozumiałą zarówno dla Twojego zespołu, jak i agentów AI — to po prostu zwykłe pliki w Twoim repozytorium.

Projekt SpecScore składa się z trzech rodzajów artefaktów w cyklu życia:**Idea** rejestruje wstępny kierunek; specyfikacja**Feature** zamraża uzgodnione zachowanie;**Plan** dzieli funkcję na uporządkowane zadania, z których każde wskazuje spełniane kryteria akceptacji.

**Dlaczego to ważne dla Twojego agenta.** Ponieważ struktura jest czytelna maszynowo, agenci AI mogą odpytywać specyfikację przez CLI zamiast czytać każdy plik. Zapytaj*„nad czym powinienem teraz pracować?”*, a CLI zwróci otwarte Features i pytania bez odpowiedzi. Ta sama forma, którą weryfikuje Twój zespół; znacznie mniejszy kontekst do załadowania przez agenta.

 Feature → Wymagania → Kryteria Akceptacji → Scenariusze. idea → feature → plan PRZYKŁAD ideas/apply-discount.md

```
# Idea: Discount codes at checkout **Status:** Approved **Date:** 2026-05-19 **Owner:** cart-team **Promotes To:** features/apply-discount ## Problem Statement How might we let returning customers redeem a single promo code at checkout without breaking the existing cart math or the site-wide promotion engine? ## Recommended Direction A registered user can apply **one** valid code per cart. Codes are time-bounded and replaceable. Stacking with site-wide promotions follows a deterministic tiebreak rule (higher discount wins; site-wide wins on tie).
```

 PRZYKŁAD features/checkout/apply-discount.md

```
--- status: approved owners: [cart-team] --- # Feature: Apply Discount A registered user can apply one valid discount code to their cart at checkout. ## Requirements ### R1 — Single-code limit - **AC-1** The cart accepts at most one discount code at a time. - **AC-2** Applying a second code replaces the first, with a visible confirmation. - **AC-3** Removing the code restores the original cart total. ### R2 — Code validity - **AC-1** A code is valid only if `valid_from` ≤ now ≤ `valid_until` . - **AC-2** Invalid codes show a specific error message. ### R3 — Discount application - **AC-1** Percentage discounts apply to subtotal, not shipping. - **AC-2** Discount totals round down to the nearest cent. - **AC-3** Stacking with site-wide promotions follows the higher-of rule. ## Scenario: Apply a valid percent-off code **GIVEN** a cart with subtotal $50.00 and shipping $10.00 **WHEN** the user applies code `SAVE20` (20% off) **THEN** the cart shows subtotal $40.00, shipping $10.00, total $50.00
```

 PRZYKŁAD plans/apply-discount/README.md

```
# Plan: Apply Discount **Status:** approved **Features:** - [apply-discount](../../features/apply-discount.md) **Author:** cart-team **Effort:** M **Impact:** high ## Context The apply-discount Feature is Approved. This plan breaks it into ordered tasks; each task cites the acceptance criteria it satisfies. ## Tasks ### T1 — Accept a `code` field on the cart Cites: R1.AC-1, R1.AC-2, R1.AC-3 ### T2 — Validate code time-window Cites: R2.AC-1, R2.AC-2 ### T3 — Apply percentage to subtotal, round down Cites: R3.AC-1, R3.AC-2 ### T4 — Higher-of tiebreak vs site-wide promo Cites: R3.AC-3 ### T5 — Confirmation toast on apply / replace Cites: R1.AC-2
```

## Specyfikacje są hierarchiczne. Twoje drzewo specyfikacji też.

Płaska lista przy pięćdziesięciu Features staje się wysypiskiem. SpecScore dba o przejrzystość drzewa: elementy nadrzędne określają zakres, podrzędne szczegóły, a struktura katalogów odzwierciedla kształt produktu, o którym Twój zespół już myśli.

**Otwarte pytania agregują się w górę.** Nierozstrzygnięte pytania na dowolnej głębokości pojawiają się w indeksie każdego rodzica. Widzisz z samego szczytu drzewa, co blokuje wydanie, bez konieczności przeszukiwania każdego pliku.

Większość narzędzi zakłada, że płaska lista wystarczy. I tak jest — do czasu. SpecScore powstał z myślą o momencie, w którym pytanie „gdzie powinna znaleźć się ta Feature?” zaczyna mieć znaczenie.

[Zobacz na żywo w specscore-cli →](https://specscore.studio/app/github.com/specscore/specscore-cli/spec/features/cli?op=explore)

 Z specscore-cli/spec/features/cli/

```
spec/features/cli/ ├── agent/ │ └── setup/ ├── feature/ │ ├── change-status/ │ ├── deps/ │ ├── info/ │ ├── list/ │ ├── new/ │ ├── refs/ │ └── tree/ ├── idea/ │ ├── change-status/ │ ├── new/ │ └── relocate/ ├── spec/ │ └── lint/ │ ├── issue-rules/ ← sub-sub-Feature │ └── plan-rules/ ├── task/ │ ├── info/ │ ├── list/ │ └── new/ └── … jeszcze 10 Features najwyższego poziomu
```

## Co zawodzi, gdy go brakuje.

- ### 🌀 Specyfikacje dryfują. Specyfikacja w dokumencie, wątek na Slacku i kod w PR po cichu rozmijają się tygodniami. Nikt nie wie, która wersja ustaleń jest kanoniczna. Rozwiązanie Jedna kanoniczna specyfikacja, w repozytorium, wersjonowana z kodem.`specscore lint` uruchamia się w CI przy każdym pushu; historia gita to pełny audyt. Specyfikacja, wątek i PR nie mogą się rozjechać — współdzielą ten sam recenzowany plik.
- ### 🌫️ AC pozostają niejasne. *"Elegancko obsługuje błędy"* miało znaczyć*"pokaż powiadomienie toast i wycofaj zmiany."* A może*"zaloguj i ponów próbę?"* Agent musi zgadywać. Rozwiązanie Linter wychwytuje niejednoznaczne kryteria, zanim powstanie choćby linijka kodu. Czasownik nie przechodzi linta, bo brakuje mu konkretnego obiektu lub warunku. Poprawienie ostrzeżenia zmusza do zdefiniowania, co tak naprawdę oznacza*"obsługuje"*.
- ### 🤖 Agenci dostarczają nie to, co trzeba. Ludzie dopowiadają sobie kontekst, pytają, uściślają. Agenci AI tego nie robią — wdrażają wzorzec, który najczęściej pojawiał się w ich danych treningowych. Kod przechodzi review, bo robi **coś** sensownego. Tyle że nie to, co miałeś na myśli. Rozwiązanie Ustrukturyzowane wejście. Agenci AI deterministycznie parsują identyfikatory REQ, AC oraz scenariusze`GIVEN / WHEN / THEN`— nie ma tu miejsca na domysły. Zadania w Planie muszą wskazywać identyfikatory AC, które realizują, dzięki czemu to, co zbudowano, można w każdej chwili zweryfikować ze specyfikacją.
- ### 🔁 Płacisz podwójnie za mętną specyfikację. Agent buduje coś na podstawie niejednoznacznego opisu, zauważasz błąd i promptujesz ponownie — na cztery różne sposoby. Każda niedokończona funkcja i każda powtórka kosztują tokeny. Im bardziej mętna specyfikacja, tym więcej rund potrzeba na jej ukończenie. Rozwiązanie Przeanalizuj specyfikację linterem, zanim uruchomisz agenta.`specscore lint` z góry odrzuca nieprecyzyjne czasowniki i brakujące kryteria akceptacji, więc agent od razu implementuje konkretny opis zamiast błądzić w kolejnych próbach. Najtańsze wywołanie agenta to to, którego nie musisz powtarzać.
- ### 💸 Agenci płacą za ponowne czytanie specyfikacji. Agent AI odpowiadając na pytanie *"co zależy od tej funkcji?"* czyta całe README funkcji. Potem indeks każdego rodzica. Potem sąsiednie funkcje na wszelki wypadek. Każde zapytanie to ponowne parsowanie. Tokeny ulatują, rośnie opóźnienie, a wraz z nim rachunek. Rozwiązanie Strukturalne zapytania zamiast czytania plików.`specscore feature tree` zwraca hierarchię jako YAML; `feature deps` przechodzi cały łańcuch zależności; `feature info` zwraca status, właściciela i otwarte pytania — wszystko w jednym wywołaniu. Agent porusza się po grafie, a nie po tekście.
- ### 🔗 Kod zapomina o swojej specyfikacji. Sześć miesięcy później debugujesz funkcję i nikt nie pamięta, które wymaganie ona realizuje. Powiązanie między kodem a specyfikacją istniało tylko w czyjejś głowie, a ta osoba odeszła z pracy. PR, który ją wprowadził, leży w archiwum. Rozwiązanie Adnotacje w kodzie źródłowym. Komentarze takie jak`// specscore: features/checkout/apply-discount/R1.AC-2`sprawiają, że powiązanie jest czytelne maszynowo i przetrwa każdy refaktoring. `specscore code deps` odpowiada na pytanie *"jaką specyfikację implementuje ten plik?"* w jednym wywołaniu; linter natychmiast zgłasza referencje wskazujące na usunięte specyfikacje.
- ### 🏷️ Zmiany statusu rozjeżdżają się. Zmieniasz status funkcji z *Draft* na *Approved*w jej README, ale nadrzędny indeks funkcji wciąż ma wpisane Draft. Trzy tygodnie później agent czytający indeks uważa, że funkcja jest w trakcie zmian. Status istnieje w dwóch miejscach i te miejsca sobie przeczą. Rozwiązanie Polecenie `specscore feature change-status` zmienia pole Status w pliku funkcji i synchronizuje wiersz w indeksie w jednym atomowym kroku — błąd lintera wycofuje zmianę. Status istnieje w jednym kanonicznym miejscu, a indeks jest jego generowanym widokiem.
- ### 📋 Specyfikacje zapominają o tym, czego nie wiedzą. Specyfikacja wygląda na dopiętą — dopóki nie przypomnisz sobie, że pytanie *"a co ze strefami czasowymi?"* przepadło w wątku na Slacku dwa miesiące temu i nigdy nie trafiło do dokumentu. Jesteś w trakcie implementacji i nikt nie pamięta odpowiedzi. Rozwiązanie Każda funkcja w SpecScore ma obowiązkową sekcję**Outstanding Questions**. Linter odrzuca funkcje, które ją pomijają — pusta sekcja jest w porządku (`"None at this time."`), ale jej brak już nie. Nierozstrzygnięte kwestie są widoczne w dokumencie, dostępne przez CLI i nie da się o nich zapomnieć.

## Najprostszy sposób na start: SpecStudio Skills dla agentów AI.

[SpecStudio Skills](https://github.com/specscore/specstudio-skills)to wtyczka do Claude Code, która przekształca cykl życia SpecScore w cztery polecenia slash. Zainstaluj ją raz, a potem wywołuj je w kolejności — od surowego pomysłu aż po gotowy plan wykonania.

```
$ /plugin marketplace add specscore/ai-marketplace $ /plugin install specstudio@specscore
```

 Claude Code autouzupełnianie

```
> /specstudio: /specstudio:ideate Dopracuj surowy pomysł w Idea w formacie SpecScore /specstudio:specify Zamień zatwierdzoną Idea w specyfikację Feature /specstudio:plan Podziel Feature na Plan zadań /specstudio:implement Zrealizuj kolejne zadanie z Planu
```

 /ideate → /specify → /plan → /implement Claude Code /ideate

```
> /ideate Zastanówmy się, jak powinien wyglądać ekran koszyka w procesie checkoutu.
```

 Claude Code /specify

```
> /specify Zdefiniujmy spec/ideas/checkout-basket.md
```

 Claude Code /plan

```
> /plan Zaplanuj wdrożenie spec/features/checkout/basket/README.md
```

 Claude Code /implement

```
> /implement Wykonaj zadanie z spec/plans/checkout-basket/README.md
```

Bezpłatne do każdego zastosowania, także komercyjnego. Źródła wtyczki:[specscore/specstudio-skills](https://github.com/specscore/specstudio-skills) — na licencji MIT.

## Sprawdź specyfikację w dwóch krokach.

Szybki, deterministyczny linter, a następnie pogłębiony przegląd AI — uruchomione na specyfikacji, którą właśnie widziałeś. Dwa kroki, dwa rodzaje pewności.

### Uruchom linter.

 deterministyczny

```
$ specscore spec lint features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds features/apply-discount/refunds:0 [error] readme-exists: README.md not found 3 violations found (3 errors) # exit code 1
```

Ten sam wynik przy każdym uruchomieniu. Darmowy, szybki, uruchamiany przy każdym commicie.

### Przegląd i ocena z AI.

 niedeterministyczny

```
> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
```

Analizuje znaczenie, tak jak recenzent w zespole.

## Oto czego nie wychwyci.

Linter, który twierdzi, że wykryje wszystko, mija się z prawdą. SpecScore to system warstwowy — deterministyczny linter, recenzent AI i Twój własny osąd — a każda warstwa ma swoje granice. Opisaliśmy je wprost: co wyłapuje linter, co wychwytuje AI, a co wciąż spoczywa na Tobie, bo żadne narzędzie jeszcze tego nie potrafi.

[Czego linter nie wykryje →](/pl/validators/#limits)

## Co znajdziesz w środku.

### Format

Markdown + YAML. Działa w każdym edytorze tekstu. Nie wymaga nowych narzędzi, aby zacząć pisać.

### Linter

CLI w Go. Weryfikuje strukturę, odwołania i kompletność. Zwraca niezerowy kod wyjścia przy błędach — działa w Twoim terminalu oraz w CI.

## Korzystaj z tego, co już masz.

SpecScore to po prostu zwykłe pliki w Twoim repozytorium. Bez konieczności zakładania konta w kolejnym SaaS-ie. Bez wymaganego orkiestratora. Używaj go z Linearem, Jirą, GitHub Projects, czystym Markdownem w katalogu lub całkowicie bez systemu do zarządzania zadaniami. Format i linter nie dbają o to, gdzie żyją Twoje tickety.

## Jak wypada SpecScore.

Rozwój sterowany specyfikacją (SDD) to dynamiczny obszar. Oto gdzie plasuje się SpecScore na tle alternatyw — bez owijania w bawełnę.

 Plain Markdown Standard wyjściowy. SpecScore to kolejny krok ewolucji Twojego Markdowna. OpenSpec Dobry punkt wyjścia. SpecScore stanowi solidne barierki ochronne. Spec Kit Spec Kit to workflow. SpecScore to trwały artefakt. Datarim Datarim uruchamia potok zadań. SpecScore to to, co po nim zostaje. CodeSpeak CodeSpeak stawia na kompilator. SpecScore stawia na format. Kiro Kiro pisze specyfikację w swoim IDE. SpecScore to format, który CI może lintować. Tessl Tessl stawia na specyfikację jako źródło. SpecScore lintuje specyfikację obok kodu. BMAD Method BMAD prowadzi pętlę zwinną. SpecScore to artefakt, który pull request może sprawdzić. Task Master AI Task Master dzieli PRD na zadania. SpecScore to specyfikacja, którą te zadania mogą cytować.

[Zobacz pełne porównanie →](/pl/vs/)

## Wolisz CLI?

Nie korzystasz z agentów AI lub potrzebujesz walidacji specyfikacji w potoku CI? Jest do tego CLI. Zainstalujesz je w 60 sekund — bez zakładania konta, bez telemetrii, działa w dowolnym katalogu ze specyfikacjami w Markdownie.

 Linux / macOS Windows

```
$ curl -fsSL https://specscore.md/install/get-cli | sh
```

```
> irm https://specscore.md/install/get-cli.ps1 | iex
```

Uruchom linter na przykładowej specyfikacji dostarczonej z binarką:

```
$ specscore lint examples/checkout/apply-discount.md
```

Zobacz wynik:

```
examples/checkout/apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
```

Przeczytaj [pełną dokumentację](/docs/) · [Współtwórz na GitHubie](https://github.com/specscore/specscore)

## Zbudowane na SpecScore.

- ### DataTug Eksploruj schematy baz danych, twórz i wykonuj zapytania oraz analizuj wyniki z DataTug. SpecScore kieruje jego wymaganiami i kryteriami akceptacji. [datatug.app →](https://datatug.app)[Narzędzia, które stworzyliśmy →](https://datatug.app/en/under-the-hood/tools-we-built/)
- ### MeaningGraph Otwarty rejestr modeli danych i definicji semantycznych, utrzymywanych we własnych repozytoriach Git i powiązanych z modelami i kodem. [meaninggraph.io →](https://meaninggraph.io/)[Przeglądaj rejestr →](https://meaninggraph.io/registry/)
- ### Codegrapher Silnik grafu kodu do szybkiej eksploracji bazy kodu i dwukierunkowego łączenia specyfikacji z kodem. [codegrapher.dev →](https://codegrapher.dev/)
- ### DALgo Warstwa dostępu do danych w Go, wyspecyfikowana za pomocą SpecScore. [dal-go.github.io →](https://dal-go.github.io/)
- ### inGitDB Wersjonowana baza danych oparta na Gicie, wyspecyfikowana za pomocą SpecScore. [ingitdb.com →](https://ingitdb.com/)
- ### Rehearse Warstwa dowodów akceptacji — uruchamia w praktyce kryteria akceptacji specyfikacji, z weryfikacjami wielokrotnego użytku i bez kodu łączącego. [rehearse.ink →](https://rehearse.ink)
- ### SpecScore Studio Interfejs webowy do przeglądania i edytowania specyfikacji SpecScore. [specscore.studio →](https://specscore.studio)

## Masz pytania?

Oto pytania, które powracają najczęściej. Każde z nich prowadzi do pełnej odpowiedzi na [stronie FAQ](/pl/faq/).

 Czym różni się SpecScore od spec-kit?

spec-kit to metodologia; SpecScore to format zapisu specyfikacji, które tworzysz, oraz narzędzie CLI. Współpracują ze sobą — rozszerzenie spec-kit zapisujące w formacie SpecScore jest w przygotowaniu.

 Pełna odpowiedź → Czym różnią się SpecStudio Skills od Superpowers i agent-skills?

Idea jest zbliżona — wszystkie trzy prowadzą agentów AI przez etapy ideate → specify → plan → implement. SpecStudio Skills zapisuje artefakty w formacie SpecScore i używa CLI `specscore` do zapytań i zmian statusu; pozostałe odczytują i modyfikują pliki bezpośrednio. Wybierz SpecStudio, gdy liczy się zużycie tokenów.

 Pełna odpowiedź → Po co CLI — czy nie wystarczy zainstalować samych skilli?

Skille nie są w stanie niezawodnie egzekwować spójności referencyjnej, zwracać przefiltrowanych wyników bez czytania każdego pliku ani aktualizować odpowiedniego pola statusu w odpowiednim czasie. CLI wykonuje każde z tych zadań jednym wywołaniem. Skille, by zrobić to samo, muszą czytać każdy plik.

 Pełna odpowiedź → Dlaczego „SpecScore” — co tak właściwie ocenia?

Dwa znaczenia, oba zamierzone. Partytura (score) — uporządkowany zapis wymagań. Oraz dosłowna ocena jakości — linter w CLI to ocena deterministyczna, a skill `/score` to ocena dojrzałości w skali A–F wystawiana przez AI.

 Pełna odpowiedź → Gdzie są dane liczbowe dotyczące oszczędności tokenów?

Dokładne, pomierzone zestawienie porównawcze jest przygotowywane przed publikacją na Habr. Z punktu widzenia architektury: CLI zwraca zwięzłą listę o ustalonej strukturze; zwykły agent zamiast tego musi wczytać N całych dokumentów.

 Pełna odpowiedź → Na jakiej licencji jest SpecScore?

Specyfikacja i dokumentacja w publicznym repozytorium [specscore/specscore](https://github.com/specscore/specscore) są na [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE). Referencyjny interfejs wiersza poleceń (CLI) w [specscore/specscore-cli](https://github.com/specscore/specscore-cli) jest na [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE).

 Pełna odpowiedź → Czy SpecScore wymaga konkretnego narzędzia AI?

Nie. Specyfikacje to pliki tekstowe w repozytorium. CLI to lokalny program. AI Skills na tej stronie opakowują to CLI dla agentów, które umieją uruchamiać skills. Format nie wymaga jednego dostawcy.

 Pełna odpowiedź → Czym jest rozwój sterowany specyfikacją (SDD)?

Rozwój sterowany specyfikacją (SDD) oznacza napisanie testowalnej specyfikacji — wymagań i kryteriów akceptacji — przed kodem, a potem sprawdzenie wyniku względem tej specyfikacji. SpecScore jest jednym formatem plików dla tych specyfikacji.

 Pełna odpowiedź →

## Zdefiniuj sukces. Potem zrób na niego miejsce.

SpecScore określa, kiedy projekt jest gotowy. Tygodniowe zobowiązanie pomaga wybrać następny krok. Połącz je krótkim przeglądem wyników.

 Wybierz następny efekt do ukończenia → Poznaj CommittedMe (po angielsku) →