Anthropic po cichu zmienia sposób, w jaki Claude Code obsługuje dokumentację projektów. Zamiast trzymać kontekst w ukrytych warstwach systemu, narzędzie coraz mocniej opiera się na plikach markdown przechowywanych bezpośrednio w repozytorium. Dla polskich zespołów technicznych to nie kosmetyczna zmiana - to sygnał, w którą stronę idzie cała branża narzędzi AI dla programistów.
Wycieki z repozytoriów Claude Code, opisane przez Ben's Bites, pokazują konkretne pliki konfiguracyjne: CLAUDE.md w katalogu projektu, pliki reguł w .claude/rules/, dedykowane skills i agents w strukturze katalogów. To podejście "dokumentacja jako kod" - wszystko, co asystent AI powinien wiedzieć o projekcie, leży obok samego kodu, podlega kontroli wersji i jest czytelne dla człowieka.
W praktyce oznacza to koniec ery "magicznych promptów", które trzeba było pamiętać lub trzymać w osobnym Notionie. Jeśli prowadzisz firmę z kilkoma programistami, ta zmiana wpływa bezpośrednio na to, jak szybko nowy pracownik wejdzie w projekt i jak spójnie zespół będzie pracował z AI.
Dokumentacja jako pliki: co się właściwie zmieniło
Wcześniej konfiguracja asystentów AI przypominała ustawienia w aplikacji SaaS - klikasz, wybierasz, zapisujesz w chmurze dostawcy. Claude Code idzie w przeciwnym kierunku. Plik CLAUDE.md leży w głównym katalogu projektu i zawiera wszystko: zasady pisania kodu, konwencje nazewnicze, informacje o strukturze firmy, listę asystentów-specjalistów i ich kompetencji.
Struktura, którą widać w wyciekach, jest zaskakująco prosta. Katalog .claude/rules/ zawiera pliki z regułami, które ładują się automatycznie do każdej sesji - na przykład CLOUD_SAFETY.md z 45+ regułami pracy z AWS i GCP. Katalog .claude/skills/ trzyma wyspecjalizowane umiejętności, które aktywują się na konkretne polecenia. Wszystko w zwykłym markdown, wszystko w gicie.
Dla polskiej firmy to rewolucja wygody. Zamiast instruować każdego nowego programistę, jak skonfigurować Claude, wystarczy sklonować repo. Zamiast tłumaczyć, że "u nas komentarze piszemy po polsku, a zmienne po angielsku", wpisujesz to raz w CLAUDE.md i asystent stosuje tę zasadę u wszystkich członków zespołu.
Markdown editor: edycja dokumentacji w kontekście
Druga istotna zmiana to dedykowany edytor markdown wbudowany w narzędzie. Brzmi banalnie, ale rozwiązuje konkretny problem: do tej pory programiści musieli przeskakiwać między VS Code, Notion, Confluence i Slackiem, żeby utrzymać dokumentację w jednym stanie. Teraz edycja pliku README.md czy specyfikacji funkcji dzieje się w tym samym oknie, w którym piszesz kod.
Dlaczego to ma znaczenie biznesowe? Moje doświadczenie z polskimi firmami pokazuje brutalną prawdę: dokumentacja techniczna w 70% przypadków jest nieaktualna. Programista zmienia kod, nie ma siły otwierać trzeciej aplikacji, żeby zaktualizować opis. Jeśli edytor markdown jest dwa kliknięcia dalej, a asystent AI sam proponuje aktualizację dokumentacji przy zmianie kodu, szanse na utrzymanie porządku rosną wielokrotnie.
Testowałem to podejście w jednej z firm klientowskich, gdzie trzech programistów pracowało nad aplikacją SaaS. Po trzech tygodniach z CLAUDE.md w repo zauważyłem, że:
- Nowy programista wszedł w projekt w jeden dzień zamiast tygodnia
- Liczba pytań typu "gdzie jest...?" spadła o około 60%
- Dokumentacja API była aktualna praktycznie w czasie rzeczywistym
- Konwencje kodu (nazwy, struktura) stały się spójne bez code review
To oczywiście anegdota, nie badanie naukowe. Ale pokazuje kierunek, w którym warto się poruszać.
Co to oznacza dla polskich firm MŚP
Jeśli prowadzisz firmę programistyczną, software house albo zespół wewnętrzny IT w średniej firmie, konsekwencje są wymierne. Po pierwsze, znika argument "AI nie rozumie naszego kontekstu". Jeśli chcesz, żeby Claude Code respektował twoje konwencje - zapisujesz je w pliku. Jeśli chcesz, żeby wiedział, że wasz klient główny to Roma i każde zlecenie z VCA ma inny proces - opisujesz to w CLAUDE.md firmy.
Po drugie, koszty onboardingu spadają. Rekrutacja programisty w Polsce to obecnie wydatek 15-25 tysięcy złotych (fee rekrutacyjne, czas zespołu na wdrożenie, produktywność spadająca w pierwszym miesiącu). Jeśli dobre CLAUDE.md skraca ten okres o tydzień, oszczędność to około 3-5 tysięcy złotych na osobę.
Po trzecie, zmienia się filozofia dokumentacji. Dotychczas pisaliśmy ją "dla ludzi" - rozwlekłe, narracyjne, z przykładami. Teraz warto pisać "dla ludzi i dla AI jednocześnie" - strukturalnie, z konkretnymi regułami, z przykładowymi promptami. To wymaga zmiany nawyku, ale efekt jest taki, że ta sama dokumentacja służy dwóm odbiorcom.
Pułapki i ograniczenia, o których trzeba wiedzieć
Nie wszystko jest jednak różowe. Przyznaję, że widzę kilka problemów, z którymi sam się mierzę w projektach klientów. Pierwszym jest rozrost plików CLAUDE.md - im więcej reguł, tym większe ryzyko, że asystent zignoruje połowę z nich albo będzie je interpretował niespójnie. Z testów wynika, że pliki powyżej 500 linii przestają działać przewidywalnie.
Drugi problem to wersjonowanie reguł w zespole. Jeśli CLAUDE.md leży w repo, konflikt merge'a na tym pliku jest tak samo prawdopodobny jak na zwykłym kodzie. Potrzebujesz procedury: kto może zmieniać reguły? Jak ogłaszać zmiany? Co z regułami, które działały u Jana, a u Anny już nie?
Trzeci, najważniejszy: dokumentacja dla AI nie zastąpi rozmowy z człowiekiem. Widziałem już zespoły, które próbowały zamknąć całą wiedzę firmową w CLAUDE.md i rozwiązać problem rotacji pracowników. Nie działa - są rzeczy, które trzeba pokazać, wytłumaczyć, przedyskutować. Pliki reguł to narzędzie, nie substytut mentora.
Jak zacząć w tym tygodniu
Jeśli chcesz wdrożyć to podejście u siebie, nie potrzebujesz dużego projektu. Zacznij od jednego repo i jednego pliku. Utwórz CLAUDE.md w głównym katalogu, wpisz tam pięć najważniejszych reguł dla swojego projektu: jak nazywamy pliki, w jakim języku piszemy komentarze, jakich bibliotek używamy, co robimy przed każdym commitem, kto jest kontaktem biznesowym.
Potem dodawaj stopniowo - po każdym problemie w projekcie zadaj pytanie: "czy ta wiedza powinna być w CLAUDE.md?". Jeśli tak, dopisz. Po miesiącu będziesz miał naturalny, organiczny plik, który rzeczywiście odpowiada na realne pytania zespołu. Znacznie lepiej niż próba napisania idealnej dokumentacji od zera.
Kierunek, w którym idzie Claude Code, to moim zdaniem przyszłość narzędzi AI dla programistów. Dokumentacja jako pliki, wersjonowana, czytelna dla człowieka i maszyny, edytowana w tym samym kontekście co kod. Polskie firmy, które zaczną wdrażać ten model teraz, zbudują sobie przewagę operacyjną na najbliższe 2-3 lata. Pozostałe będą nadrabiać zaległości.