Zasady agentów (.cursorrules / CLAUDE.md / AGENTS.md)

1. Przegląd koncepcji i problem systemowy

Współczesne LLM są trenowane na gigabajtach otwartego kodu z GitHuba, dlatego domyślnie generują „przeciętny” kod: przestarzałe wersje major bibliotek, chaotyczne wzorce importów, any w TypeScript lub nieefektywne podejścia do obsługi błędów. Gdy inżynier pracuje w paradygmacie vibe-codingu bez utrwalonych reguł, każdy nowy prompt staje się loterią:

• Agent instaluje przestarzały moment.js lub axios zamiast natywnych date-fns czy fetch.
• Agent miesza warstwy architektoniczne (np. odwołuje się bezpośrednio do bazy danych z komponentu React po stronie klienta).
• Agent wymyśla własne komendy kompilacji lub testowania zamiast używania istniejących skryptów projektowych.

Agent Rules (pliki .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) rozwiązują problem dryfu bazy kodu. Przekształcają one wewnętrzne konwencje zespołu w kontrakt systemowy, który jest odczytywany przez środowisko deweloperskie lub agenta terminalowego jeszcze przed rozpoczęciem generowania jakiegokolwiek kodu.

2. Taksonomia architektury i model mentalny

Reguły repozytorium dzielą się na trzy poziomy izolacji i aktywacji:

┌─────────────────────────────────────────────────────────────┐
│                   POZIOMY ZASAD AGENTA                      │
├─────────────────────────────────────────────────────────────┤
│ 1. Warstwa globalna / maszynowa (~/.cursorrules, ~/.claude.json)   │
│    Preferencje konkretnego programisty (język, styl odpowiedzi)│
├─────────────────────────────────────────────────────────────┤
│ 2. Warstwa rdzenia repozytorium (CLAUDE.md, AGENTS.md, zasady główne)  │
│    Globalny stack technologiczny, zabronione biblioteki, komendy lint / test    │
├─────────────────────────────────────────────────────────────┤
│ 3. Zasady zakresowe / sterowane zdarzeniami (.cursor/rules/*.mdc)         │
│    Aktywacja na podstawie wzorca glob (np. trasy API, UI, baza danych)  │
└─────────────────────────────────────────────────────────────┘

1. Globalne reguły repozytorium (Core Repository Contract):
   • Znajdują się w katalogu głównym projektu (CLAUDE.md dla Claude Code, AGENTS.md lub .cursorrules dla edytorów).
   • Opisują krytyczne minimum: wersje środowiska (Node.js 22, Bun, Python 3.12), menedżer pakietów (pnpm), obowiązkowy linter oraz wytyczne dotyczące struktury commitów.
2. Kontekstowe reguły modułowe (Scoped Domain Rules):
   • Pliki z metadanymi i wzorcami glob (np. .cursor/rules/database.mdc z filtrem src/db/**/*.ts).
   • Są ładowane do pamięci roboczej modelu wyłącznie wtedy, gdy agent planuje edycję plików migracji lub modeli ORM.
3. Ograniczenia operacyjne (Operational Guardrails):
   • Jasne ograniczenia negatywne (Negative Constraints): „NIGDY nie wykonuj git push --force”, „NIGDY nie modyfikuj .env.production”, „NIE dodawaj nowych zależności bez wyraźnej zgody inżyniera”.

3. Pipeline techniczny i mechanika wewnętrzna

Cykl życia reguł podczas sesji vibe-codingu:

1. Inicjalizacja sesji i skanowanie repozytorium: IDE lub agent CLI podczas startu skanuje katalog główny oraz katalogi usługowe .cursor/rules/ lub .agents/rules/.
2. Analiza intencji i dopasowanie masek (Glob Matching): Użytkownik wysyła zapytanie („Utwórz nowy endpoint dla płatności subskrypcji”). Agent przewiduje zmiany plików w src/app/api/stripe/route.ts. Silnik reguł aktywuje zasady dla src/app/api/**/*.ts oraz stripe.mdc.
3. Konstrukcja rozszerzonego promptu systemowego: Silnik konkatenuje:
   • Bazowy System Prompt modelu;
   • Zawartość pliku globalnego kontraktu;
   • Znalezione reguły modułowe;
   • Aktualne drzewo otwartych plików oraz zapytanie użytkownika.
4. Generowanie kodu z wymuszonym przestrzeganiem invariantów: Model formułuje wywołanie narzędzia lub kod, traktując reguły jako obowiązkowy kontekst systemowy.
5. Walidacja post-generacyjna: Jeśli agent ma dostęp do terminala, uruchamia komendę walidacyjną zapisaną w regułach (np. pnpm typecheck) przed zwróceniem końcowego raportu inżynierowi.

4. Praktyczne scenariusze inżynierskie w produkcji

01. Granice architektoniczne w Next.js 15+ App Router

Plik .cursor/rules/nextjs.mdc z maską src/app/**/*.tsx zapobiega klasycznym błędom w użyciu komponentów serwerowych i klienckich:

---
description: Standardy architektoniczne Next.js App Router
globs: src/app/**/*.tsx, src/components/**/*.tsx
---
- Domyślnie wszystkie komponenty są Server Components.
- Dyrektywę 'use client' dodawaj WYŁĄCZNIE w przypadku użycia useState, useEffect lub obsług zdarzeń onClick/onChange.
- ZABRONIONE jest importowanie narzędzi serwerowych (db, auth secret) do plików z dyrektywą 'use client'.
- Wszystkie mutacje danych wykonuj wyłącznie za pośrednictwem Server Actions w katalogu `src/actions/`.

02. Deterministyczne uruchamianie testów dla Claude Code

Konfiguracja CLAUDE.md gwarantuje, że agent terminalowy korzysta wyłącznie z poprawnych skryptów testowych, unikając prób uruchomienia niezgodnego globalnego jest:

# Wytyczne dotyczące repozytorium dla Claude Code

## Polecenia
- Budowanie: `pnpm build`
- Sprawdzanie typów: `pnpm tsc --noEmit`
- Testy jednostkowe: `pnpm test:unit`
- Testy E2E: `pnpm test:e2e`

## Dyscyplina pracy
Przed zgłoszeniem pomyślnego wykonania zadania:
1. Uruchom `pnpm tsc --noEmit`. Jeśli występują błędy typowania — napraw je.
2. Uruchom `pnpm test:unit` dla zmodyfikowanych modułów.
3. Nie twórz nowych plików bez wcześniejszego sprawdzenia, czy w katalogu `src/lib/` nie istnieją już odpowiednie narzędzia pomocnicze (utility).

03. Wymuszenie bezpieczeństwa typów i walidacji Zod w API

Reguła dla backendu uniemożliwia wykorzystanie nietypizowanych payloadów JSON w kontrolerach:

---
description: Standaryzacja endpointów backendowych
globs: src/server/api/**/*.ts
---
- Wszystkie argumenty przychodzących żądań muszą być walidowane za pomocą schematów Zod (`schema.parseAsync(req.body)`).
- Typ `any` jest surowo zabroniony; w przypadku pracy z danymi o nieznanym kształcie należy używać typu `unknown` wraz z późniejszym zawężaniem typów (type narrowing).
- W razie wystąpienia błędów biznesowych należy rzucać sparametryzowany błąd `TRPCError` lub `HttpError` z odpowiednim kodem statusu HTTP.

5. Pułapki, typowe błędy i bezpieczeństwo

• Przerośnięte reguły (Rule Bloat & Attention Saturation): Próba umieszczenia całej dokumentacji projektu w pliku reguł prowadzi do plików przekraczających 500 linii. To rozprasza uwagę modelu („Lost in the Middle”) i powoduje, że model zaczyna ignorować kluczowe wytyczne. Rozbijajcie reguły na modułowe zakresy.
• Sprzeczne lub konflikujące reguły: Jeśli globalny CLAUDE.md wymaga użycia pnpm, a przestarzały README.md lub lokalna reguła zawiera npm install, model może wpadać w pętle halucynacji dotyczących menedżera pakietów.
• Ryzyko wycieku danych wrażliwych: Nigdy nie umieszczajcie tokenów dostępowych, haseł do baz testowych ani osobistych kluczy API w regułach repozytorium. Wszystkie zmienne środowiskowe powinny być opisywane jedynie jako abstrakcyjne nazwy (np. DATABASE_URL is required in .env.local).
• Brak wersjonowania: Reguły agentów muszą ewoluować wraz z bazą kodu w systemie kontroli wersji Git. Zmiana stacku technologicznego powinna towarzyszyć atomowej aktualizacji odpowiednich plików reguł w tym samym commicie.