# CARL — Dynamiczne reguły dla Claude Code

[CARL](https://github.com/ChristopherKahler/carl) (Context Augmentation & Reinforcement Layer) to system wstrzykiwania reguł do Claude Code — reguły ładują się **tylko gdy są potrzebne**, zamiast zapychać kontekst sesji regułami, których akurat nie używasz.

Zainstalowany globalnie w `~/.carl/`.

---

## Jak to działa

Claude Code ma ograniczony kontekst sesji. CARL rozwiązuje problem "zbyt wielu reguł na raz":

- **Domeny** — zestawy reguł uruchamiane automatycznie przez słowa kluczowe w prompcie
- **Star-commands** (`*dev`, `*review`, itp.) — tryby uruchamiane ręcznie przez wpisanie `*nazwatrybe`
- **Global** — reguły zawsze aktywne (minimalne, uniwersalne)

Efekt: zamiast 50 reguł na każdą sesję, Claude dostaje 5–10 tych, które są relevantne teraz.

---

## Struktura plików

```
~/.carl/                  # Globalna konfiguracja (wszystkie projekty)
├── manifest              # Rejestr domen (stany + słowa kluczowe)
├── global                # Reguły zawsze aktywne
├── commands              # Definicje star-commands
├── context               # Reguły kontekstowe (rozmiar okna kontekstu)
└── {nazwa-domeny}        # Twoja domena (bez rozszerzenia!)

.carl/                    # Konfiguracja lokalna (tylko ten projekt)
└── {nazwa-domeny}        # Reguły specyficzne dla shopPRO
```

**Ważne:** Nazwy plików domen — **małe litery, bez rozszerzenia** (`phpdev`, nie `phpdev.carl`).

---

## Dostępne star-commands

Wpisz `*nazwa` na początku wiadomości lub w środku promptu, żeby przełączyć tryb:

| Komenda | Tryb | Kiedy używać |
|---------|------|-------------|
| `*dev` | Development | Implementacja, szybkie zmiany bez tłumaczeń |
| `*review` | Code review | Przegląd kodu, bezpieczeństwo, edge cases |
| `*brief` | Zwięzłe odpowiedzi | Tylko bullet points, bez elaboracji |
| `*plan` | Planowanie | Eksploracja przed implementacją, opcje + tradeoffs |
| `*discuss` | Dyskusja | Burza mózgów, wiele podejść, bez skakania do kodu |
| `*debug` | Debugowanie | Systematyczna diagnoza, root cause analysis |
| `*explain` | Wyjaśnianie | Nauka, koncepty, stopniowe budowanie wiedzy |
| `*carl` | Pomoc CARL | Zarządzanie domenami, konfiguracja, pytania o CARL |

### Przykłady

```
*dev Napraw błąd w summaryView() gdzie duplikuje zamówienia

*review Przejrzyj OrderRepository::createFromBasket pod kątem bezpieczeństwa

*brief Co robi CacheHandler::deletePattern()

*plan Chcę dodać system rabatów do koszyka

*discuss Czy lepiej rozdzielić ApiloRepository na sync i admin?
```

---

## Tworzenie własnej domeny (projekt)

Kiedy masz zestaw reguł specyficznych dla shopPRO, utwórz lokalną domenę w `.carl/`.

### Krok 1 — Plik domeny

Utwórz `.carl/shoppro` (bez rozszerzenia):

```
# shopPRO Domain Rules
SHOPPRO_RULE_0=PHP < 8.0 — nie używaj match, named args, union types, str_contains
SHOPPRO_RULE_1=ORM: Medoo ($mdb), zawsze prepared statements, nigdy string concatenation
SHOPPRO_RULE_2=Namespace \Domain\ mapuje do autoload/Domain/ (D uppercase, a lowercase)
SHOPPRO_RULE_3=Testy: PHPUnit 9.6, pattern AAA, mock Medoo przez createMock(\medoo::class)
SHOPPRO_RULE_4=Cache: CacheHandler::deletePattern() do kasowania, TTL 86400, dane serialized
```

### Krok 2 — Wpis w manifeście

Dodaj do `.carl/manifest` (lub `~/.carl/manifest` jeśli globalna):

```
SHOPPRO_STATE=active
SHOPPRO_RECALL=shopPRO, medoo, zamówienie, koszyk, OrderRepository, Domain
SHOPPRO_EXCLUDE=
SHOPPRO_ALWAYS_ON=false
```

- `RECALL` — słowa kluczowe które triggerują domenę (przecinek = OR)
- `ALWAYS_ON=true` — ładuj przy każdym prompcie (tylko dla naprawdę universalnych reguł)
- `EXCLUDE` — słowa które blokują domenę mimo dopasowania RECALL

### Krok 3 — Weryfikacja

Wpisz `*carl` w czacie i zapytaj: _"Pokaż mi aktywne domeny"_.

---

## Zarządzanie przez Claude

Zamiast ręcznie edytować pliki, możesz zarządzać CARL przez Claude:

```
*carl Dodaj domenę dla testów PHPUnit w shopPRO

*carl Pokaż moją aktualną konfigurację

*carl Wyłącz domenę SHOPPRO tymczasowo

*carl Dodaj regułę do domeny dev: zawsze uruchamiaj ./test.ps1 po zmianach
```

Claude użyje skills `carl:manager` / `carl:tasks:*` do operacji na plikach.

---

## Integracja z PAUL

CARL i [PAUL](./PAUL_WORKFLOW.md) działają uzupełniająco:

- **PAUL** strukturyzuje *proces* (plan → apply → unify)
- **CARL** dostarcza *reguły domenowe* wtedy gdy są potrzebne

Praktycznie: podczas `/paul:apply` możesz prefixować `*dev` żeby Claude skupił się na kodzie bez elaboracji. Podczas `/paul:discuss` — `*discuss` żeby dostać pełną analizę opcji.

---

## Dobre praktyki

- **RECALL słowa** — używaj konkretnych, rzadkich słów żeby unikać false triggers. `medoo` lepsze niż `php`.
- **Mało reguł per domena** — 5–8 reguł to optymalnie. Więcej = wolniejsze matching, więcej tokenów.
- **ALWAYS_ON=false** domyślnie — ALWAYS_ON=true tylko dla reguł naprawdę universalnych (jak GLOBAL).
- **Star-commands przy dużych taskach** — na początku sesji wpisz `*dev` lub `*plan` żeby ustawić tryb.
- **Nie duplikuj CLAUDE.md** — CARL nie zastępuje CLAUDE.md. CLAUDE.md to architektura projektu. CARL to reguły zachowania Claude.

---

*Docs: 2026-03-12*