Optymalizacja CLAUDE.md: Wskazówki 16-25

Pliki CLAUDE.md są fundamentem efektywnego użycia Claude Code. Dostarczają trwałej pamięci pomiędzy sesjami, ustanawiają kontekst projektu i dramatycznie poprawiają jakość asysty Claude’a. Te 10 wskazówek pomoże ci stworzyć pliki CLAUDE.md, które przekształcą twój przepływ pracy rozwoju.

Zrozumienie plików CLAUDE.md

Pliki CLAUDE.md służą jako system trwałej pamięci Claude Code. W przeciwieństwie do historii rozmów, która zostaje wyczyszczona, te pliki są automatycznie ładowane na początku każdej sesji, zapewniając spójny kontekst o twoim projekcie.

Kluczowe korzyści

• Trwały kontekst: Informacje pozostają pomiędzy sesjami i członkami zespołu
• Zmniejszone użycie tokenów: Nie ma potrzeby wielokrotnego wyjaśniania szczegółów projektu
• Zgodność zespołu: Wspólne zrozumienie konwencji projektu
• Lepsza jakość wyników: Claude podąża za twoimi specyficznymi wzorcami i preferencjami
• Szybsze wdrażanie: Nowi członkowie zespołu szybciej się wprowadzają

Strategiczne umieszczenie i struktura

Wskazówka 16: Twórz strategiczne pliki CLAUDE.md

Pliki CLAUDE.md mogą być umieszczane na wielu poziomach w hierarchii twojego projektu. Claude Code automatycznie je odkrywa i priorytetyzuje na podstawie specyficzności:

project-root/
├── CLAUDE.md                    # Globalny kontekst projektu
├── ~/.claude/CLAUDE.md          # Osobiste globalne preferencje
├── frontend/
│   └── CLAUDE.md               # Wytyczne specyficzne dla frontendu
├── backend/
│   └── CLAUDE.md               # Wzorce backendowe
└── src/
    └── components/
        └── CLAUDE.md           # Konwencje na poziomie komponentów

Kolejność priorytetów (najspecyficzniejszy wygrywa):

1. CLAUDE.md w aktualnym katalogu
2. CLAUDE.md w katalogu nadrzędnym (rekurencyjnie w górę do root)
3. CLAUDE.md w katalogu głównym projektu
4. ~/.claude/CLAUDE.md w katalogu domowym

Główny CLAUDE.md

# Przegląd projektu

To jest platforma e-commerce zbudowana z Next.js i Node.js.

## Architektura
- Frontend: Next.js 14 z App Router
- Backend: Node.js z Express
- Baza danych: PostgreSQL z Prisma ORM
- Uwierzytelnianie: JWT z refresh tokenami
- Zarządzanie stanem: Zustand

## Kluczowe zasady
- TypeScript dla całego nowego kodu
- Komponenty funkcyjne z hookami
- Projektowanie RESTful API
- Kompleksowa obsługa błędów

Specyficzny dla frontendu

# Wytyczne frontendu

## Struktura komponentów
- Używaj komponentów funkcyjnych z TypeScript
- Interfejsy props zdefiniowane nad komponentem
- Niestandardowe hooki w katalogu `/hooks`
- Współdzielone komponenty w `/components/shared`

## Stylowanie
- Tailwind CSS dla wszystkich stylów
- Brak stylów inline poza wartościami dynamicznymi
- Wymagane wsparcie dla trybu ciemnego
- Responsive design z podejściem mobile-first

Osobiste globalne

# Osobiste preferencje

## Styl kodu
- Preferuj wczesne zwroty nad zagnieżdżone warunki
- Używaj opisowych nazw zmiennych (bez skrótów)
- Komentarze dla "dlaczego", nie "co"
- Maksymalna długość linii: 100 znaków

## Przepływ pracy Git
- Format conventional commits
- Squash commitów przed mergowaniem
- Zawsze twórz gałęzie funkcji

Wskazówka 17: Używaj funkcji auto-generowania

Claude Code może automatycznie wygenerować kompleksowy plik CLAUDE.md poprzez analizę twojego projektu:

claude
/init

Ta komenda:

• Skanuje strukturę twojego projektu
• Identyfikuje frameworki i biblioteki
• Wykrywa wzorce kodowania
• Analizuje istniejącą dokumentację
• Tworzy dostosowany plik CLAUDE.md

Po wygenerowaniu, dostosuj go dodając:

• Konwencje specyficzne dla zespołu
• Wyjaśnienia logiki biznesowej
• Decyzje architektoniczne
• Uwagi dotyczące wydajności

Wskazówka

Uruchamiaj /init okresowo w miarę ewolucji projektu, aby uchwycić nowe wzorce i zaktualizować dokumentację.

Wskazówka 18: Dokumentuj często używane komendy

Umieść często używane komendy i skrypty, aby zmniejszyć przełączanie kontekstu:

# Często używane komendy

## Rozwój
- `npm run dev` - Uruchom serwer deweloperski (port 3000)
- `npm run build` - Zbuduj na produkcję
- `npm run test` - Uruchom pakiet testów
- `npm run test:watch` - Uruchom testy w trybie obserwacji
- `npm run lint` - Uruchom ESLint z auto-naprawą
- `npm run typecheck` - Uruchom sprawdzanie kompilatora TypeScript

## Baza danych
- `npm run db:migrate` - Uruchom oczekujące migracje
- `npm run db:seed` - Uzupełnij danymi deweloperskimi
- `npm run db:reset` - Zresetuj bazę danych (UWAGA: destrukcyjne)
- `npm run db:studio` - Otwórz Prisma Studio

## Wdrożenie
- `npm run deploy:staging` - Wdróż na staging (wymaga VPN)
- `npm run deploy:prod` - Wdróż na produkcję (wymaga zatwierdzenia)

## Niestandardowe skrypty
- `./scripts/generate-types.sh` - Generuj typy TypeScript z API
- `./scripts/analyze-bundle.sh` - Analizuj rozmiar bundla webpack
- `./scripts/update-deps.sh` - Interaktywny aktualizator zależności

Profesjonalna wskazówka

Umieść kontekst o tym, kiedy i dlaczego używać każdej komendy, nie tylko co robią.

Wskazówka 19: Ustal wytyczne stylu kodu

Udokumentuj standardy kodowania i preferencje twojego zespołu jasno:

# Wytyczne stylu kodu

## TypeScript
- **ZAWSZE** używaj jawnych typów zwracanych dla funkcji
- **ZAWSZE** definiuj interfejsy dla props komponentów
- **PREFERUJ** type nad interface dla unii i prymitywów
- **UNIKAJ** typu any - używaj unknown i zawężania typów

Przykład:
\`\`\`typescript
// ✅ Dobrze
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

const Button: React.FC<ButtonProps> = ({ label, onClick, variant = 'primary' }) => {
  return <button className={styles[variant]} onClick={onClick}>{label}</button>;
};

// ❌ Źle
const Button = ({ label, onClick, variant }: any) => {
  return <button onClick={onClick}>{label}</button>;
};
\`\`\`

## Organizacja importów
1. Zewnętrzne zależności
2. Aliasy wewnętrzne (~/)
3. Importy relatywne (./)
4. Importy stylów

Przykład:
\`\`\`typescript
import React, { useState, useEffect } from 'react';
import { useRouter } from 'next/router';

import { api } from '~/lib/api';
import { Button } from '~/components/ui';

import { formatDate } from './utils';
import styles from './Component.module.css';
\`\`\`

## Obsługa błędów
- Używaj niestandardowych klas błędów
- Zawsze loguj błędy z kontekstem
- Zapewniaj przyjazne użytkownikowi komunikaty błędów
- Umieszczaj granice błędów dla komponentów React

Wskazówka 20: Umieść etykietę repozytorium

Udokumentuj praktyki zespołowe i przepływy pracy dla zapewnienia spójności:

# Etykieta repozytorium

## Przepływ pracy Git
1. **Nazewnictwo gałęzi**: `feature/opis`, `fix/opis`, `chore/opis`
2. **Komunikaty commitów**: Podążaj za conventional commits
   - `feat:` Nowa funkcja
   - `fix:` Naprawa błędu
   - `docs:` Tylko dokumentacja
   - `style:` Zmiany stylu kodu
   - `refactor:` Refaktoryzacja kodu
   - `test:` Zmiany testów
   - `chore:` Zmiany procesu budowy lub narzędzi pomocniczych

## Proces Pull Request
1. **Samo-przegląd**: Najpierw przejrzyj własny PR
2. **Opis**: Używaj szablonu PR, linkuj do issue
3. **Testy**: Wszystkie testy muszą przejść
4. **Zrzuty ekranu**: Umieść dla zmian UI
5. **Rozmiar**: Utrzymuj PR poniżej 400 linii gdy to możliwe

## Wytyczne przeglądu kodu
- Bądź konstruktywny i konkretny
- Sugeruj ulepszenia, nie tylko krytykuj
- Używaj "my" zamiast "ty" w komentarzach
- Zatwierdź z "LGTM" (Looks Good To Me)

## Strategia merge'owania
- **Squash and merge** dla gałęzi funkcji
- **Rebase** dla aktualizacji gałęzi funkcji
- **Brak commit merge'ów** w głównej gałęzi

Techniki optymalizacji treści

Wskazówka 21: Dokumentuj wymagania konfiguracji środowiska

Pomóż Claude zrozumieć twoje środowisko deweloperskie:

# Środowisko deweloperskie

## Wymagania wstępne
- Node.js 18.x lub wyższy (użyj nvm)
- PostgreSQL 14.x
- Redis 6.x (do cache'owania)
- Docker Desktop (opcjonalnie, dla kontenerów)

## Początkowa konfiguracja
1. Sklonuj repozytorium: `git clone <repo-url>`
2. Zainstaluj zależności: `npm install`
3. Skopiuj zmienne środowiskowe: `cp .env.example .env`
4. Skonfiguruj plik .env:
   - DATABASE_URL: String połączenia PostgreSQL
   - REDIS_URL: String połączenia Redis
   - JWT_SECRET: Wygeneruj za pomocą `openssl rand -base64 32`
   - API_KEY: Uzyskaj od lidera zespołu
5. Uruchom migracje: `npm run db:migrate`
6. Uzupełnij bazę danych: `npm run db:seed`
7. Uruchom deweloperski: `npm run dev`

## Zmienne środowiskowe
- **Deweloperskie**: Używaj .env.local (git-ignored)
- **Testowe**: Używaj .env.test
- **Produkcyjne**: Ustaw na platformie wdrożeniowej

## Znane problemy
- Hot reload może zawieść na Windows - zrestartuj serwer dev
- Port 3000 konflikty z innymi usługami - zmień w .env
- Połączenia z bazą danych mogą się wyczerpać - zwiększ rozmiar puli

Wskazówka 22: Dodaj ostrzeżenia specyficzne dla projektu

Udokumentuj pułapki i nieoczywiście zachowania:

# ⚠️ Ważne ostrzeżenia

## Uwagi dotyczące wydajności
- **Strona listy produktów**: Ogranicza do 50 elementów ze względu na wydajność
- **Przesyłanie obrazów**: Automatycznie kompresowane, max 5MB
- **Indeksowanie wyszukiwania**: Działa asynchronicznie, może potrwać 30 sekund
- **Inwalidacja cache**: Wymagane ręczne wyzwolenie dla niektórych operacji

## Uwagi bezpieczeństwa
- **Klucze API**: Nigdy nie commituj do repozytorium
- **Dane użytkowników**: PII musi być szyfrowane w spoczynku
- **Przesyłanie plików**: Waliduj typy MIME po stronie serwera
- **Zapytania SQL**: Używaj tylko zapytań sparametryzowanych

## Częste pułapki
1. **Zarządzanie stanem**
   - Nie mutuj stanu Zustand bezpośrednio
   - Używaj immer dla złożonych aktualizacji

2. **Wywołania API**
   - Zawsze obsługuj stany loading i error
   - Używaj AbortController do sprzątania

3. **Zapytania do bazy danych**
   - Zapytania N+1 częste w dashboardzie użytkownika
   - Używaj includes dla powiązanych danych

4. **Testowanie**
   - Mockuj usługi zewnętrzne
   - Resetuj bazę danych między pakietami testów

Uwaga

Utrzymuj ostrzeżenia aktualne w miarę odkrywania nowych problemów. Claude będzie je pamiętać i unikać częstych błędów.

Wskazówka 23: Używaj klawisza # do dynamicznych aktualizacji

Claude Code zapewnia szybki sposób aktualizacji plików CLAUDE.md podczas rozwoju:

# Podczas sesji Claude Code, naciśnij # i wpisz:
Zawsze używaj klas Tailwind do stylowania, nigdy stylów inline

# Claude odpowiada:
Dodam to do najbardziej odpowiedniego pliku CLAUDE.md.

Ta funkcja:

• Automatycznie określa najlepszy plik CLAUDE.md do aktualizacji
• Dodaje instrukcję w odpowiedniej sekcji
• Utrzymuje formatowanie i strukturę
• Działa zarówno dla nowych reguł jak i poprawek

Częste zastosowania:

• Dodawanie odkrytych wzorców
• Korygowanie nieporozumień
• Dokumentowanie decyzji podjętych podczas rozwoju
• Przechwytywanie preferencji zespołu

Wskazówka 24: Dopracowuj instrukcje jak prompty

Traktuj treść CLAUDE.md jak prompty - bądź konkretny i używaj wyróżnień:

Słabe instrukcje

# Wytyczne

Używaj TypeScript dla plików.

Podążaj za przewodnikiem stylu.

Pisz testy.

Mocne instrukcje

# Krytyczne wytyczne

**ZAWSZE** używaj TypeScript z włączonym trybem strict dla WSZYSTKICH plików.

**MUSISZ** podążać za przewodnikiem stylu Airbnb z naszymi modyfikacjami:
- Wcięcie 2 spacje (NIE taby)
- Średniki wymagane
- Przecinki końcowe w multilinii

**WYMAGANE** dla każdej funkcji:
- Testy jednostkowe z pokryciem >80%
- Testy integracyjne dla endpointów API
- Testy E2E dla krytycznych ścieżek użytkownika

**NIGDY**:
- Nie używaj słowa kluczowego var (używaj const/let)
- Nie commituj stwierdzeń console.log
- Nie wyłączaj reguł ESLint bez komentarza

Efektywne wzorce instrukcji:

• ZAWSZE/NIGDY dla reguł nie podlegających negocjacji
• PREFERUJ/UNIKAJ dla mocnych rekomendacji
• ROZWAŻ dla sugestii
• Przykłady do wyjaśnienia oczekiwań

Wskazówka 25: Przepuść przez ulepszacz promptów

Okresowo optymalizuj swoje pliki CLAUDE.md używając technik ulepszania promptów Anthropic:

1. Wyodrębnij treść swojego CLAUDE.md

   cat CLAUDE.md > claude-md-content.txt

2. Użyj Claude do jego ulepszenia

   Ulepsz ten plik CLAUDE.md, aby był bardziej efektywny dla Claude Code.
   Uczyń instrukcje jaśniejszymi, dodaj pomocne przykłady i lepiej zorganizuj:
   
   [wklej treść]

3. Skup się na ulepszeniach takich jak:

   • Jaśniejsza organizacja sekcji
   • Bardziej konkretne instrukcje
   • Lepsze przykłady
   • Usunięcie dwuznaczności
   • Dodanie kontekstu

4. Przetestuj ulepszoną wersję

   • Uruchom nową sesję Claude Code
   • Sprawdź czy instrukcje są poprawnie wykonywane
   • Iteruj na podstawie wyników

Lista kontrolna optymalizacji

• Czytelne nagłówki sekcji z celem
• Konkretne, wykonalne instrukcje
• Przykłady dla złożonych koncepcji
• Ostrzeżenia dla częstych błędów
• Linki do dodatkowych zasobów
• Regularne przeglądy i aktualizacje

Podsumowanie najlepszych praktyk

Najefektywniejsze pliki CLAUDE.md dzielą te charakterystyki:

1. Struktura hierarchiczna: Używaj wielu plików dla różnych kontekstów
2. Żywa dokumentacja: Aktualizuj regularnie w miarę ewolucji projektu
3. Zgodność zespołu: Udostępniaj i wersjonuj pliki CLAUDE.md
4. Jasne przykłady: Pokaż, nie tylko powiedz
5. Konkretne instrukcje: Bądź jawny co do oczekiwań
6. Bogate w kontekst: Umieść “dlaczego” za decyzjami
7. Integracja narzędzi: Dokumentuj niestandardowe narzędzia i skrypty
8. System ostrzeżeń: Podkreśl pułapki i niebezpieczeństwa
9. Regulny przegląd: Optymalizuj na podstawie rzeczywistego użycia
10. Szybkie aktualizacje: Używaj klawisza # do natychmiastowych ulepszeń

Następne kroki

Z dobrze zoptymalizowanymi plikami CLAUDE.md dostarczającymi kontekst, jesteś gotowy opanować interfejs linii komend. Przejdź do Mistrzostwo linii komend, aby nauczyć się podstawowych komend i skrótów produktywności.