---
title: "Jak napisać CLAUDE.md: poradnik dla zespołu programistów"
url: "https://szymonlakomy.pl/jak-napisac-claude-md"
description: "Jak napisać CLAUDE.md dla Claude Code: gdzie leży plik, co wpisać, dlaczego poniżej 200 linii, importy @, reguły w .claude/rules i AGENTS.md."
updated: "2026-11-14"
author: "Szymon Łakomy"
language: "pl"
---

[Strona główna](https://szymonlakomy.pl/) [Claude Code w firmie](https://szymonlakomy.pl/claude-code-w-firmie) Jak napisać CLAUDE.md

# Jak napisać CLAUDE.md: plik instrukcji, który Claude Code naprawdę stosuje

CLAUDE.md to plik z instrukcjami projektu, który Claude Code wczytuje na starcie każdej sesji. Dobrze napisany zastępuje powtarzanie tych samych uwag, a za długi albo sprzeczny sprawia, że agent stosuje zasady wybiórczo.

Autor: [Szymon Łakomy](https://szymonlakomy.pl/o-mnie). Aktualizacja: 14 listopada 2026

Jak napisać CLAUDE.md: **krótko, konkretnie i tylko o tym, czego Claude nie wyczyta z kodu**, czyli polecenia do budowania i testów, mapa katalogów, zasady projektu i pułapki. Dokumentacja Anthropic zaleca mniej niż 200 linii na plik i instrukcje, które da się sprawdzić. Wieloetapowe procedury przenieś do skilla, zasady jednego modułu do.claude/rules, a twarde zakazy do hooka albo reguły deny.

## Gdzie leży CLAUDE.md i kogo dotyczy?

CLAUDE.md może leżeć na czterech poziomach, a Claude Code łączy treść wszystkich znalezionych plików, zamiast nadpisywać jeden drugim.

| Poziom | Lokalizacja | Kogo dotyczy |
| --- | --- | --- |
| Polityka organizacji | Windows: C:\Program Files\ClaudeCode\CLAUDE.md, macOS: /Library/Application Support/ClaudeCode/CLAUDE.md, Linux i WSL: /etc/claude-code/CLAUDE.md | całą firmę, plik wdraża dział IT |
| Użytkownik | ~/.claude/CLAUDE.md | jedną osobę we wszystkich jej projektach |
| Projekt | ./CLAUDE.md albo./.claude/CLAUDE.md | cały zespół, bo plik jest w repozytorium |
| Osobisty plik projektu | ./CLAUDE.local.md, dopisany do.gitignore | jedną osobę w jednym projekcie |

Według dokumentacji Claude Code, stan na listopad 2026.

Pliki z katalogu startowego i katalogów nadrzędnych ładują się od razu, a CLAUDE.md z podkatalogu dopiero wtedy, gdy Claude pracuje na plikach w tym podkatalogu. Pliki pamięci otworzysz i poprawisz poleceniem /memory.

## Co wpisać do CLAUDE.md?

Do CLAUDE.md wpisuję fakty potrzebne w każdej sesji, których agent nie odczyta szybko z samego kodu.

| Sekcja | Co wpisać | Przykład |
| --- | --- | --- |
| Polecenia | uruchomienie, testy, build, lint | npm test uruchamiaj przed każdym commitem |
| Mapa katalogów | gdzie leżą najważniejsze części kodu | handlery API są w src/api/handlers |
| Zasady projektu | konwencje, których nie pilnuje linter | kwoty tylko z jednego pliku z cenami |
| Pułapki | miejsca, w których mylą się agent i nowe osoby | nie edytuj katalogu dist, bo build go nadpisuje |
| Definicja ukończenia | kiedy zadanie jest skończone | testy przechodzą, kompilacja bez błędów |

Przykłady są hipotetyczne. Wpisz polecenia i ścieżki z własnego repozytorium.

Sygnał, że czas coś dopisać: Claude drugi raz robi ten sam błąd albo powtarzasz tę samą poprawkę w nowej sesji. Wstępną wersję przygotuje polecenie /init, a Ty skracasz ją i uzupełniasz o to, czego z kodu nie widać.

## Jak pisać instrukcje, które Claude stosuje?

Instrukcje w CLAUDE.md pisz konkretnie, krótko i bez sprzeczności, bo Claude traktuje ten plik jako kontekst, a nie konfigurację, której musi bezwzględnie przestrzegać.

- **Konkretnie i sprawdzalnie.** Zamiast „testuj zmiany” napisz „uruchom npm test przed commitem”.
- **Krótko.** Poniżej 200 linii na plik. Dłuższy plik zajmuje więcej kontekstu, a według dokumentacji Claude rzadziej stosuje jego zasady.
- **Bez sprzeczności.** Gdy dwie instrukcje sobie przeczą, Claude może wybrać dowolną z nich, więc stare zapisy regularnie usuwam.
- **Notatki dla ludzi w komentarzach.** Blokowe komentarze HTML są usuwane przed wczytaniem i nie zajmują kontekstu.

Na co dzień pracuję z Claude Code, także przy tym serwisie. Przegląd pliku zaczynaj od zasad zbyt ogólnych, bo takich nie da się sprawdzić.

## Jak podzielić długi CLAUDE.md na importy i reguły?

Długi CLAUDE.md dzielisz importami @ i plikami w katalogu.claude/rules, ale kontekst oszczędzają tylko reguły z polem paths.

- **Import @ścieżka.** Zapis @docs/git.md dołącza wskazany plik. Ścieżka względna liczy się od pliku z importem, a zagnieżdżenie kończy się na czterech poziomach. Zaimportowany plik ładuje się razem z CLAUDE.md.
- **Katalog.claude/rules.** Jeden plik.md na temat, na przykład testy albo styl API. Reguła bez pola paths ładuje się na starcie.
- **Reguły z polem paths.** Reguła z wzorcem ścieżek trafia do kontekstu dopiero wtedy, gdy Claude czyta lub edytuje pasujący plik, na przykład migrację bazy danych.

Gdy CLAUDE.md projektu importuje plik spoza katalogu roboczego, Claude Code przy pierwszym takim imporcie w projekcie prosi o zgodę.

## Kiedy Claude Code czyta AGENTS.md zamiast CLAUDE.md?

Claude Code czyta AGENTS.md, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md ani CLAUDE.local.md. Gdy są oba pliki, domyślnie czyta tylko CLAUDE.md, chyba że CLAUDE.md importuje AGENTS.md.

AGENTS.md to otwarty format instrukcji, z którego korzysta między innymi Codex od OpenAI. Jeśli w repozytorium pracuje kilka agentów, wspólne zasady mogą zostać w AGENTS.md, a CLAUDE.md dołącza je importem @AGENTS.md i dodaje uwagi tylko dla Claude Code. Na Windows import jest pewniejszy niż dowiązanie symboliczne. Konfigurację dla obu agentów i różnice w ich uprawnieniach opisuję na stronie [Claude Code czy Codex](https://szymonlakomy.pl/claude-code-czy-codex).

## Czego nie wkładać do CLAUDE.md?

Sekrety, długie procedury i zakazy bez wyjątków mają lepsze miejsca niż CLAUDE.md.

| Zamiast w CLAUDE.md | Gdzie to trzymać |
| --- | --- |
| hasła i klucze API | sejf na hasła albo zmienne środowiskowe, do tego reguła deny na odczyt plików.env |
| wieloetapowa procedura, na przykład wydanie wersji | skill w.claude/skills, wczytywany dopiero przy pasującym zadaniu |
| zakaz bez wyjątków, na przykład wypychania na gałąź main | hook PreToolUse albo reguła deny w.claude/settings.json |
| zasady jednego modułu | reguła z polem paths w.claude/rules |

Zdanie w CLAUDE.md jest prośbą, a hook i reguła deny są blokadą. Działanie hooków opisuję na stronie [hooki w Claude Code](https://szymonlakomy.pl/hooki-w-claude-code). Procedury zespołu opisuję na stronie [Skills w Claude dla firmy](https://szymonlakomy.pl/skills-w-claude-dla-firmy), a polecenia ukryte w treściach z zewnątrz na stronie [prompt injection](https://szymonlakomy.pl/prompt-injection).

## Przykładowy szkielet CLAUDE.md

Szkielet CLAUDE.md dla nowego repozytorium to sześć nagłówków po kilka linii (przykład hipotetyczny dla aplikacji webowej):

1. **Opis projektu.** Co to za aplikacja, w jakim stosie i dla kogo.
2. **Polecenia.** Uruchomienie, testy, build i lint.
3. **Architektura.** Najważniejsze katalogi i miejsce konfiguracji.
4. **Zasady.** Nazewnictwo, obsługa błędów, miejsce stałych i tekstów.
5. **Pułapki.** Pliki generowane, wolne testy, moduły do zmiany tylko po uzgodnieniu.
6. **Przed zakończeniem zadania.** Testy przechodzą, kompilacja bez błędów, opis zmiany gotowy.

Pomoc przy CLAUDE.md, uprawnieniach i pierwszych skillach rozliczam według stawki 150 do 200 zł netto za godzinę. Szersze wdrożenie opisuje strona [Claude Code w firmie](https://szymonlakomy.pl/claude-code-w-firmie).

## Źródła

Opis opieram na poniższych źródłach. Przepisy, dokumentacja producentów i warunki usług się zmieniają, więc szczegóły warto sprawdzić u źródła:

- [How Claude remembers your project](https://code.claude.com/docs/en/memory) (Anthropic)
- [Settings files and precedence](https://code.claude.com/docs/en/settings) (Anthropic)
- [Hooks reference](https://code.claude.com/docs/en/hooks) (Anthropic)

## Najczęstsze pytania

### Gdzie powinien leżeć plik CLAUDE.md w projekcie?

Plik CLAUDE.md projektu umieszczasz w katalogu głównym repozytorium albo jako.claude/CLAUDE.md. Plik trafia do gita, więc cały zespół pracuje z tymi samymi instrukcjami, a osobiste uwagi zapisujesz w CLAUDE.local.md dopisanym do.gitignore.

### Jak długi może być CLAUDE.md?

Dokumentacja Claude Code zaleca mniej niż 200 linii na plik, bo dłuższy plik zużywa więcej kontekstu i jest słabiej przestrzegany. Nadmiar przenieś do reguł z polem paths albo do skilli.

### Czy Claude Code czyta plik AGENTS.md?

Claude Code czyta AGENTS.md tylko wtedy, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md ani CLAUDE.local.md. Gdy są oba pliki, domyślnie czyta tylko CLAUDE.md, więc wspólny plik dołączasz importem @AGENTS.md.

### Czy Claude Code zawsze przestrzega CLAUDE.md?

Nie. CLAUDE.md jest dla Claude kontekstem, a nie wymuszoną konfiguracją, więc przy długim albo sprzecznym pliku część zasad może zostać pominięta. Zakaz bez wyjątków, na przykład czytania plików.env, ustawiasz regułą deny w pliku ustawień albo hookiem PreToolUse.

## Powiązane strony

- [Claude Code w firmie](https://szymonlakomy.pl/claude-code-w-firmie)
- [Claude Code czy Codex](https://szymonlakomy.pl/claude-code-czy-codex)
- [Skills w Claude dla firmy](https://szymonlakomy.pl/skills-w-claude-dla-firmy)
- [Prompt injection](https://szymonlakomy.pl/prompt-injection)
- [Bezpieczeństwo agentów AI](https://szymonlakomy.pl/bezpieczenstwo-agentow-ai)
- [Programista AI na zlecenie](https://szymonlakomy.pl/programista-ai-na-zlecenie)
- [Naprawa aplikacji napisanej przez AI](https://szymonlakomy.pl/naprawa-aplikacji-napisanej-przez-ai)

## Chcesz uporządkować CLAUDE.md w swoim repozytorium?

Napisz, w jakim stosie pracuje zespół i z jakich agentów korzysta. Pomogę przygotować CLAUDE.md, ustawienia uprawnień i pierwsze skille.

[Bezpłatna wycena](https://szymonlakomy.pl/kontakt?temat=ai) [697 322 226](tel:697322226) [LinkedIn](https://www.linkedin.com/in/szymon-%C5%82akomy-7a1192361/)
