Prowadzę TranslateScorm — aplikację, która tłumaczy szkolenia internetowe na obce języki. Korzystają z niej firmy szkoleniowe: wgrywają gotowy kurs po polsku, a dostają go w kilku wersjach językowych. Żeby tłumaczenia były spójne — żeby ta sama nazwa stanowiska czy przycisku brzmiała wszędzie tak samo — każda firma ma u siebie słownik: listę pojęć wraz z ich zatwierdzonymi tłumaczeniami.

I właśnie ten słownik chciałem tamtego ranka poprawić. Do tej pory miał sztywno ustawione języki, te same dla wszystkich klientów. Chciałem, żeby każda firma mogła wybrać własne — bo jedna tłumaczy na czeski i słowacki, a druga na hiszpański. Godzina, może dwie roboty.

Zrobiłem to. Kliknąłem „Zapisz". Nie zadziałało — nie dlatego, że źle wymyśliłem rozwiązanie, tylko dlatego, że jedną z czynności potrzebnych do uruchomienia zmiany po prostu pominąłem. Przygotowałem ją, odłożyłem na później i zapomniałem.

Mogłem to naprawić w minutę i wrócić do pracy. Zamiast tego zadałem sobie inne pytanie: dlaczego w ogóle mogło do tego dojść? I reszta dnia poszła już nie na słownik, tylko na to pytanie. Słownik był tylko zapalnikiem — dalej nie będzie już o nim mowy.

Jak to wyglądało wcześniej

Miałem jeden komplet prawdziwych danych i pracowałem bezpośrednio na nim. Każda próba, każdy eksperyment, każde „sprawdzę tylko, czy to działa" dotyczyło od razu tego samego miejsca, z którego korzystali klienci.

To trochę jak remontowanie sklepu w godzinach otwarcia. Zwykle jakoś idzie. Klienci przechodzą obok drabiny i nic się nie dzieje. Ale nie ma tam żadnego marginesu na pomyłkę — a pomyłka w końcu przychodzi, bo zawsze przychodzi.

Najgorsze było to, że nie miałem gdzie się pomylić bezpiecznie. Nie istniało miejsce, w którym mógłbym coś zepsuć, obejrzeć skutki i spokojnie naprawić. Skoro takiego miejsca nie ma, to każdy błąd wychodzi dopiero tam, gdzie boli najbardziej: u ludzi, którzy właśnie próbują wykonać swoją pracę.

Trzy miejsca zamiast jednego

Rozwiązanie brzmi banalnie: zamiast jednego miejsca — trzy. Każde ma inne zadanie i inne dane.

• U mnie na komputerze. Tu powstaje zmiana. Dane są wymyślone, więc mogę zepsuć absolutnie wszystko i nikogo to nie dotyczy.
• Kopia testowa. Osobne miejsce urządzone tak samo jak to prawdziwe, ale z danymi na niby. Tu sprawdzam, czy zmiana zachowa się tak samo w warunkach zbliżonych do rzeczywistych.
• To, z czego korzystają klienci. Tu trafia wyłącznie coś, co przeszło dwa poprzednie etapy.

Sens jest jeden: zmiana ma szansę zawieść w miejscu, gdzie nic to nie kosztuje. Nie chodzi o to, żeby się nie mylić. Chodzi o to, żeby pomyłka spotkała mnie, a nie klienta. U mnie zbudowanie tego zajęło część jednego dnia i nie wiązało się z dodatkowymi opłatami — druga baza mieści się w darmowym planie.

Jak to jest poskładane naprawdę

Powyższe schematy są celowo uproszczone. Poniżej to samo, ale z prawdziwymi nazwami — gdyby ktoś chciał zobaczyć, z czego to się składa. Nie trzeba tego rozumieć, żeby czytać dalej; ważny jest sam układ.

Aplikacja składa się z dwóch części, które łączą się w parę. Pierwsza to strona, którą widzi użytkownik. Druga to baza danych — magazyn, w którym trzymane są słowniki, konta i tłumaczenia. Sztuka polega na tym, żeby strona testowa łączyła się z bazą testową, a nigdy z prawdziwą.

Do tego dochodzi trzeci element: gałąź. To równoległa wersja projektu — ten sam kod, ale rozwijany osobno, tak jak dwie kopie tego samego dokumentu, w których pracuje się niezależnie. Wysłanie zmiany do gałęzi test automatycznie odświeża stronę testową, a do main — tę, z której korzystają klienci. Dzięki temu nie ma czegoś takiego jak „ręczne wgrywanie na serwer", a więc nie ma też okazji, żeby wgrać coś nie tam, gdzie trzeba.

Dlaczego akurat ten pominięty krok był groźny

Wróćmy na moment do tamtego kliknięcia „Zapisz". Wiele zmian składa się z dwóch części: samej zmiany oraz przygotowania miejsca w bazie, w którym mają być trzymane nowe informacje. To jak wstawienie nowej rubryki do formularza: trzeba dodać i pole, i miejsce na wpisaną w nie treść.

Ja zrobiłem pierwsze, a drugie odłożyłem. I to jest podstępne, bo na pierwszy rzut oka wszystko wygląda na gotowe — zmiana napisana, zadanie odhaczone. Program zgłasza problem dopiero wtedy, gdy ktoś faktycznie spróbuje czegoś użyć.

U mnie „ktoś" to byłem ja, pięć minut później. Bez etapu pośredniego tym kimś byłby klient — w środku swojej pracy, bez pojęcia, dlaczego przycisk przestał działać.

O co zapytać osobę, która robi dla Ciebie oprogramowanie

Pięć pytań, na które nie trzeba wiedzy technicznej. Interesuje Cię nie tyle sama odpowiedź, ile to, czy pada bez wahania.

1. Gdzie sprawdzacie zmiany, zanim zobaczą je moi ludzie? Jeśli odpowiedź brzmi „u siebie" i na tym koniec — brakuje etapu pośredniego.
2. Czy testujecie na prawdziwych danych mojej firmy? Powinno paść „nie" — do prób służy kopia, nie oryginał.
3. Skąd wiecie, że wszystkie potrzebne kroki zostały wykonane? Szukasz odpowiedzi „mamy to zapisane i sprawdzamy", nie „pamiętamy".
4. Co się dzieje, gdy zmiana okaże się zła po wdrożeniu? Powinien istnieć sposób powrotu do stanu sprzed — i ktoś powinien go znać.
5. Czy mamy kopię danych i kiedy ostatnio ktoś ją odtworzył? Kopia, której nigdy nie odtworzono, jest tylko obietnicą kopii.

Prompt, którym to spiąłem

Całego układu nie budowałem ręcznie — zleciłem to Claude Code, czyli asystentowi AI, który pracuje bezpośrednio na plikach projektu. Poniżej szablon polecenia, oczyszczony z moich konkretów, żeby dało się go użyć u siebie. Uzupełniasz nawiasy kwadratowe i wysyłasz.

Kontekst: projekt [NAZWA] to [CO ROBI]. Stos: [FRAMEWORK],
baza [DOSTAWCA BAZY], hosting [DOSTAWCA HOSTINGU].
Dziś istnieje tylko jedno środowisko — produkcyjne — i pracuję
bezpośrednio na nim. Chcę to rozdzielić na: lokalne, testowe
i produkcyjne.

ZASADY (obowiązują przez całe zadanie):
- Nie wykonuj niczego na produkcji bez mojej wyraźnej zgody.
  Produkcja to [ADRES] i baza [IDENTYFIKATOR].
- Zmiany w bazie mają być zapisane jako pliki migracji w repo,
  nie wklejane ręcznie w panelu. Chcę móc odtworzyć stan bazy
  od zera z samego repo.
- Zanim cokolwiek zmienisz, przedstaw plan i poczekaj
  na moje „ok".

ZADANIA:
1. Zbadaj repozytorium i opisz stan faktyczny: gdzie są
   ustawienia połączenia z bazą, czy istnieje jakikolwiek
   podział środowisk, co jest zaszyte na sztywno w kodzie.
   Nie zgaduj — sprawdź w plikach i pokaż, gdzie co znalazłeś.
2. Ściągnij aktualny schemat bazy produkcyjnej do repo jako
   punkt wyjścia dla migracji.
3. Zaproponuj sposób wyboru środowiska po adresie strony.
   Wymagania: dopasowanie dokładne, nie po fragmencie adresu;
   adres nieznany ma trafiać do środowiska lokalnego,
   nigdy do produkcyjnego.
4. Wypisz kroki, które muszę wykonać ręcznie poza repo
   (założenie drugiej bazy, ustawienia u dostawcy hostingu,
   wpisy DNS) — po kolei, z zaznaczeniem, co jest nieodwracalne.
5. Podaj sposób sprawdzenia, że rozdzielenie faktycznie działa:
   jak potwierdzić, że środowisko testowe NIE łączy się
   z bazą produkcyjną.

Po każdym etapie zatrzymaj się i podsumuj, co zostało zrobione
i co wymaga mojej decyzji. Jeśli któreś polecenie jest
niejednoznaczne — dopytaj, zamiast zakładać.

Czego się nauczyłem

Najdroższa nie była nowa funkcja, tylko brak miejsca do jej sprawdzenia. Sama zmiana to kilka godzin. Reszta dnia poszła na coś, czego brak wyszedł na jaw dopiero wtedy, gdy przestało działać.

Warto sprawdzić, zamiast zakładać. Tamtego dnia kilka razy „oczywista" diagnoza okazała się fałszywa — raz przez godzinę byłem przekonany, że zepsułem coś w bazie, a okazało się, że sprawdzałem to w niewłaściwy sposób. Za każdym razem ratowało to samo: sprawdzić jeszcze raz, ale inaczej niż poprzednio.

Problem rzadko leży tam, gdzie się objawia. Zaczęło się od przycisku, który nie zadziałał. Skończyło na wniosku, że nie mam gdzie pracować bezpiecznie. Gdybym naprawił tylko przycisk, ten sam problem wróciłby za miesiąc pod inną postacią.

Aplikacja jest dziś w lepszym stanie niż rano. Nie dlatego, że doszła nowa funkcja — choć doszła. Dlatego, że następnym razem, gdy coś pójdzie nie tak, będę miał gdzie to sprawdzić, zanim zobaczą to klienci.