improve-codebase-architecture: utrzymanie architektury
Piąty krok z README: okresowe skanowanie kodu w poszukiwaniu okazji do "pogłębienia" — zamiany płytkich modułów w głębokie (Lekcja 18). To bezpośredni konsument słownika, który dopiero co poznałeś: skill ma używać terminów module/interface/depth/seam/adapter dokładnie, nigdy "component" czy "boundary".
Polecane źródło
Lokalny plik .agents/skills/improve-codebase-architecture/SKILL.md w tym repo.
samodzielny plik poza repo, karty kandydatów z diagramem przed/po i siłą rekomendacji
3. Grillowanie
dopiero gdy wybierzesz kandydata — /grilling + /domain-modeling na żywo
Sygnały tarcia, których szuka subagent
Zrozumienie jednego pojęcia wymaga skakania między wieloma drobnymi modułami
Moduły płytkie — interfejs niemal tak złożony jak implementacja
Czyste funkcje wyodrębnione tylko dla testowalności, ale prawdziwe błędy chowają się w tym, jak są wywoływane — brak locality
Mocno sprzężone moduły przeciekające przez swoje seamy
Fragmenty trudne albo niemożliwe do przetestowania przez obecny interfejs
Do każdego podejrzanego miejsca stosowany jest test usunięcia z Lekcji 18: usunięcie koncentruje złożoność z powrotem u wywołujących, czy po prostu ją przenosi?
Kluczowy wniosek: raport HTML ląduje w katalogu tymczasowym systemu ($TMPDIR / /tmp / %TEMP%), nigdy w repo — dokładnie ta sama dyscyplina "nie zaśmiecaj repo jednorazowym artefaktem", którą poznałeś przy prototype w Lekcji 16. I podobnie jak tam: to, co zostaje na trwałe, to nie sam raport, tylko decyzja podjęta na jego podstawie.
Diagnoza oddzielona od projektowania
Po napisaniu raportu skill ma wprost nie proponować jeszcze żadnych interfejsów — tylko zapytać: "Which of these would you like to explore?". Projektowanie zaczyna się dopiero w fazie 3, przez /grilling, gdy już wiesz, który kandydat Cię interesuje. To rozdzielenie chroni przed najczęstszym błędem code review architektonicznego: rzucaniem gotowym rozwiązaniem, zanim ktokolwiek zgodził się, że to w ogóle jest problem wart rozwiązania.
ADR tylko przy odrzuceniu z konkretnego powodu
Jeśli podczas grillowania odrzucisz kandydata, a powód jest trwały (nie "nie teraz, bo brak czasu", tylko coś, co przyszły eksplorator architektury musiałby znać, żeby nie zaproponować tego samego jeszcze raz) — skill zapyta, czy zapisać to jako ADR. To osobny przypadek od trzech warunków ADR z Lekcji 14: tutaj chodzi konkretnie o zapobieganie ponownemu odkrywaniu tego samego martwego tropu.
Zadanie praktyczne — jeden przegląd architektury na żywym kodzie
W swoim prawdziwym projekcie wpisz /improve-codebase-architecture:
Sprawdź, czy raport faktycznie otworzył się poza repo (sprawdź ścieżkę, którą Claude Ci poda).
Przeczytaj karty kandydatów — czy słownictwo z Lekcji 18 (module/interface/seam/depth) jest używane konsekwentnie, czy wkrada się "component"/"service"?
Wybierz jednego kandydata i przejdź przez grillowanie — zwróć uwagę, czy CONTEXT.md faktycznie aktualizuje się na żywo, gdy nazywacie nowe pojęcia.
Sprawdź się
1. Dlaczego raport HTML zapisuje się do katalogu tymczasowego systemu, a nie do repozytorium?
To dokładnie ta sama dyscyplina co w Lekcji 16: rzeczy jednorazowe/pomocnicze nie mają rotnąć w repozytorium. Trwała ma być tylko decyzja, nie sam raport.
2. Po napisaniu raportu skill NIE proponuje jeszcze żadnych interfejsów. Dlaczego?
Diagnoza (raport z kandydatami) jest celowo oddzielona od projektowania (grillowanie). Rozwiązanie pojawia się dopiero, gdy zgodzisz się, który problem w ogóle chcesz rozwiązać.
3. Odrzucasz kandydata podczas grillowania, mówiąc "nie teraz, brak czasu w tym sprincie". Czy skill zaproponuje ADR?
ADR jest oferowany tylko przy powodzie trwałym, load-bearing — takim, który zapobiegnie ponownemu zaproponowaniu tego samego w przyszłości. "Brak czasu teraz" to powód efemeryczny, pomijany.
4. Subagent znajduje czyste funkcje wyodrębnione dla testowalności, ale prawdziwe błędy pojawiają się w tym, jak są wywoływane. Brak jakiej właściwości to sygnalizuje?
Locality oznacza, że zmiana/błędy/wiedza koncentrują się w jednym miejscu. Gdy błędy chowają się w sposobie wywołania rozproszonym po całym kodzie, mimo "czystych" funkcji w środku — to właśnie brak locality.
5. Który wbudowany subagent z Lekcji 4 skill wykorzystuje do organicznego przeszukania kodu w Fazie 1?
Skill wprost używa Agent tool z subagent_type=Explore — tego samego, read-only subagenta z Lekcji 4, do taniego i szybkiego przeszukania kodu bez obciążania głównego okna kontekstu.
Coś niejasne? Zapytaj mnie wprost — mogę pomóc ocenić kartę kandydata z Twojego raportu pod kątem słownictwa albo siły rekomendacji.