FullSpec framework dla AI-rozwoju z Claude Code i specyfikacjami

FullSpec: framework do rozwoju sterowanego AI z Claude Code

Rozwój z wykorzystaniem asystentów AI często prowadzi do chaosu z powodu braku jednolitej dokumentacji architektonicznej. FullSpec rozwiązuje ten problem, formalizując cały cykl od idei do wydania poprzez łańcuch specyfikacji, które generują i utrzymują agenty AI.

Problem: AI bez pamięci architektonicznej

Kluczowa trudność przy pracy z LLM, takimi jak Claude Code, to brak kontekstu decyzji architektonicznych. AI szybko pisze kod, ale nie pamięta, dlaczego system jest zbudowany w ten sposób. W projekcie z 25 mikrousługami prowadzi to do krytycznych konfliktów:

• Różne algorytmy szyfrowania w sąsiednich usługach
• Niespójne kontrakty API
• Sprzeczne decyzje w równoległych sesjach

Tradycyjne podejścia do dokumentacji nie działają: albo pozostaje w tyle za kodem, albo wymaga niepraktycznej biurokracji. AI potrzebuje aktualnych, pełnych i spójnych specyfikacji — a FullSpec tworzy właśnie takie środowisko.

Architektura FullSpec: 23 agenty i 8 faz

Framework organizuje rozwój poprzez formalne dokumenty, które generują i walidują agenty AI. Użytkownik wywołuje /chain z opisem zadania, na przykład "zrobić autoryzację OAuth2", a system uruchamia sekwencję 8 faz.

Poziomy specyfikacji

Łańcuch tworzy cztery poziomy dokumentów z obowiązkowym przeglądem na każdym etapie:

• Discussion — wymagania, kryteria sukcesu, zakres i ryzyka
• Design — zmiany systemu: usługi, kontrakty API, modele danych
• Plan Tests — scenariusze testowe, napisane przed kodem
• Plan Dev — zadania, zależności i bloki wykonania

Po zatwierdzeniu specyfikacji system automatycznie generuje dokumentację, tworzy GitHub Issues, pisze kod i testy, przeprowadza code review i tworzy PR.

Kluczowe mechanizmy frameworka

Równoległa praca agentów

Zamiast jednego Claude, wykonującego zadania sekwencyjnie, FullSpec używa 23 wyspecjalizowanych agentów AI:

• Generator Design
• Planista testów
• Koder dla różnych języków
• Recenzenci na każdym poziomie
• Agenty synchronizacji dokumentacji

Przy synchronizacji uruchamia się N agentów równolegle — po jednym na każdą usługę.

Automatyczna walidacja i reguły

System zawiera ponad 80 skryptów walidacji i 30 pre-commit hooków, które sprawdzają:

• Format dokumentów
• Spójność struktury
• Brak sekretów w kodzie
• Zgodność commit message ze standardami

16 kontekstowych reguł automatycznie ładuje się przy pracy z plikami: .ts → standard TypeScript, .py → standard FastAPI. Reguły przechowywane są w .claude/rules/ i stosowane bez dodatkowych prompty.

Żywe specyfikacje i sprawdzanie konfliktów

Główna różnica w porównaniu do analogicznych rozwiązań — system wykrywa i rozwiązuje rozbieżności między kodem a specyfikacjami. Po każdym commicie uruchamiany jest CONFLICT-CHECK:

• Przy wykryciu sprzeczności proces jest wstrzymywany
• System określa poziom konfliktu (Design, Plan Dev itp.)
• Specyfikacje są kaskadowo aktualizowane od góry do dołu
• Dokumentacja pozostaje aktualna na wszystkich etapach rozwoju

Porównanie z alternatywnymi rozwiązaniami

| Kryterium | FullSpec | Spec Kit (GitHub) | Kiro (AWS) | OpenSpec (Fission AI) |

|----------|----------|-------------------|------------|-----------------------|

| Typ | Framework procesu | CLI-toolkit | IDE (fork VS Code) | CLI-framework |

| Formalizacja wymagań | Discussion z kryteriami | Constitution + Spec | Requirements (EARS) | Proposal |

| Projektowanie architektoniczne | Design z kontraktami API | Plan | Design (markdown) | Design |

| Planowanie testów przed kodem | Plan Tests z numeracją TC-N | Nie | Nie | Nie |

| Wykrywanie konfliktów | Automatyczne + kaskadowe aktualizacje | Nie | Nie | Nie |

| Żywa dokumentacja | Autosynchronizacja ze spec | Nie | Nie | Nie |

| Automatyzacja GitHub | Issues, PR, Review, Release | Nie | Nie | Nie |

| Agenty AI | 23 równoległe | 0 | 1 (wbudowany) | 0 |

| Walidacja | 80+ skryptów, 30 pre-commit hooków | 0 | 0 | ~5 |

| Wsparcie brownfield | Na razie nie | Tak | Tak | Tak (fokus) |

FullSpec zamyka pełny cykl rozwoju, ale wymaga powiązania z Claude Code i na razie nie wspiera integracji w istniejących projektach.

Charakterystyki techniczne

• 71 umiejętności — slash-komendy dla każdego kroku procesu
• 23 agenty AI — równoległe workery ze specjalizacją
• 80+ skryptów walidacji — sprawdzenie na wszystkich etapach
• 30 pre-commit hooków — automatyczna kontrola jakości
• 16 reguł kontekstowych — rozszerza się z dodaniem technologii
• 8 faz procesu — od idei do wydania produkcyjnego
• Rekurencyjna standaryzacja — system tworzy sam siebie według jednolitych reguł

Co ważne

• Niski próg wejścia — mimo złożonej architektury, użytkownik współdziała tylko przez /chain i dialogowe potwierdzenia
• Tylko Claude Code — framework został opracowany pod konkretnego asystenta AI, wsparcie innych środowisk nie było testowane
• Dokumentacja w języku rosyjskim — wszystkie instrukcje i specyfikacje w języku rosyjskim, co nie przeszkadza Claude w ich przetwarzaniu
• Tylko greenfield — obecna wersja działa jako szablon dla nowych projektów, wsparcie brownfield w rozwoju
• Otwarty kod źródłowy — projekt dostępny pod licencją MIT na GitHub

Projekt stanowi praktyczną implementację podejścia, gdzie AI nie tylko generuje kod, ale pracuje w ramach sformalizowanego procesu z żywą dokumentacją. To redukuje ryzyko konfliktów architektonicznych i zwiększa przewidywalność rozwoju w zespołach korzystających z asystentów AI.

— Editorial Team