update
This commit is contained in:
Jacek
147
docs/CARL_WORKFLOW.md
Normal file
147
docs/CARL_WORKFLOW.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user