Jak skonfigurować CLAUDE.md w 2026 roku: szablon i 6 zasad

Materiały o vibe codingu: narzędzia, studia przypadków, błędy. Poradniki Ailoot.

Po co potrzebujesz CLAUDE.md i dlaczego bez niego Claude zapomina o projekcie?#

We wtorek otwierasz Claude Code i wyjaśniasz: „Pracuję nad tym projektem, oto narzędzia, tego nie rób”. Działa.

W czwartek ten sam czat już się skończył, więc powtarzasz wszystko. W sobotę znowu, w poniedziałek jeszcze raz.

Tak wygląda praca z agentem bez CLAUDE.md: każde nowe okno to stażysta z czystą kartą, któremu musisz wciąż od nowa mówić te same rzeczy. Kiedyś poświęcałem 5-10 minut na wpisywanie tego wprowadzenia przed każdą sesją. Polecenia stawały się długie, bo cały kontekst musiałem przekazywać ręcznie. A rezultat nadal był ogólnikowy: agent nie znał moich odbiorców, ekonomiki ani zasad.

Dzięki aktualizowanemu plikowi CLAUDE.md znika wprowadzenie. Wszystkie zasady, które wcześniej powtarzałeś w każdym czacie, znajdują się w jednym pliku i automatycznie pojawiają się na początku każdej sesji. Polecenie staje się krótkie: „zrób X”, zamiast „pracuję nad projektem Y, narzędzia to Z, nie rób A ani B, a przy okazji pamiętaj też o C”.

Znikają też powtarzające się błędy.

Każdy błąd agenta to powód, by dodać jedną linijkę do CLAUDE.md. Po miesiącu masz żywą „konstytucję projektu”, a Claude przestaje wpadać w te same, znane pułapki.

Jest też trzeci poziom: agent przestaje pisać w próżni. Za pośrednictwem CLAUDE.md kieruję Claude’a do folderów z kontekstem: tam, gdzie znajdzie informacje o odbiorcach, cenach i identyfikacji marki. Bez tego kierowania agent pisze „wysokiej jakości rozwiązania”, nie znając mojej ekonomiki, więc wychodzą abstrakcyjne, schematyczne i „takie jak u wszystkich”.

Czym jest CLAUDE.md i w jakiej kolejności Claude go odczytuje?#

Anthropic opisuje CLAUDE.md w swojej oficjalnej dokumentacji tak:

Cztery miejsca, w których Claude Code szuka pliku CLAUDE.md, w kolejności rosnącego priorytetu:

Wszystkie cztery pliki są wczytywane do kontekstu jednocześnie. Jeśli ich zasady są sprzeczne, Anthropic mówi wprost w swojej dokumentacji, że nie wiadomo, która z nich będzie miała pierwszeństwo; Claude może wybrać dowolną. Dlatego prościej jest trzymać wszystkie krytyczne informacje w pliku CLAUDE.md projektu i unikać duplikatów.

Jest jeden szczegół techniczny, o którym prawie nikt nie pisze, a który wyjaśnia wiele dziwnych zachowań.

Innymi słowy, CLAUDE.md nie jest „monitem systemowym” w ścisłym znaczeniu. To pierwsza wiadomość użytkownika, którą widzi Claude. Zatem jego zasady to mocne sugestie, a nie prawa. Jeśli zasada wymaga egzekwowania, użyj przetestowanego hooka dla objętego nim zdarzenia oraz uprawnień lub izolacji środowiska dla szerszej granicy dostępu. Automatyczne uruchomienie hooka nie czyni jego sprawdzeń kompletnymi. Poniżej wyjaśnię granicę między hooks a CLAUDE.md.

Jak w 5 minut napisać minimalny CLAUDE.md (gotowy szablon)?#

Poniżej znajduje się szablon, który sprawdziłem w dziesiątkach moich projektów. Dzięki niemu plik ma około 80-120 wierszy, czyli mieści się w zaleceniu Anthropic, by celować poniżej 200 wierszy. Ten szablon pozwala agentowi uzyskiwać najbardziej sensowne wyniki.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Aby Claude automatycznie wypełnił ten szablon dla twojego projektu, przekaż mu to polecenie. Odczyta kontekst i uzupełni pola w nawiasach kwadratowych:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Celuj w CLAUDE.md poniżej 200 wierszy. Jeśli jest dłuższy, przejrzyj powtórzenia i przenieś szczegółowe procedury do podlinkowanych plików. Zachowaj kluczowe zasady planowania, refleksji i repozytorium, a potem sprawdź je na reprezentatywnych zadaniach.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Jeśli nie masz jeszcze folderów about-me/ i business/, to nie szkodzi. Claude zada pytania doprecyzowujące i przygotuje minimalny CLAUDE.md na podstawie dostępnych informacji. Foldery możesz utworzyć później, gdy już będziesz wiedzieć, co w nich umieścić.

Jakie 6 zasad sprawia, że CLAUDE.md jest żywym dokumentem?#

Zasada 1. Nie przekraczaj 200 wierszy

Anthropic zwięźle ujmuje to w swojej oficjalnej dokumentacji:

Długi plik CLAUDE.md działa przeciwko sobie na dwa sposoby. Po pierwsze, zużywa tokeny. Plik z 800 wierszami instrukcji jest wczytywany do każdego okna i podczas każdej sesji pochłania kilka tysięcy tokenów z twojego limitu. Przy subskrypcji Pro z dziennym limitem zauważalnie zmniejsza to liczbę dostępnych sesji. Po drugie, model zaczyna ignorować zasady.

Dokumentacja zaleca celowanie poniżej 200 wierszy, aby ograniczyć zużycie kontekstu i poprawić przestrzeganie instrukcji. Nie ustanawia ostrej granicy awarii przy wierszu 201. Zanim zdecydujesz, co przenieść, przejrzyj przydatność, sprzeczności, liczbę wczytanych tokenów i rzeczywiste wyniki zadań.

Zasada 2. Kończ każdą sesję refleksją

W CLAUDE.md napisz: „Na koniec każdej sesji zapisz, co zrobiłeś i czego się nauczyłeś, w retrospectives/YYYY-MM-DD_*.md”. Po dodaniu tego wiersza Claude sam zacznie kończyć każdą sesję refleksją; nie musisz o to prosić.

Po co robić refleksję:

• Dwa tygodnie później możesz otworzyć starą retrospektywę i przypomnieć sobie, dlaczego wybrałeś tę drogę.
• Gdy po miesiącu wrócisz do projektu, będziesz mieć gotową mapę ostatnich decyzji.
• Jeśli pracujesz w zespole, współpracownik może przeczytać retrospektywę i w 2 minuty zrozumieć aktualny stan, bez rozmowy.

Zasada 3. Rób commit po każdym zakończonym zadaniu

W moim CLAUDE.md jest napisane: „Po każdym zakończonym zadaniu utwórz commit z opisową wiadomością”. Claude sam zaczyna dzielić pracę na atomowe commity.

Daje ci to dwie korzyści. Po pierwsze, jeśli coś się zepsuje, możesz cofnąć jedną operację, a nie „wszystko, co dziś zrobiłem”. Po drugie, historia commitów staje się dziennikiem pracy, pokazującym, co i w jakiej kolejności się zmieniło.

Zasada 4. Zawsze sprawdzaj folder business/

Przy każdym zadaniu dotyczącym klientów, produktów lub tekstów agent powinien najpierw otworzyć business/INDEX.md i odpowiedni plik z tego folderu. Mój CLAUDE.md mówi wprost: „Podczas pracy nad interfejsem lub tekstem najpierw sprawdź business/audience/avatar.md i business/assets/brand-guidelines.md”.

Bez tej zasady Claude pisze teksty w „ogólnym stylu dobrej strony internetowej”. Dzięki niej teksty pasują do twojego stylu, twojego klienta i nie zawierają zakazanych przez ciebie słów.

Zasada 5. Dodawaj zasadę po każdym błędzie agenta

To główna zasada, która utrzymuje CLAUDE.md przy życiu.

Przykłady z mojego CLAUDE.md dodane po konkretnych błędach:

• „Nigdy nie commituj cudzych plików WIP za pomocą git add . - dodawaj pliki według nazw”.
• „Przed wypchnięciem zmian do main sprawdź git log origin/main..main --oneline - jeśli wynik nie jest pusty, nie wypychaj zmian”.
• „Nie wymyślaj wartości - pobieraj je z .env albo z kodu. Zwłaszcza adresy URL, nazwy użytkowników i tokeny”.

Każdy z tych wierszy jest śladem konkretnego zdarzenia. Kiedyś agent commitował niedokończoną gałąź partnera. Raz dołączyłem cudze, niewypchnięte commity. Innym razem agent wymyślił nieistniejący adres URL. Każdy błąd staje się zasadą i ta sama rana zadana sobie samemu już się nie powtarza.

Zasada 6. Zasady bezpieczeństwa umieszczaj w .claude/settings.json, a nie w CLAUDE.md

W CLAUDE.md możesz napisać „nie dotykaj .env”, ale to tylko prośba; Claude może ją zignorować, bo CLAUDE.md jest wczytywany jako wiadomość użytkownika, a nie prawo. W kwestiach krytycznego bezpieczeństwa użyj .claude/settings.json, gdzie możesz bezwzględnie blokować określone polecenia.

Lista blokowanych poleceń, którą dodaję do każdego nowego projektu:

• rm -rf (rekurencyjne usuwanie dowolnych plików).
• Odczyt całego pliku .env (Read .env).
• export i curl w jednym poleceniu (schemat mogący posłużyć do wycieku sekretów na zewnątrz).
• git push --force bez wyraźnej zgody.

Inne poradniki znajdziesz na Ailoot.

Jak wygląda CLAUDE.md w działającej firmie (anatomia pliku z 280 wierszami)?#

Większość przykładów CLAUDE.md dostępnych w internecie to techniczne szablony dla programistów: „Używaj TypeScript”, „Nie pisz testów dłuższych niż 50 wierszy”. Dla przedsiębiorcy taki CLAUDE.md jest bezużyteczny - pomija stronę biznesową.

Poniżej znajduje się struktura mojego roboczego CLAUDE.md. Usunąłem konkretne zasady i ścieżki, bo odzwierciedlają moje wewnętrzne działania. Strukturę i logikę sekcji można jednak zastosować w każdym projekcie: dopasuj ją do własnej sytuacji, a otrzymasz działający plik.

1. Krótki opis projektu (15 wierszy). Czym się zajmujemy, kto jest odbiorcą i jakie produkty oferujemy. Nie streszczenie strony marketingowej, ale podsumowanie dla agenta, które pozwoli mu zrozumieć, „dokąd zmierzamy”.

2. O mnie (10 wierszy). Odnośnik do folderu about-me/ - cyfrowego odwzorowania mojego sposobu myślenia. Ton, wartości, zasady, zakazane słowa. Gdy Claude pisze tekst „w moim imieniu”, najpierw czyta ten folder, by zachować zgodność z moim głosem.

3. Struktura repozytorium (20 wierszy). Drzewo z komentarzami: gdzie znajduje się kod, gdzie kontekst biznesowy, gdzie plany i refleksje. Bez tej mapy Claude za każdym razem szuka plików na ślepo.

4. Tabela „Gdzie szukać informacji” (25 wierszy). Kierowanie od „pytania → pliku”. Na przykład w przypadku agencji nieruchomości może to być: „potrzebuję warunków kredytu hipotecznego → business/products/mortgage.md” albo „potrzebuję tonu wypowiedzi do postów → business/assets/voice.md”. Podstaw własne pliki. Ta tabela jest sercem CLAUDE.md. Bez niej agent zgaduje, który plik zawiera odpowiedź. Dzięki niej trafia prosto do źródła.

5. Kluczowe zasady projektu (40 wierszy, 10-15 punktów). Ta sekcja rośnie stopniowo i wymaga najwięcej pracy. Każdy punkt jest śladem konkretnego błędu. W przypadku sklepu internetowego zasady mogą brzmieć: „nigdy nie wpisuj cen ani terminów dostawy na stałe”, „nie publikuj produktu bez wyraźnego polecenia” oraz „przed publikacją oferty sprawdź jej styl w słowniku marki”. Ta sekcja to „konstytucja projektu”.

6. Planowanie operacyjne (20 wierszy). Tabela wyzwalaczy łącząca „zwrot użytkownika → działanie”. Na przykład: „Gdy powiem «zaplanuj tydzień», otwórz ops/monthly.md i utwórz plik na ten tydzień”. Dzięki temu Claude staje się asystentem operacyjnym, który rozumie kontekst poleceń.

7. Narzędzia (5 wierszy). Technologie. Krótko, bez zbędnych słów.

8. Publikowanie (15 wierszy). Instrukcja krok po kroku, jak opublikować zmiany na produkcji: które polecenia uruchomić, w jakiej kolejności i co sprawdzić. Kiedyś wyjaśniałem to za każdym razem. Teraz Claude już wie.

9-12. Bezpieczeństwo (35 wierszy). Cztery osobne podsekcje: zasady pracy z .env, dostęp do produkcyjnej bazy danych, bezpieczne polecenia do prezentacji (nagrania ekranu, transmisje, zrzuty ekranu, by przypadkowo nie ujawnić tokenów) oraz zasady rotacji sekretów.

13. Folder plans/ (10 wierszy). Standard planowania: nazwa pliku, struktura etapów i zawartość bloku podsumowania.

14. Folder retrospectives/ (5 wierszy). Standard refleksji: szablon, nazwa pliku i wymagana zawartość.

15. Dane z bieżącej bazy (15 wierszy). Zasada oznaczania „świeżych danych”: gdy plik wskazuje, że dane liczbowe muszą być aktualne, agent pobiera je ze źródła zamiast używać starych. Dzięki temu Claude nie korzysta z wczorajszych danych.

16. Język (3 wiersze). „Zawsze odpowiadaj w preferowanym przez użytkownika języku. Używaj tylko łączników, nie półpauz”.

Łącznie około 280 wierszy. To przekracza cel zwięzłości, ale nie czyni pliku nieprawidłowym. W tym przykładzie pozostawał przydatny; decyzja o jego zachowaniu powinna zależeć od zmierzonego użycia kontekstu i reprezentatywnych zadań testowych. Tabele nie są automatycznie tańsze w tokenach od prozy.

Co robi polecenie /init i dlaczego to nie wystarczy?#

Anthropic opisuje to polecenie w dokumentacji tak:

Co /init robi dobrze:

• Rozpoznaje narzędzia na podstawie package.json, Cargo.toml i pyproject.toml.
• Wypisuje polecenia do budowania i testowania.
• Wykrywa konwencje na podstawie istniejących plików (.eslintrc, .prettierrc).
• Zauważa istniejące zasady Cursor (.cursorrules, .cursor/rules/) i Copilota oraz uwzględnia istotne części. W trybie CLAUDE_CODE_NEW_INIT=1 wykrywa AGENTS.md.

Czego /init nie zrobi:

• Nie będzie wiedzieć, kim jest twój klient.
• Nie uwzględni zakazanych przez ciebie słów w tekstach.
• Nie doda zasad dotyczących błędów agenta, bo jeszcze ich nie było.
• Nie utworzy tabeli „gdzie szukać informacji” dla twojej struktury biznesowej.

Właściwy przebieg pracy wygląda więc tak:

1. Uruchom /init w Claude Code

   Otrzymasz początkowy CLAUDE.md mający 30-50 wierszy, z narzędziami i poleceniami. To techniczny fundament.

2. Uzupełnij go szablonem z tego artykułu

   Skorzystaj z sekcji „Minimalny CLAUDE.md w 5 minut”. Dodaj sekcje dotyczące nawigacji, kierowania i zasad.

3. Uzupełnij pola w nawiasach kwadratowych

   Przekaż Claude’owi polecenie „przeczytaj mój projekt i uzupełnij szablon”. Jeśli foldery business/ i about-me/ jeszcze nie istnieją, Claude zada pytania doprecyzowujące.

4. Przeprowadź test warunków skrajnych

   Powiedz Claude’owi: „Przeczytaj mój CLAUDE.md i znajdź 10 niejasności, które mogą sprawić, że jako agent źle go zrozumiesz”. Otrzymasz listę poprawek.

5. Potem używaj pliku

   Dodawaj linijkę po każdym błędzie agenta. Po miesiącu będziesz mieć żywy plik CLAUDE.md dopasowany do twojej firmy.

Polecenie do kroku czwartego:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md, AGENTS.md i MEMORY.md: kto co odczytuje w 2026 roku?#

Główne pytanie, które nurtuje początkujących, brzmi: czy Claude Code odczytuje AGENTS.md? Przed wrześniem 2026 roku odpowiedź brzmiała „nie”: dokumentacja Anthropic zalecała utworzenie CLAUDE.md importującego AGENTS.md. Od wersji 2.1.277 (wydanej 18 września 2026 roku) Claude Code odczytuje sam plik AGENTS.md, ale tylko wtedy, gdy w bieżącym folderze roboczym ani żadnym folderze nadrzędnym nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md.

Jeśli projekt ma plik CLAUDE.md, Claude Code domyślnie odczytuje tylko jego i pomija AGENTS.md. Możesz zmienić to w /config, w sekcji Project instructions: na przykład ustawienie claude-md-and-agents-md sprawi, że będą odczytywane oba pliki. Inna metoda działa w każdej wersji: dodaj import do CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

Składnia @filename importuje inny plik. Claude odczytuje go i wczytuje do kontekstu razem z CLAUDE.md. Import nie powoduje ponownego odczytania pliku, nawet jeśli Claude Code sam potrafi odczytywać AGENTS.md.

Kiedy potrzebujesz AGENTS.md. Jeśli pracujesz równolegle z Claude Code oraz Codex CLI, Cursorem lub Copilotem, utwórz AGENTS.md jako jedyne źródło prawdy, umieść @AGENTS.md w CLAUDE.md i dodaj na wierzchu zasady specyficzne dla Claude’a. Jeśli takich zasad nie ma, nie musisz tworzyć CLAUDE.md: od wersji 2.1.277 Claude Code sam odczyta AGENTS.md. Jeśli pracujesz wyłącznie w Claude Code, AGENTS.md nie jest potrzebny; wystarczy jeden plik CLAUDE.md. Instrukcje krok po kroku dotyczące wszystkich opcji znajdziesz w poradniku korzystania z AGENTS.md i CLAUDE.md w jednym projekcie.

Czym jest MEMORY.md? Od niedawnej aktualizacji Claude Code automatycznie zapisuje notatki o tobie w ~/.claude/projects/<project-name>/memory/MEMORY.md. Mogą one dotyczyć nawyków w rozmowie („użytkownik woli krótkie odpowiedzi”), powtarzających się zwrotów („zakazał emoji w kodzie”) i obserwacji dotyczących zachowania („pracuje na macOS, używa zsh”).

To odrębny system pamięci, a nie CLAUDE.md. Nie piszesz go ręcznie; Claude tworzy go na podstawie rozmów. Jeśli MEMORY.md zawiera coś, co powinno stać się zasadą, przenieś to do CLAUDE.md. Jeśli zawiera coś niepotrzebnego lub nieprawidłowego, możesz usunąć to ręcznie; to plik tekstowy.

Jaki rozmiar CLAUDE.md jest użyteczny i jak ocenić długi plik?#

W każdym oknie Claude Code do kontekstu wczytywanych jest kilka warstw: monit systemowy Anthropic (szacowany na dziesiątki tysięcy tokenów), twój CLAUDE.md, pliki importowane przez @, MEMORY.md, bieżąca historia czatu oraz zawartość plików otwieranych przez Claude’a. Wszystko to musi zmieścić się w kontekście modelu (200K tokenów w przypadku Sonnet, 1M w przypadku Opus).

Im większy CLAUDE.md, tym mniej miejsca zostaje na bieżącą pracę. Plik z 1,000 wierszami to około 8,000 tokenów, powtarzanych w każdej sesji. Przy subskrypcji Pro (z mojego doświadczenia to około 10-12 „intensywnych” poleceń dziennie) zmniejsza to twoje możliwości o jedną czwartą.

Koszt to tylko jeden problem. Przestrzeganie zasad może słabnąć przy długich, nieistotnych lub sprzecznych instrukcjach; nie istnieje uniwersalna liczba niezawodnie przestrzeganych reguł. Przetestuj kilka reprezentatywnych zadań obejmujących zasady krytyczne, zapisz błędy i porównaj działanie po ukierunkowanej zmianie.

Oto praktyczna zasada dotycząca rozmiaru:

• 80-120 wierszy - wygodny zakres początkowy dla zwięzłej mapy projektu, bez gwarancji poziomu przestrzegania zasad.
• 150-200 wierszy - przydatny sygnał do oceny trafności i przeniesienia szczegółowych procedur do podlinkowanych plików.
• 200-300 wierszy - sprawdź liczbę tokenów, powtórzenia i wyniki zadań; opisany wyżej przykład firmowy z 280 wierszami może nadal działać dobrze.
• 400+ wierszy - mocny powód do ukierunkowanego przeglądu, nie dowód bezużyteczności. Zachowaj kluczowe ograniczenia i przenoś szczegóły po sprawdzeniu, że linki i zasady nadal działają.

Sama liczba wierszy nie potwierdza sukcesu ani porażki. Po zmianie powtórz te same reprezentatywne zadania i sprawdź ważne reguły zamiast przypisywać wymyślony procent zgodności.

Anthropic podaje w dokumentacji bezpośredni test:

Zastosuj to do każdego wiersza. Jeśli odpowiedź brzmi „nadal zrobiłby to dobrze”, usuń wiersz. CLAUDE.md nie jest miejscem na dokumentację, historię decyzji ani filozofię. Służy wyłącznie do zapisania zasad, których agent potrzebuje, by czegoś nie zepsuć.

Jakie 7 błędów sprawia, że CLAUDE.md staje się bezużyteczny?#

Błąd 1. „Bądź dobrym inżynierem”

Najczęstszy błąd. Ludzie zapisują w CLAUDE.md ogólne życzenia: „pisz czysty kod”, „stosuj najlepsze praktyki”, „myśl jak starszy inżynier”.

Te słowa nic nie znaczą. Claude i tak pisze „czysty kod” w ogólnym sensie. Te wiersze zajmują kontekst, nie wpływając na żadną decyzję.

Zastąp „pisz czysty kod” zasadami „używaj wcięć o szerokości 2 spacji”, „nie używaj any w TypeScript” albo „funkcje nie mogą mieć więcej niż 30 wierszy”. Konkretne i możliwe do zweryfikowania.

Błąd 2. Powielanie wiedzy, którą Claude już ma

Opisy standardowych konwencji języka („w JavaScript funkcje są obiektami pierwszej klasy”, „TypeScript ma typowanie statyczne”). Wyjaśnienia, jak działa npm, git albo docker.

Claude nauczył się tego wszystkiego podczas trenowania. Powtarzanie tych informacji w CLAUDE.md nic nie daje; jedynie zmniejsza dostępny kontekst.

Błąd 3. Długie instrukcje krok po kroku w CLAUDE.md

Długie instrukcje o tym, „jak wdrożyć projekt”, „jak utworzyć migrację bazy danych” albo „jak skonfigurować nowy komponent”. Dziesiątki wierszy objaśniających kolejne kroki.

To nie jest miejsce na długie instrukcje krok po kroku. To miejsce na zasady w jednym wierszu. Umieść długie instrukcje w skills/ (osobnym mechanizmie Claude Code wczytywanym na żądanie) albo w docs/. W CLAUDE.md dodaj jednolinijkowy odnośnik: „Podczas tworzenia migracji otwórz docs/migrations.md”.

Błąd 4. Zasady już sprawdzane przez automatyczny analizator kodu

„Używaj średników”, „nie zostawiaj nieużywanych importów”, „nie używaj var”. ESLint, Prettier i Biome wykrywają to wszystko - to lintery (automatyczne narzędzia do sprawdzania kodu).

Linter jest deterministyczny: uruchamia się, znajduje błąd i go poprawia. Zasada w CLAUDE.md jest probabilistyczna; agent może o niej zapomnieć. Nie ma potrzeby jej powielać - łatwiej skonfigurować linter.

Błąd 5. Sekrety w CLAUDE.md

Widziałem hasła do kont testowych, tokeny API środowiska testowego i odnośniki do uwierzytelnionych paneli administracyjnych. Wszystko znajdowało się w pliku commitowanym do gita i wczytywanym do kontekstu modelu Anthropic.

Nigdy. Sekrety należą do .env, który jest ujęty w .gitignore. Co najwyżej CLAUDE.md powinien mówić: „Nie odczytuj całego pliku .env; użyj grep dla konkretnej zmiennej”.

Błąd 6. Zbiórka na 500+ wierszy, której nikt nie czyścił od sześciu miesięcy

CLAUDE.md urósł, powiela połowę docs/, przeczy sobie w kilku miejscach i nikt nie pamięta, co się w nim znajduje. Agent zaczyna ignorować większość treści. Zespół narzeka, że „Claude nie przestrzega instrukcji”, i dodaje więcej zasad, co pogarsza sytuację.

Oznaki zaniedbanego CLAUDE.md: ponad 300 wierszy, powtórzone zasady w różnych sekcjach, nieaktualne odnośniki do nieistniejących już plików oraz „historyczne” notatki, takie jak „w 2024 roku zdecydowaliśmy się na to rozwiązanie, a potem zmieniliśmy zdanie”.

Rozwiązanie: co dwa tygodnie poproś Claude’a o przegląd według testu Anthropic: „Gdyby usunąć ten wiersz, czy agent popełniłby błąd?”. Usuń wszystko, dla czego odpowiedź brzmi „nie”.

Błąd 7. Utworzenie CLAUDE.md i zapomnienie o nim

To przeciwieństwo poprzedniego błędu. Plik został przygotowany raz, dwa miesiące temu, i od tamtej pory nie był ruszany. W międzyczasie zmieniły się narzędzia, dodano nowe foldery i pojawiły się nowe błędy agentów. CLAUDE.md nic o tym nie wie, bo nikt go nie aktualizował.

Wyraźny znak ostrzegawczy: powtarzasz tę samą instrukcję podczas każdej sesji. „Nie rób X”, „nie dotykaj Y”, „pamiętaj o Z”. Jeśli powtórzyłeś coś więcej niż dwa razy, ta zasada powinna znaleźć się w CLAUDE.md, a nie w twojej głowie.

Jak sprawić, by CLAUDE.md sam się uczył dzięki zasadzie „aktualizuj na koniec sesji”?#

Mój CLAUDE.md zawiera krótką sekcję:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Po dodaniu tej sekcji do CLAUDE.md Claude zaczął pod koniec każdej sesji pytać: „Czy jest coś nowego, co warto zapisać?”. Jeśli tak, proponował wersję roboczą zasady, ja ją doprecyzowywałem, a potem tworzony był plik.

Po dwóch miesiącach pracy w ten sposób mam ponad dwa tuziny plików w about-me/feedback/ - zasad wyciągniętych z konkretnych błędów. Każdy plik to jedna strona w formacie Zasada → Dlaczego → Jak. Folder stał się „drugą pamięcią”, zapisującą moje indywidualne preferencje i zakazy.

Każdy błąd przestaje się powtarzać, bo zmienia się w zasadę, a zasady kumulują się i wzajemnie wzmacniają. Po sześciu miesiącach Claude zna mój projekt lepiej, niż ja pamiętam go po miesięcznej przerwie.

Jak dodać do CLAUDE.md zasady prawne, marketingowe i operacyjne?#

Dla większości zespołów CLAUDE.md to dokument wyłącznie techniczny: narzędzia, polecenia do budowania, konwencje kodowania. To przydatne, ale stanowi tylko jedną trzecią wartości.

Gdy przedsiębiorca prowadzi CLAUDE.md, warto dodać sekcje biznesowe. Najważniejsze są trzy:

Zasady prawne (dla regulowanych rynków)

Jeśli publikujesz teksty w regulowanej branży (finanse, medycyna, reklama leków, produkty dla dzieci), zakazane słowa mają znaczenie prawne i powinny znaleźć się w CLAUDE.md jako jawne zasady. Nie w czyjejś głowie, nie na zrzucie ekranu z edytora - w pliku, który agent widzi podczas każdej sesji.

Przykład dla projektu fintechowego bez licencji bankowej:

Uwaga redakcyjna: poniższy przykład pokazuje format wewnętrznej zasady dla konkretnego projektu. Nie stanowi uniwersalnego zezwolenia na używanie wymienionych terminów: dopuszczalność stwierdzeń zależy od obowiązującego prawa i statusu firmy.

🚨 KRYTYCZNE - zakaz używania sformułowań finansowych. W materiałach dla klientów nie używaj: „depozyt”, „gwarantowany zysk” ani „produkt inwestycyjny”. Używaj: „konto oszczędnościowe”, „oczekiwany zysk” i „produkt o zmiennym oprocentowaniu”. Powodem są wymogi prawne dotyczące reklamy usług finansowych, które mają zastosowanie do tego projektu.

Ten blok w CLAUDE.md robi prostą rzecz: za każdym razem, gdy prosisz Claude’a o napisanie tekstu dla klientów, agent sprawdza go pod kątem tych zakazów. Bez tej zasady zakazane słowa pojawiają się w co trzeciej kampanii. Dzięki niej zapominasz o ich istnieniu.

To samo podejście działa w przypadku:

• Projektów medycznych (żadnych twierdzeń, że coś „leczy” lub „uzdrawia”).
• Reklamy leków (żadnych twierdzeń, że coś jest „najskuteczniejsze”; obowiązkowe ostrzeżenia).
• Każdej regulowanej branży, w której obowiązują własne zasady reklamowe.

Styl marketingowy i format tekstów

Jeśli regularnie publikujesz teksty (w mediach społecznościowych, newsletterach, na stronach internetowych), warto opisać ich format w jednym akapicie w CLAUDE.md. Oto przykład dla influencera albo agencji prowadzącej kanał komunikacyjny:

Przy pisaniu postów na kanał zajrzyj do style/posts.md. Używaj dozwolonych w kanale znaczników formatowania i unikaj „niebezpiecznych” znaków specjalnych. Kończ wezwaniem do działania zawierającym tag UTM zgodny z konwencją: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude wcześniej pisał posty w „ogólnym stylu strony marketingowej”. Teraz stosuje twój format, używa twoich znaczników UTM i nie zdradza, że tekst napisała sztuczna inteligencja.

Zwyczaje operacyjne

Tabele wyzwalaczy. Gdy wypowiadasz określony zwrot, agent wie, które pliki otworzyć i jakie działania podjąć. Oto przykład dla zespołu planującego tydzień:

„Zaplanuj tydzień” → otwórz ops/monthly.md, utwórz w tym samym folderze plik YYYY-WNN.md i przenieś zadania z ops/backlog.md pod odpowiednie dni. „Co jest w backlogu?” → odczytaj ops/backlog.md i przedstaw zawartość w formie listy. „Zamknij tydzień” → uzupełnij sekcję „Podsumowanie tygodnia” w pliku bieżącego tygodnia.

Dzięki takim tabelom Claude zmienia się z „pomocnika piszącego kod” w „operatora”, który zna rutynę twojej firmy. W każdy poniedziałek mówię „zaplanujmy tydzień”, a Claude otwiera odpowiednie pliki, odczytuje cele miesięczne i proponuje podział zadań.

Jak sprawdzić CLAUDE.md za pomocą 12-punktowej listy kontrolnej w 5 minut?#

1. Rozmiar. Czy plik jest zwięzły, a około 200 wierszy traktuje jako cel przeglądu, nie granicę zaliczenia?
2. Nazwa. Czy nazywa się dokładnie CLAUDE.md, z wielkimi literami, a nie claude.md?
3. Lokalizacja. Czy znajduje się w katalogu głównym projektu lub w ./.claude/CLAUDE.md?
4. Opis projektu. Czy pierwsze 5 wierszy jasno wyjaśnia, czym jest projekt i dla kogo?
5. Narzędzia. Czy technologie zostały wymienione wprost i bez zbędnych słów?
6. Struktura. Czy znajduje się tam diagram repozytorium z objaśnieniami?
7. Kierowanie. Czy znajduje się tam tabela „pytanie → plik” wskazująca, gdzie szukać odpowiedzi?
8. Zasady. Czy istnieje sekcja z regułami zaczynającymi się od „nigdy” i „zawsze”?
9. Konkretność. Czy każdą zasadę da się zweryfikować? („Używaj 2 spacji”, a nie „pisz pięknie”).
10. Aktualizowanie. Czy istnieje zasada „sprawdź na koniec sesji, co dodać”?
11. Refleksja. Czy istnieje zasada „zapisz podsumowanie sesji w retrospectives/”?
12. Bezpieczeństwo. Czy krytyczne zakazy (.env, rm -rf) znajdują się również w .claude/settings.json?

Jeśli masz więcej niż pięć odpowiedzi „nie”, otwórz Claude’a i przekaż mu to polecenie:

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

Wystarczająco zwięzły dla zadania; przegląd w okolicy 200 wierszy bez traktowania tej liczby jako twardego limitu

Project description in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

Czego użyć po CLAUDE.md: Plan Mode, Skills czy sub-agentów?#

CLAUDE.md to fundament. Gdy już działa, możesz dodać trzy mechanizmy Claude Code, które wzajemnie się wzmacniają.

Plan Mode. Tryb, w którym Claude najpierw tworzy plan zmian, czeka na twoją zgodę, a dopiero potem zaczyna pracę. Włącz go za pomocą Shift+Tab lub polecenia /plan. Rozwiązuje główny problem vibe codingu: „Poprosiłem Claude’a, żeby naprawił jedną rzecz, a on przepisał połowę projektu”. W Plan Mode to się nie stanie - zobaczysz plan, zanim agent dotknie jakichkolwiek plików.

Skills. Osobne pliki .md w folderze .claude/skills/, zawierające wiedzę dla określonego rodzaju zadań. Na przykład skill „jak napisać migrację bazy danych” zawiera konkretną procedurę, szablon i przykłady. Ta wiedza nie znajduje się w CLAUDE.md, bo jest zbyt obszerna. Gdy Claude napotka zadanie typu „napisz migrację”, wczytuje odpowiedni skill i postępuje zgodnie z nim.

Sub-agenci. Jeśli zadanie wymaga dużego kontekstu (na przykład przeglądu rozbudowanej funkcji), Claude może uruchomić osobnego sub-agenta z jego własnym, czystym kontekstem. Sub-agent wykonuje pracę i zwraca wynik bez zagracania kontekstu głównego czatu.

Wszystkie trzy mechanizmy korzystają z CLAUDE.md jako punktu wyjścia: odczytują go na początku pracy, aby poznać kontekst projektu. Dlatego te funkcje również działają kiepsko bez aktualizowanego CLAUDE.md. Najpierw fundament, potem kolejne warstwy.

Następny krok. Utwórz plik CLAUDE.md w katalogu głównym projektu, skopiuj szablon z początku tego artykułu i uzupełnij pola w nawiasach kwadratowych za pomocą pomocniczego polecenia. Potem korzystaj z pliku: każdy błąd agenta zamieniaj w nową linijkę. Po dwóch lub trzech tygodniach CLAUDE.md przestanie być „dokumentem, który napisaliśmy i o nim zapomnieliśmy”, a stanie się czymś, z czego Claude faktycznie korzysta podczas każdej sesji.

Jeśli chcesz zbudować pełny zestaw wokół CLAUDE.md - folder business/ na Drugi Mózg, folder about-me/ do cyfrowego odwzorowania ciebie, podstawowe skille i skonfigurowany Plan Mode - skorzystaj z instrukcji i przykładów w tym artykule. Poradniki Ailoot.

Czytaj dalej poradniki Ailoot.