Przepływ pracy z AI

Ten projekt został zbudowany z Claude Code. Większość deklaracji „zbudowane z AI” kończy się na etykietce. Oto pełny obraz: co AI wie, jak działają sesje, jak wygląda tworzenie promptów w praktyce i gdzie człowiek wyznacza granicę. Jeśli sam budujesz z AI lub po prostu ciekawi cię, jak to naprawdę wygląda — to jest dla ciebie.

Co AI wie

Claude Code posiada trwały plik pamięci, który przenosi kontekst między sesjami. Zamiast za każdym razem eksplorować bazę kodu od nowa, kontynuuje od miejsca, w którym skończyliśmy. Oto co się w nim znajduje (w wersji oczyszczonej):

Tożsamość projektu

Nazwa aplikacji, lokalizacja źródeł, licencja, identyfikator aplikacji
Relacja forka: upstreamem jest En Croissant autorstwa Francisco Salgueiro, my utrzymujemy nasz własny fork niezależnie
Dlaczego fork istnieje: główny maintainer odrzucił funkcję TTS, co jest zrozumiałe — różne wizje tego samego projektu

Reguły budowania

Wyłącznie pnpm — npm psuje vanillaExtract (biały ekran w runtime, żadnego błędu, po prostu nic)
Wymagany Node.js 22+ (Vite 7 potrzebuje crypto.hash)
Zawsze pnpm format && pnpm lint:fix przed commitem
Zamknąć aplikację przed nadpisaniem binarki (“Text file busy”)
Po przeniesieniu katalogów źródłowych, cargo clean żeby wyczyścić nieaktualne referencje ścieżek

Wiedza o architekturze

Które pliki odpowiadają za które funkcje (atomy w atoms.ts, nawigacja po drzewie w tree.ts, silnik TTS w tts.ts)
Dlaczego wszystkie atomy TTS potrzebują getOnInit: true (imperatywne odczyty przez store.get() zanim React zasubskrybuje)
Jak działa cache audio (klucze provider:voiceId:lang:text)
Poprawka współrzędnych chessground jest po stronie CSS, a nie forkiem biblioteki
Układ danych: co gdzie się znajduje, co jest symlinkowane, co przeżywa restarty aplikacji

Czego nie wie

Pamięć nie zawiera kluczy API, haseł ani poświadczeń. Odwołuje się do ich lokalizacji przechowywania (nazwy atomów w localStorage), ale nigdy do samych wartości. AI generuje kod, który odczytuje klucze z ustawień — nigdy nie widzi ani nie obsługuje faktycznych sekretów.

Jakie instrukcje dostaje AI

Poza plikiem pamięci, Claude Code przestrzega zasad wbudowanych w jego system:

Nie komplikuj ponad miarę. Wprowadzaj tylko zmiany, o które bezpośrednio poproszono. Poprawka błędu nie wymaga sprzątania otaczającego kodu. Trzy podobne linie kodu są lepsze niż przedwczesna abstrakcja.
Nie zgaduj URL-i. Nigdy nie fabrykuj linków ani endpointów.
Czytaj przed edycją. Nigdy nie proponuj zmian w kodzie, którego nie przeczytałeś.
Edytuj, zamiast tworzyć. Nie twórz nowych plików, chyba że jest to absolutnie konieczne.
Żadnych luk bezpieczeństwa. Uważaj na injection, XSS i problemy z OWASP top 10.
Pytaj, gdy nie jesteś pewien. Jeśli instrukcja jest niejednoznaczna, pytaj zamiast zgadywać.
Dwa razy mierz, raz tnij. Operacje destrukcyjne (force push, reset —hard, usuwanie plików) wymagają wyraźnej zgody człowieka.

Pisanie dobrych promptów

Różnica między użyteczną a frustrującą interakcją z AI prawie zawsze tkwi w prompcie.

Bądź konkretny w tym, czego chcesz. Nie „napraw buga”, ale „klucz cache TTS nie zawiera nazwy providera, więc przełączenie z ElevenLabs na Google odtwarza zcachowane audio ElevenLabs zamiast generować nowe.”

Dołącz kontekst, którego AI nie ma. AI potrafi czytać twój kod, ale nie czyta w twoich myślach. „Użytkownik zgłosił, że współrzędne na szachownicy są odwrócone” jest mniej przydatne niż „CSS w chessgroundBaseOverride.css ma zamienione rzędy i kolumny — oryginał Francisco miał je odwrócone.”

Podaj swoje ograniczenia. „Nie twórz nowych plików” albo „użyj istniejącego wzorca atomów” albo „to musi działać bez klucza API” mówią AI, gdzie są barierki.

Powiedz, czego nie chcesz. „Nie dodawaj obsługi błędów dla przypadków, które nie mogą wystąpić” albo „nie refaktoryzuj otaczającego kodu” zapobiega nadmiernej inżynierii — najczęstszemu trybowi awarii AI.

Wzorzec to: intencja + kontekst + ograniczenia. Opanuj to, a AI stanie się dramatycznie bardziej użyteczne.

Tryb planowania: użycie jednego Claude’a do tworzenia promptów dla drugiego

Claude Code ma „tryb planowania” (plan mode), który oddziela myślenie od działania. W trybie planowania AI czyta pliki, eksploruje bazę kodu i tworzy plan — ale nie pisze żadnego kodu. Przeglądasz plan, poprawiasz go, a potem przełączasz na tryb implementacji, w którym AI go realizuje.

Dlaczego to działa? Ponieważ najtrudniejsza część każdego zadania programistycznego to nie pisanie kodu. To ustalenie, jaki kod napisać — które pliki zmienić, jakie wzorce stosować, jakie przypadki brzegowe istnieją. Tryb planowania poświęca pełną uwagę temu pytaniu, zanim zostanie napisana choćby jedna linia.

Przykład z tego projektu: kiedy przebudowywaliśmy menu Pomocy, aby dodać selektor języka, rozmowa w trybie planowania zbadała, jak działają menu Tauri, jakie atomy już istnieją, jak przeglądarka dokumentacji rozwiązuje ścieżki zasobów i jak wygląda API dialogu potwierdzenia. Zanim przełączyliśmy się na implementację, AI miało kompletną mapę zmian. Żadnych fałszywych startów.

W istocie używasz jednej instancji AI jako starszego architekta, a drugiej jako programisty. Ten sam model, różne role.

Jak działają sesje

Typowa sesja wygląda tak:

Człowiek określa zamiar. „Dodaj notatkę o cachowaniu do sekcji KittenTTS.” „Usuń telemetrię PostHog.” „Oceny jakości są błędne, oto jakie powinny być.”
AI czyta odpowiednie pliki. Nie zgaduje, co jest w pliku. Czyta go, rozumie aktualny stan, a potem proponuje zmiany. Wiele plików jest czytanych równolegle, gdy są od siebie niezależne.
AI wprowadza zmianę. Celowane edycje istniejących plików. Nie przepisywanie — chirurgiczne modyfikacje, które zachowują wszystko dookoła.
Człowiek weryfikuje. Każda edycja jest pokazana przed zapisaniem na dysk. Człowiek zatwierdza, odrzuca lub przekierowuje. „Nie, to zbyt grzeczne — napisz, że naprawdę jest do bani.” „Przenieś ten akapit wyżej.” „Nie o to mi chodziło.”
Commit na polecenie. AI nigdy nie commituje z własnej inicjatywy. Człowiek mówi „commit” lub „commit and push.” Commity zawierają Co-Authored-By: Claude Opus 4.6 — zawsze z przypisaniem, nigdy w ukryciu.

Okna kontekstu i stany zapisu

Każda rozmowa z AI ma okno kontekstu — całkowitą ilość tekstu, jaką może utrzymać w pamięci jednocześnie. Kiedy rozmowa staje się wystarczająco długa, starsze wiadomości są kompresowane, żeby zrobić miejsce.

Dwie strategie: utrzymuj rozmowy skupione (jedno zadanie na rozmowę) i używaj stanów zapisu (Claude Code zapisuje transkrypty jako pliki JSONL, które można wznowić z pełnym przywróceniem kontekstu). Plik pamięci służy innemu celowi — to trwała baza wiedzy, która przetrwa wszystkie rozmowy.

Co AI proponuje vs. co trafia do produkcji

Pierwsza sugestia AI rzadko jest wersją ostateczną. Typowa wymiana:

AI tworzy coś rozsądnego
Człowiek mówi „zbyt korporacyjne” albo „bądź bardziej bezpośredni” albo „to jest błędne, oto dlaczego”
AI poprawia
Człowiek zatwierdza

Gust, ton i ostateczna decyzja są zawsze po stronie człowieka. AI zapewnia prędkość — czytanie plików, rozumienie kontekstu, precyzyjne edycje w bazie kodu, którą potrafi utrzymać w pamięci. Człowiek zapewnia osąd — co budować, jak to powinno wyglądać, kiedy przestać.

Umiejętności i komendy slash

Claude Code obsługuje „umiejętności” (skills) — wielokrotnego użytku prompty przechowywane jako pliki markdown w katalogu .claude/commands/. Wywołujesz je komendą slash, np. /translate-docs.

Ten projekt używa umiejętności /translate-docs, która automatyzuje tłumaczenie dokumentacji na wiele języków. Plik umiejętności zawiera pełne instrukcje: które pliki tłumaczyć, jakiego formatu używać, jak obsługiwać bloki kodu i linki, jaki ton zachować. Zamiast tłumaczyć to wszystko za każdym razem, po prostu wpisujesz /translate-docs, a AI dokładnie wie, co robić.

Umiejętności kodują proces, nie tylko informację. Możesz je budować dla dowolnego powtarzalnego workflow: uruchamiania testów, wdrażania, przeglądania PR-ów, aktualizowania changelogów.

Zasady kodowania

Pełny dokument zasad znajduje się w repozytorium pod adresem .claude/01_UNIVERSAL_PRINCIPLES.md. Zaczął się od Clean Code Roberta C. Martina (2008) plus uzupełnień na erę AI. Potem odbyliśmy szczerą rozmowę o tym, co wciąż się broni, a co nie.

Co jest ponadczasowe

Nazwy ujawniające intencję. Zawsze. Na zawsze.
Funkcje robią jedną rzecz. Prawdziwą zasadą jest spójność, nie rozmiar.
Brak efektów ubocznych. Wciąż główne źródło większości błędów.
Komentarze wyjaśniają dlaczego, nie co.
Zasada Pojedynczej Odpowiedzialności. Moduł powinien mieć jeden powód do zmiany.
Programuj pod interfejsy, nie implementacje.
Nie połykaj błędów. Każdy błąd to informacja.
Emergentny design: przechodzi wszystkie testy, bez duplikacji, wyraża intencję, minimalizuje złożoność. W tej kolejności.

Co jest kontekstowe

Te zasady są solidne, ale konkretne reguły odzwierciedlają świat sprzed AI lub specyficzny dla danego języka. Stosujemy ducha, nie literę:

DRY. Duplikacja, która zaczyna się rozbiegać, jest niebezpieczna. Ale wyciąganie każdego powtórzonego wzorca do abstrakcji tworzy pośredniość, która może być gorsza. Czasem trzy czytelne linie tutaj są lepsze niż przedwczesna abstrakcja w innym pliku.
Ścisła ceremonia TDD. Zasada — dostarczaj przetestowany kod, miej pewność, że działa — jest bezdyskusyjna. Ceremonia — test musi istnieć przed kodem — została zaprojektowana dla workflow, w którym ludzie wolno piszą. Pisz testy. Upewnij się, że przechodzą. To, czy test czy kod powstał pierwszy, jest mniej ważne niż to, czy oba istnieją.
Zasada harcerza. „Zostaw obozowisko czystsze” — tak. Ale harcerz sprzątał obozowisko, nie cały las. Napraw to, czego dotykasz. Nie refaktoryzuj całej struktury pliku, bo zmieniłeś w nim jedną linię.

Uzupełnienia na erę AI

Wskazówki oparte na zasadach skalują się lepiej niż reguły. Zasada pozwala na osąd; reguła jest krucha.
Jeśli agent to zbudował, agent może to utrzymywać. Zachowuj kontekst rozmów i artefakty. Dokumentuj proces budowania, nie tylko wynik.
Jasność ponad spryt. System, który to zbudował, musi umieć odtworzyć rozumowanie i poprawnie je zmodyfikować. Jawna struktura wygrywa z drobnymi sprytnymi abstrakcjami.
Czy to mogłoby stać się infrastrukturą? Narzędzie rozwiązuje problem dla ciebie. Infrastruktura umożliwia innym budowanie na tym. Projektuj odpowiednio.

Gdzie człowiek wyznacza granicę

AI to narzędzie. Niezwykle dobre. Ale są rzeczy, których nie robi:

Decyzje produktowe. Jakie funkcje budować, co wyciąć, jak aplikacja powinna się czuć. „Ocena jakości System TTS powinna mówić ‘znośna’, bo naprawdę jest do bani” — to ludzka ocena oparta na faktycznym odsłuchaniu.
Gust. AI potrafi pisać czystą prozę, ale głos projektu, decyzja o byciu bezpośrednim w kwestii jakości, wybór wyraźnego wyróżnienia Francisco — to są ludzkie decyzje.
Etyka. Usunięcie PostHog nie było zadaniem refaktoryzacyjnym. To było „strona ustawień mówi, że nie zbieramy telemetrii, ale w kodzie jest aktywny klucz API PostHog. To kłamstwo. Napraw to.” AI wykonało. Człowiek zidentyfikował problem i zależało mu na tym.
Szachy. Szachownica nie interesuje się twoimi narzędziami.

Dlaczego to udostępniamy

Ponieważ „zbudowane z AI” stało się pustym sloganem. Wszyscy to mówią. Nikt tego nie pokazuje. Interesujące pytanie nie brzmi, czy AI było zaangażowane — ale jak było zaangażowane i co człowiek faktycznie wniósł.

Oto odpowiedź. Człowiek wnosi wizję, gust, osąd i odpowiedzialność. AI wnosi prędkość, pamięć i niestrudzoną gotowość do czytania komunikatów o błędach Rust o drugiej w nocy.

Żadne z nich nie zbuduje tego samodzielnie. Oba mają przypisane zasługi. Taka jest umowa.

En Parlant~ jest forkiem En Croissant autorstwa Francisco Salgueiro, zbudowanym z Claude Code od Anthropic.