Reguły w Claude Code: .claude/rules i filtry paths

O czym to jest

Claude Code czyta plik CLAUDE.md na początku każdej sesji. To miejsce na instrukcje dla agenta: jak zbudować projekt, jak pisać teksty, czego nie ruszać. Na początku plik jest krótki, ale z czasem rośnie. Dochodzą zasady pisania testów, styl kodu, wymagania dla konfiguracji, reguły dla dokumentacji. Wszystko to agent dostaje za każdym razem, nawet gdy poprawia jedną literówkę w readme.md. Co warto wpisać do CLAUDE.md i jak wygląda jego hierarchia (globalny, projektowy, w podkatalogu), opisuje Agenci AI #2, w części o CLAUDE.md . Zarządzanie kontekstem przez agenta omawia Agenci AI #4 — Pamięć i kontekst .

Claude Code ma na to osobny mechanizm: reguły (rules). To zwykłe pliki Markdown w katalogu .claude/rules/. Każda reguła opisuje jeden temat i może się ładować tylko wtedy, gdy agent pracuje z plikiem, którego dotyczy. Ten wpis pokazuje, jak taki plik wygląda, gdzie może leżeć i jak opisać, do których plików ma się odnosić.

Jak wygląda reguła

Każda reguła to osobny plik Markdown (z rozszerzeniem .md) w katalogu .claude/rules/. Takich katalogów może być kilka (o tym niżej). Najprostszy układ wygląda tak:

moj-projekt/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── styl-pisania.md
        ├── terminologia.md
        └── dane-poufne.md

W najprostszej postaci reguła to po prostu fragment CLAUDE.md przeniesiony do osobnego pliku. Taka reguła ładuje się na starcie każdej sesji. Nie oszczędza miejsca w kontekście, ale porządkuje instrukcje: zamiast jednego pliku na 400 linii powstaje kilka krótkich, tematycznych.

Inaczej działa reguła, która na początku ma nagłówek (frontmatter) z polem paths:

---
paths:
  - "oferty/**/*.md"
---

# Oferty dla klientów

- Zaczynaj od problemu klienta, nie od opisu firmy.
- Ceny podawaj netto, z dopiskiem „+ VAT”.
- Każda oferta kończy się terminem ważności i danymi kontaktowymi.

Taka reguła nie trafia do kontekstu na starcie. Agent dostaje ją dopiero wtedy, gdy otworzy, utworzy lub zmieni plik pasujący do wzorca, np. oferty/2026/kowalski.md. Jeśli przez całą sesję pracuje tylko nad notatkami ze spotkań, zasad dla ofert w ogóle nie zobaczy.

paths to jedyne pole, które Claude Code odczytuje z nagłówka reguły. Inne pola, np. description: czy priority:, są po cichu ignorowane. Jeśli YAML w nagłówku zawiera błąd składni, reguła traci filtr i ładuje się w każdej sesji.

Gdzie mogą leżeć reguły

Reguły mogą leżeć w trzech miejscach:

~/.claude/rules/                      # reguły użytkownika: wszystkie projekty na tym komputerze
└── moje-teksty.md                    # paths: "**/*.md"

firma/
├── .claude/rules/                    # reguły projektu
│   ├── ton-komunikacji.md            # bez paths: ładuje się zawsze
│   └── dokumenty/                    # podkatalog tylko dla porządku
│       └── oferty.md                 # paths: "oferty/**" → firma/oferty/...
└── dzialy/prawny/
    ├── .claude/rules/                # reguły jednego działu
    │   └── umowy.md                  # paths: "umowy/**" → firma/dzialy/prawny/umowy/...
    └── umowy/...

Z tego układu wynika kilka zasad:

• Podkatalogi w rules/ nie zmieniają zakresu reguły. dokumenty/oferty.md działa tak samo jak oferty.md. O tym, kiedy reguła się ładuje, decyduje wyłącznie paths.
• Wzorce liczą się od katalogu, w którym leży .claude. Reguła działu prawnego z umowy/** dopasuje dzialy/prawny/umowy/najem.md, ale nie dzialy/marketing/umowy/influencer.md. Każdy dział pisze więc reguły tak, jakby jego katalog był osobnym projektem.
• Reguły użytkownika obowiązują wszędzie i ładują się przed regułami projektu. Ich wzorce liczą się od katalogu, w którym uruchomiono sesję, więc **/*.md zadziała w każdym projekcie z plikami Markdown.
• Reguły się nie nadpisują. Jeśli reguła użytkownika i reguła projektu mówią co innego, Claude może zastosować dowolną z nich, więc trzeba dbać o ich spójność.

Filtry paths

Wzorce działają podobnie jak w .gitignore:

• * to dowolny ciąg znaków w obrębie jednej nazwy (bez /), ** to dowolna liczba podkatalogów,
• {a,b} to kilka wariantów w jednym wzorcu,
• [0-9] to jeden znak z podanego zakresu,
• / na początku przypina wzorzec do katalogu głównego.

Lista działa jak „lub”: reguła ładuje się, gdy pasuje którykolwiek wzorzec. Kilka przykładów:

---
paths:
  - "config/series.yaml"               # jeden konkretny plik
  - "Dockerfile"                       # plik o tej nazwie na dowolnym poziomie
  - "**/*.py"                          # wszystkie pliki .py w projekcie
  - "*.md"                             # .md na każdym poziomie (wzorzec bez /)
  - "/*.md"                            # .md tylko w katalogu głównym
  - "src/components/*.tsx"             # tylko ten katalog, bez podkatalogów

  - "src/**/*.{ts,tsx}"                # = src/**/*.ts i src/**/*.tsx
  - "**/*.{test,spec}.{ts,js}"         # 4 warianty plików testów
  - "**/{docker-compose,compose}*.{yml,yaml}"

  - "migrations/[0-9][0-9][0-9][0-9]_*.py"   # 0042_add_index.py, ale nie helpers.py
  - "blog_data/20[0-9][0-9]/*.md"      # tylko katalogi z rokiem, bez blog_data/szkolenia/

  - 'assets/photos \[2024]/**'         # dosłowny nawias w nazwie: backslash i pojedynczy cudzysłów
---

Kilka rzeczy, o których warto pamiętać:

• Brak wykluczeń. Dokumentacja nie opisuje składni typu !blog_data/szkolenia/**, więc zamiast wykluczać katalog, trzeba zawęzić wzorzec (jak w przykładzie z 20[0-9][0-9]).
• Limit 1000 wariantów na regułę. Każda grupa klamer mnoży liczbę wariantów. Wzorzec, który przekroczyłby limit, nie jest rozwijany i nie pasuje do żadnego pliku. Wzorce bez klamer się nie liczą.

Reguły, CLAUDE.md czy skill

Claude Code ma kilka sposobów przekazywania instrukcji. Różnią się tym, gdzie leżą i kiedy agent je dostaje.

Więcej o skillach: Skille w Claude Code i Agenci AI #5 .

Przykłady zastosowania

Jak sprawdzić, czy reguła działa

Podsumowanie

• Reguła to plik .md w .claude/rules/ (w projekcie, także w podkatalogu) albo w ~/.claude/rules/ (dla wszystkich projektów użytkownika).
• Jedyne pole odczytywane z nagłówka to paths. Bez niego reguła ładuje się zawsze, z nim tylko przy pracy z pasującymi plikami.
• Wzorce liczą się względem katalogu, w którym leży .claude, a w regułach użytkownika względem katalogu, w którym uruchomiono sesję.
• Błędnie zapisany nagłówek po cichu zamienia regułę warunkową w globalną, więc wzorce warto zawsze brać w cudzysłów (wzorzec bez cudzysłowu zaczynający się od * lub { psuje składnię YAML).
• *, **, klamry i nawiasy kwadratowe wystarczą, żeby opisać praktycznie każdą grupę plików.