Pisz CLAUDE.md jak konstytucję: zakazy, zasady postępowania, decyzje domyślne. 92 commity w 5 dni, bez zboczeń z kursu.
W 5 dni wrzuciłem 92 commity i wypchnąłem produkt na produkcję (github.com/defi-io/smarts). Bez wpadek, bez rollbacków, bez wielkich refaktoringów. Nie dlatego, że Claude jest geniuszem. A dzięki 565 liniom CLAUDE.md w korzeniu projektu.
Ten tekst jest o tym, jak napisać CLAUDE.md, który działa jak konstytucja, i co dzieje się potem.
Wielu pisze CLAUDE.md jak README — czym jest projekt, jak go odpalić. To marnotrawstwo.
README jest dla ludzi. CLAUDE.md jest dla Claude'a. Claude ładuje go automatycznie na początku każdej sesji. Każda linijka, którą tam wstawisz, staje się warunkiem wstępnym dla każdej jego późniejszej decyzji.
W stylu README dostajesz to: Claude z grubsza wie, czym jest projekt, wie, jak puścić testy, ale każdą decyzję techniczną podejmuje od zera.
W stylu konstytucji dostajesz to: Claude wie, które drogi są zamknięte, które konwencje są obowiązkowe, w którą stronę domyślnie skręcać na rozwidleniu, i kiedy się zatrzymać i zapytać.
Różnica: pierwszy „przy okazji" wciągnie nową zależność, doda warstwę abstrakcji, dotknie Gemfile. Drugi nie.
Projekt, nad którym pracuję, nazywa się smarts.md — platforma generująca live docs i serwery MCP dla smart contractów. Jego CLAUDE.md ma 565 linii, w takich sekcjach:
1. Tożsamość projektu (5 linii)
2. Rdzeń produktu (definicja jednolinijkowa + różnice strukturalne wobec konkurencji)
3. Stack techniczny (twarde ograniczenia, format YAML)
4. Lista zakazów (jawne pozycje ❌)
5. Zakres (twarde granice MVP)
6. Architektura (z diagramem ASCII)
7. Struktura katalogów (odpowiedzialność każdego pliku)
8. Konwencje kodu Ruby (ze snippetami rób/nie rób)
9. Strategia cache (jako tabela)
10. Wymagania testowe
11. Szczegóły deployu
12. Workflow Git
13. Zasady użycia Claude Code (instrukcje zachowania)
14. Kamienie milowe na 90 dni
15. Zasady kluczowe
Żadna sekcja nie jest ozdobna. Poniżej wybiorę kilka i wyjaśnię, dlaczego są napisane tak, a nie inaczej.
Moja wygląda tak:
❌ Bez serwisów TypeScript / Node.js
❌ Bez ethers.js / web3.js
❌ Bez Sidekiq (używamy Solid Queue)
❌ Bez React / Vue / Svelte (używamy Hotwire)
❌ Bez Redis (Solid Cache / Solid Queue / Solid Cable pokrywają wszystko)
❌ Bez niezweryfikowanych kontraktów (tylko zweryfikowane na Etherscan)
❌ Bez Solana / Bitcoin / Move (tylko EVM)
To projekt Web3. Domyślnie w Web3 jest TypeScript + ethers.js + Redis + React. Idę pod prąd. Mam swoje powody, ale Claude ich nie zna. Bez listy zakazów Claude oprze rekomendacje na „zdrowym rozsądku branży" zaszytym w danych treningowych — a to niemal na pewno droga TypeScript.
Z listą zakazów Claude przestaje pytać „dodajemy serwis Node, żeby odpalać web3.js?". Ta droga jest domyślnie zamknięta.
Klucz: każdy wpis musi być jawny i absolutny. Nie pisz „staraj się unikać TypeScriptu". Pisz „bez TypeScriptu". Wszystko mgliste Claude czyta jako negocjowalne.
Ostatni duży blok CLAUDE.md to „Zasady użycia Claude Code":
### Gdy mówię „zacznij X"
1. Najpierw sprawdź, czy ograniczenia CLAUDE.md pozwalają na to podejście
2. Potem sprawdź w istniejącym kodzie, czy nie ma już powiązanej implementacji
3. Przed pisaniem kodu otwórz nową gałąź
4. Po wdrożeniu uruchom testy
5. Bez auto-commita — gdy kod jest napisany i testy zielone, zatrzymaj się
i raportuj. Czekaj, aż wyraźnie powiem "commit"
### Gdy mówię „mam pomysł"
Nie pisz kodu od razu. Najpierw:
1. Potwierdź zrozumienie (sparafrazuj)
2. Oceń względem ograniczeń CLAUDE.md
3. Wskaż potencjalne problemy lub lepsze alternatywy
4. Poczekaj na moje potwierdzenie, potem działaj
### Przy technicznym rozwidleniu
Gdy CLAUDE.md nie precyzuje:
1. Domyślnie wybieraj wariant „bardziej Rails-native"
2. Domyślnie wybieraj wariant z mniejszą liczbą zależności
3. Domyślnie wybieraj wariant, który pozwala solo-devowi szybciej iterować
4. W razie wątpliwości — zatrzymaj się i zapytaj
Ta część jest dziesięć razy ważniejsza od „używaj snake_case".
Stylu kodu Claude uczy się czytając kod. Ale „kiedy się zatrzymać i zapytać", „gdy słyszysz 'mam pomysł', najpierw sparafrazuj, zamiast od razu pisać kod" — to wzorce zachowania. Sam kod ich nie nauczy.
Najważniejsza linia: w którą stronę domyślnie skręcać na rozwidleniu. Ta jedna reguła decyduje, co robi Claude, gdy nie ma cię w pokoju (gdy mówisz tylko „zacznij X" i odchodzisz). Wpisz to jasno, a będziesz mógł go zostawić, żeby pracował bez nadzoru.
W nagłówku CLAUDE.md jest taka linia:
Ten dokument jest „pierwszym źródłem" projektu. Ładowany automatycznie na początku każdej sesji Claude Code. Gdy zmieniasz decyzje techniczne, najpierw zmień tutaj; kod nadąży później.
To umowa workflow. Gdy decyduję się zmienić jakiś wybór techniczny — powiedzmy, podnieść główny model AI z gpt-5-mini do gpt-5 — pierwszy krok to nie ruszać initializera. Pierwszy krok to poprawić ten fragment w CLAUDE.md:
ai:
fast: gpt-5-mini # przed
fast: gpt-5 # po
Potem każę Claude'owi ponownie przeczytać CLAUDE.md i wyrównać kod.
Dlaczego? Bo jeśli zmienisz wartość w kodzie, a CLAUDE.md zostanie w tyle, następnym razem Claude czyta CLAUDE.md, widzi starą wartość i „uprzejmie" cofa twój kod. Źródłem konfliktu jest pojedynczy punkt awarii — CLAUDE.md bez synchronizacji. Konstytucja zostająca w tyle za rzeczywistością — tak zaczynają się wojny domowe.
Traktować CLAUDE.md jak konstytucję znaczy: zawsze biegnie przed kodem.
smarts.md, 5 dni, 92 commity:
Średnie życie PR-a: 30 minut. Bez wielkich refaktoringów. Bez „czekaj, ten kierunek był zły, rollback".
Nie dlatego, że Claude to magia. Dlatego, że w każdej sesji jechał po 565-liniowym torze. Wiedział, że nie wciągamy TypeScriptu, wiedział, że Solid Queue jest domyślną kolejką, wiedział, że funkcje view są cache'owane 60 sekund, wiedział, że każdy service musi implementować metodę klasową call, wiedział, że przed commitem ma czekać na moje potwierdzenie.
Zdejmij połowę tych ograniczeń — dostaniesz: 30 minut dziennie tłumaczenia „dlaczego nie używamy X", 5 minut review zależności, którą wciągnął „przy okazji", i Gemfile, który powoli się rozsypuje.
Nie zaczynaj od pustego pliku. Zacznij od najświeższej decyzji, która zabolała.
Jeżeli ostatnio Claude „ciągnie nowe zależności" — wpisz listę zakazów.
Jeżeli „byle co zmienia architekturę" — diagram architektury + „nowe mikrousługi, zmiana DB itd. wymagają potwierdzenia".
Jeżeli „nie pisze testów" — „co musi być pokryte testami jednostkowymi obowiązkowo".
Jeżeli „commituje za agresywnie" — „bez auto-commita, czekaj na wyraźną instrukcję".
Każdy ból — jedna pozycja. Reszty na razie nie pisz.
Po trzech miesiącach będziesz miał CLAUDE.md na 500 linii, gdzie za każdą linią stoi konkretne „nie chcę, żeby znów to robił". Ten dokument bije każdy szablon, bo jest dopasowany dokładnie do twojego projektu, twojego workflow, twojego zespołu (nawet jeśli to tylko ty).
Konstytucja nie powstaje za jednym razem. Krystalizuje się z konkretnych konfliktów, jeden po drugim.
Źródło: github.com/defi-io/smarts