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

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 scenariuszeGIVEN / 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-2sprawiają, ż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 Approvedw 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ć.