148 lines
5.3 KiB
Markdown
148 lines
5.3 KiB
Markdown
# 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*
|