| name | code-quality |
| description | Audyt jakości kodu: architektura (SOLID, circular deps), performance (Big O, N+1, scalability), prostota (YAGNI, LOC reduction), wzorce (patterns, anti-patterns, duplikacja). Stack-agnostic. Używaj przy audycie jakości, po implementacji dużych features, przy refaktoryzacji, ocenie tech debt. |
Code Quality Audit
Skill do przeprowadzania glebokiego audytu jakosci kodu. Stack-agnostic -- dziala niezaleznie od technologii. Skupia sie na uniwersalnych zasadach inzynierii oprogramowania: architektura, wydajnosc, prostota, wzorce.
Kiedy uzywac
- Audyt jakosci po implementacji duzego feature'a
- Przed planowan refaktoryzacja -- identyfikacja co naprawic
- Ocena tech debt i priorytetyzacja splaty
- Weryfikacja decyzji architektonicznych
- Review po polaczeniu kilku PR-ow (analiza calosciowa)
- Wejscie do nowego codebase -- zrozumienie stanu kodu
Roznica vs code-review: Code review sprawdza konkretne zmiany (diff). Code quality audit analizuje glebiej -- architekture, skalowanosc, zlozonosc calych modulow. To nie guardrails (od tego jest coding-rules.md), to gleboka analiza.
Workflow -- 4 przebiegi analizy
Audyt sklada sie z 4 niezaleznych przebiegow. Kazdy ma inny fokus i moze byc uruchamiany osobno.
Przebieg 1: SOLID + Architektura
Cel: Sprawdzenie czy kod jest dobrze zorganizowany strukturalnie.
Co analizowac:
- Single Responsibility -- Czy kazdy modul/klasa/funkcja ma jeden powod do zmiany?
- Open/Closed -- Czy mozna dodac nowa funkcjonalnosc bez modyfikacji istniejacego kodu?
- Liskov Substitution -- Czy podtypy zachowuja sie jak typy bazowe?
- Interface Segregation -- Czy konsumenci uzywaja wszystkich metod interfejsu?
- Dependency Inversion -- Czy moduly zaleza od abstrakcji czy konkretnych implementacji?
- Circular dependencies -- import graph, wzajemne zaleznosci miedzy modulami
- Layer boundaries -- Czy warstwy sa prawidlowo oddzielone? Czy nie ma przeskakiwania warstw?
- API contracts -- Czy interfejsy miedzy modulami sa stabilne i dobrze zdefiniowane?
- Deep vs shallow modules -- czy moduł ma dużą dźwignię za małym interfejsem (deep), czy interfejs jest niemal tak złożony jak implementacja (shallow / pass-through)?
Jak przeprowadzic:
- Zbuduj mape zaleznosci (grep importow, przeanalizuj kto importuje kogo)
- Dla kazdego modulu odpowiedz: "jaki jest jeden powod do zmiany tego modulu?"
- Sprawdz czy sa cykliczne zaleznosci (A importuje B, B importuje A)
- Zweryfikuj ze warstwy nie sa naruszane (UI nie importuje data access, serwis nie zalezy od UI)
- Deletion test dla modułów podejrzanych o płytkość: wyobraź sobie usunięcie modułu. Jeśli złożoność znika — był pass-through (kandydat do konsolidacji). Jeśli złożoność pojawia się rozproszona u N callerów — zarabiał na siebie (zostaw)
Szczegolowa dokumentacja: resources/architecture-analysis.md
Przebieg 2: Performance
Cel: Identyfikacja problemow wydajnosciowych i ocena skalowalnosci.
Co analizowac:
- Big O -- Zlozonosc obliczeniowa kluczowych operacji
- N+1 -- Zapytania/operacje w petli (fetch/query w loop, map z async)
- Scalability projection -- Co sie stanie przy 10x, 100x, 1000x danych?
- Caching -- Czy dane ktore mozna cachowac sa cachowane? Czy cache jest prawidlowo invalidowany?
- Memory -- Czy sa wycieki pamieci, niepotrzebne kopie duzych struktur?
Jak przeprowadzic:
- Dla kazdej kluczowej operacji okresl zlozonosc Big O
- Szukaj petli z operacjami I/O wewnatrz (fetch, query, file read)
- Dla kazdej struktury danych zapytaj: "co jesli bedzie 1000x wieksza?"
- Sprawdz czy memoizacja/cache jest uzywana tam gdzie ma sens
Szczegolowa dokumentacja: resources/performance-analysis.md
Przebieg 3: Simplicity (YAGNI)
Cel: Identyfikacja zbednej zlozonosci i mozliwosci uproszczenia.
Co analizowac:
- YAGNI -- Czy kazdy element kodu jest explicite wymagany TERAZ?
- Abstraction challenge -- Czy kazda abstrakcja ma uzasadnienie (2+ uzycia)? Reguła szwu: jeden adapter = szew hipotetyczny (przedwczesna abstrakcja), dwa adaptery = szew realny. Pojedynczy adapter za interfejsem to sygnał przedwczesnej abstrakcji
- Redundancy -- Zduplikowana logika, powtorzony error handling, dead code
- Complexity -- Deep nesting, dlugie funkcje, dlugie pliki
- LOC metrics -- Ile linii logiki mozna usunac bez utraty funkcjonalnosci?
Jak przeprowadzic:
- Dla kazdej abstrakcji (interfejs, klasa bazowa, factory, wrapper) zapytaj: "ile implementacji/konsumentow?"
- Szukaj dead code: nieuzywane importy, zmienne, funkcje, eksporty
- Szukaj duplikatow: ta sama walidacja w 3 miejscach, powtorzony error handling
- Mierz: ile linii logiki mozna usunac?
Szczegolowa dokumentacja: resources/simplicity-audit.md
Przebieg 4: Pattern Consistency
Cel: Sprawdzenie spojnosci wzorcow, nazewnictwa i konwencji.
Co analizowac:
- Design patterns -- Czy wzorce sa uzywane poprawnie i spojnie?
- Anti-patterns -- God Object, Feature Envy, Shotgun Surgery, Inappropriate Intimacy
- Naming -- Czy nazewnictwo jest spojne w calym codebase?
- Duplikacja -- Nie duplikacja kodu (to przebieg 3), ale duplikacja koncepcji i odpowiedzialnosci
- Konwencje -- Czy caly codebase stosuje te same konwencje (error handling, logging, walidacja)?
Jak przeprowadzic:
- Porownaj podobne moduly -- czy stosuja te same wzorce?
- Sprawdz nazewnictwo: czy booleany maja prefix
is/has/should? Czy handlery maja handle?
- Szukaj anti-patternow z katalogu (patrz architecture-analysis.md)
- Sprawdz czy error handling jest ustandaryzowany w calym projekcie
Klasyfikacja problemow
Uzyj tego samego systemu co code-review, aby raporty byly spojne:
[blocking] KRYTYCZNE -- wymaga natychmiastowej naprawy
- Circular dependencies blokujace rozwoj
- Algorytm O(n^3) na danych produkcyjnych
- Brak walidacji na granicy API
- Wyciek pamieci w petli glownej
[important] POWAZNE -- wymaga naprawy
- Naruszenie SRP (modul z 5+ odpowiedzialnosciami)
- N+1 w gorących sciezkach
- Zbedna abstrakcja komplikujaca kod
- Niespojne wzorce miedzy modulami
[nit] DROBNE -- zalecane
- Niespojne nazewnictwo
- Brak early return (deep nesting)
- Magic numbers bez named constants
- Zbedne komentarze
[suggestion] SUGESTIE -- opcjonalne
- Alternatywna architektura
- Propozycja uproszczenia
- Potencjalna optymalizacja (nie krytyczna)
Format raportu
## Code Quality Audit: [nazwa modulu/projektu]
### Podsumowanie
[1-3 zdania: ogolna ocena, glowne problemy, rekomendacja]
### Statystyki
- Modulow/plikow przeanalizowanych: X
- [blocking]: X
- [important]: X
- [nit]: X
- [suggestion]: X
- LOC przeanalizowanych: ~X
- LOC do potencjalnego usuniecia: ~X
---
### Przebieg 1: SOLID + Architektura
[wyniki analizy, problemy z klasyfikacja]
### Przebieg 2: Performance
[wyniki analizy, problemy z klasyfikacja]
### Przebieg 3: Simplicity (YAGNI)
[wyniki analizy, problemy z klasyfikacja]
### Przebieg 4: Pattern Consistency
[wyniki analizy, problemy z klasyfikacja]
---
### Complexity Score
- Low (< 10 issues) / Medium (10-25 issues) / High (> 25 issues)
### Top 5 priorytetow do naprawy
Przy każdym priorytecie dodaj **badge siły rekomendacji** (ortogonalny do severity — mówi o pewności, nie o wadze): `Strong` / `Worth exploring` / `Speculative`.
1. [najwazniejszy problem + uzasadnienie] — `Strong`
2. ...
### Co zrobiono dobrze
- [pozytywne aspekty]
### Rekomendacja
- [ ] Kod w dobrym stanie -- brak pilnych zmian
- [ ] Wymaga punktowych poprawek (tech debt niski)
- [ ] Wymaga zaplanowanej refaktoryzacji (tech debt sredni)
- [ ] Wymaga znaczacej przebudowy (tech debt wysoki)
Zasady
- Stack-agnostic -- ten skill nie zaklada zadnej technologii. Zasady sa uniwersalne
- Gleboka analiza, nie guardrails --
coding-rules.md definiuje zasady codziennej pracy. Ten skill robi gleboka analize architektonalna
- Fakty, nie opinie -- kazdy finding musi byc uzasadniony (Big O, liczba zaleznosci, LOC)
- Priorytetyzacja -- nie wszystko trzeba naprawic naraz. Raport musi zawierac "Top 5 priorytetow"
- Doceniaj -- zauważaj dobre rozwiazania, nie tylko problemy
- Kontekst -- uwzgledniaj faze projektu (MVP vs mature), deadline, rozmiar zespolu
- Nie duplikuj coding-rules.md -- te reguly sa znane. Skup sie na rzeczach ktorych coding-rules nie pokrywa
Dokumentacja referencyjna
| Potrzebujesz... | Przeczytaj |
|---|
| SOLID, circular deps, layer boundaries, anti-patterns | architecture-analysis.md |
| Big O, N+1, scalability, caching, benchmarks | performance-analysis.md |
| YAGNI, abstrakcje, redundancja, LOC metrics | simplicity-audit.md |
